Заметки консультанта

Шамрай Александр Владимирович

Использование TFS REST API на примере решения для учета времени, потраченного на задачи

Posted by Шамрай Александр на Июль 14, 2016

На сегодняшний день TFS предоставляет следующие основные механизмы для взаимодействия со своими данными внешним приложениям:

  • TFS API на основе клиентский и серверных моделей взаимодействия, которые обеспечивают доступ ко всем необходимым функциям и объектам TFS. Для работы этого подхода необходимо иметь соответствующие библиотеки, которые позволят выполнять необходимые операции.
  • Командная строка tf, которая обеспечивает взаимодействие с сервером для операций с версионным контролем TFVC.
  • Набор инструментов TFS Power Tools дают дополнительные возможности для работы из командной строки для оперирования с рабочими элементами, запросами, а также дополнительные возможности для использования Power Shell.
  • TFS REST API взаимодействие с сервером TFS на основе запросов в формате Json. Этот механизм не настолько богат набором функций как первый, но является в общем достаточным для обеспечения интеграционных задач. Кроме этого плюсом данного механизма является то, что нет необходимости устанавливать клиентские библиотеки, а в случае с VS 2015 необходимо устанавливать всю студию, т.к. Team Explorer отдельно объектная модель не поставляется.

В рамках данного поста мы рассмотрим, как можно использовать Rest Api, чтоб получить информацию о рабочих элементах и зарегистрировать свои. Пример использования приложен к статье в виде таймтрекер клиента, который позволяет подсчитывать потраченное на активности время и привязывать это к конкретной задаче, ошибке и т.д. Основные операции, которые выполняются приложением через REST API:

  • Получение информации об активных рабочих элементах, назначенных на текущего пользователя.
  • Создание рабочего элемента Активность и его связывание с родительским рабочим элементом из предыдущего пункта.
  • Обновление информации о времени в родительском рабочем элементе.

Выполнение запросов к TFS

Взаимодействие с сервером TFS или службой VSO выполняется на основе HTTP запросов в формате JSON. Вся основная информация о доступных методах находится по следующему адресу: https://www.visualstudio.com/en-us/docs/integrate/api/overview

Для подключения к серверу и выполнения запросов используется HttpClient, пример использования которого отображен ниже:

В первой части функции организуется подключение в зависимости от настроек приложения. Можно выполнять подключение через значения имени и пользователя по умолчанию или указывать необходимые данные для авторизации. Во второй части выполняется создание асинхронных запросов со следующими методами:

  • GET – используется в основном для получения какой-либо информации, например, рабочего элемента или запроса по рабочим элементам.
  • POST – в рамках примера используется для выполнения запроса по рабочим элементам на основе Work item query language.
  • PATCH – для создания и обновления рабочих элементов. Т.к. данный пункт не реализован стандартными методами, то выполняется создание нового метода через new HttpMethod(«PATCH»).

Выполнение запросов на основе WIQL

В рамках примера WIQL используется для получения активных рабочих элементов. Подробнее можно посмотреть здесь: https://www.visualstudio.com/en-us/docs/integrate/api/wit/wiql.

Для выполнения запроса необходимо отправить запрос в соответствующей структуре и разобрать полученный ответ. Для этой цели можно использовать решение Newtonsoft.Json, которое позволяет быстро сформировать необходимые классы и налету преобразовывать их в соответствующий вид. Пример классов ниже.

  • Для формирования запроса используется класс с единственным свойством, которое будет содержать передаваемый запрос WIQL

  • Для получения ответа используется класс, который содержит информацию о запросе, его колонках, а также список workItems полученных рабочих элементов в виде их идентификаторов и ссылок на рабочие элементы.

Пример использования классов для получения необходимого списка рабочих элементов отображен ниже:

В начале функции идет формирование строки запроса, которая имеет изначальный следующий вид:

string QueryWisReq = «{Url сервера}/{Имя коллекции}/_apis/wit/wiql?api-version=1.0»;

Далее создается экземпляр класса для запроса по рабочим элементам и его свойству присваивается соответствующее значение, в нашем случае задается запрос, который отбирает все назначенные на исполнителя рабочие элементы в состоянии Активно. Следующим шагом выполняется преобразование класса в JSON формат и его передача в тело запроса к серверу TFS с использованием метода POST. Результат запроса преобразовывается в экземпляр класса FlatQueryResult, из которого мы получаем необходимый для нас список идентификаторов рабочих элементов.

Создание рабочего элемента

Подробную информацию о доступных методах для оперирования с рабочими элементами можно посмотреть здесь: https://www.visualstudio.com/en-us/docs/integrate/api/wit/work-items. При создании нового рабочего элемента задается запрос, который в своем теле несет информацию о новых атрибутах, включающие в себя:

  • Информацию о полях и их значениях:

  • Информацию о ссылках:


Пример использования классов для создания рабочих элементов отображен ниже:

В данном примере отображена функция, которая создает новый рабочий элемент и получает на вход наименование проекта, тип рабочего элемента, коллекцию полей и их значений, а также ссылку на родительский рабочий элемент, который будет сразу привязан при создании. Перед отправкой запроса на сервер выполняется создание списка полей NewField, который включается в себя следующие свойства:

  • op – отражает операцию с полем, при присваивании значения можно использовать выражение «add»;
  • path – путь к полю, которое формируется через слияние строк «/fields/» и имя-ссылка на поле;
  • value – содержимое поля при создании рабочего элемента.

Кроме этого добавляется информация о ссылках. В данном случае добавляется ссылка для родительского элемента с системным наименованием «System.LinkTypes.Hierarchy-Reverse», которая также является заблокированной, т.е. ее невозможно удалить стандартными средствами TFS:

_lnks.value.attributes.isLocked = true;

Для создания рабочего элемента формируется запрос:

string urlCreateWI = «{Url сервера}/{Имя коллекции}/{Имя проекта}/_apis/wit/workitems/${Тип рабочего элемента}?api-version=1.0»;

Результат запроса в свою очередь преобразовывается в экземпляр класса WorkItemAtrr, описание которого можно увидеть в исходно коде приложении для примера.

Исходный код приложения для примера

Для того, чтобы посмотреть подробнее как используют приведенные выше примеры, а также другие методы, можно перейти по ссылке https://tfstimetracker.codeplex.com/

Использование приложения, которое приведено для примера

Данное решение выработано на основе предыдущих статей по учету рабочего времени Организация управления расписаниями (Timesheet) в TFS и позволяет автоматизировать учет потраченных часов на выполнение поставленных задач. Приложение выполняет следующие основные функции:

  • Конфигурирование приложения. В данном случае необходимо указать путь к серверу и коллекцию, с которыми необходимо работать, отображаемое имя, по которому выполняется поиск активных назначенных на сотрудника рабочих элементов, а также, если необходимо, параметры авторизации. Кроме этого конфигурируются настройки по рабочим элементам: какой рабочий элемент отвечает за активность, какое состояние считается как «Активное», какие типы активностей могут использоваться.

Рисунок 1.Настройка параметров подключения к TFS

Рисунок 2. Настройка рабочих элементов

  • Выбор активных рабочих элементов и запуск подсчета времени. Решение выполняет поиск рабочих элементов по всем командным проектам и, когда пользователь выбрал необходимый, начинает подсчет времени. Также предусмотрена функция паузы, которую можно активировать нажатием соответствующей кнопки или активируется автоматически, если пользователь 10 минут ничего не делает за рабочим местом.

Рисунок 3. Выбор активных задач с помощью меню

  • Сохранение информации о затраченном времени. При нажатии на кнопку Стоп создается рабочий элемент (в примере Активность), который содержит информацию о времени, типе активности и комментарий. Также данный рабочий элемент связывается родительской связью с выбранной на предыдущем шаге задачей (или дефектом), в которой в свою очередь также обновляется информация о затраченном и оставшемся времени.

Рисунок 4. Сохранение информации о потраченном времени на задачу

Рисунок 5. Новая активность и родительская задача

Итог

Как видно из примера, использование REST API при работе с рабочими элементами обеспечивает достаточную функциональность и при этом невысокую сложность. Отдельным плюсом является то, что данный подход является кроссплатформенным без необходимости использования каких-либо отдельных клиентских библиотек.

Реклама

Добавить комментарий

Заполните поля или щелкните по значку, чтобы оставить свой комментарий:

Логотип WordPress.com

Для комментария используется ваша учётная запись WordPress.com. Выход / Изменить )

Фотография Twitter

Для комментария используется ваша учётная запись Twitter. Выход / Изменить )

Фотография Facebook

Для комментария используется ваша учётная запись Facebook. Выход / Изменить )

Google+ photo

Для комментария используется ваша учётная запись Google+. Выход / Изменить )

Connecting to %s

 
%d такие блоггеры, как: