Team settings are edited through the WorkHttpClient client, which includes team settings, boards, delivery plans, team performance, etc. In the context of this post, we will consider only the most frequently settings: an iteration path, an area path and team backlogs.
Before starting to work with team settings, you have to create a team context. To do this, you create a new TeamContext object with two parameters: a team project name and a team name. If we need to get a context of the default team, you can pass only a team project name. Create the default team context:
TeamContext teamContext = new TeamContext(TeamProjectName);
Iterations
By managing iterations, you can minimize a work of team administrators. If you are using shared iteration in all or many teams, you can add them automatically to all teams after you add iterations to your team project. You can also periodically clean old iterations, so they do not accumulate in team settings.
Before adding an iteration to a team, you have to add it to project settings. Creating of an iteration was described here: Manage Areas and Iterations in Team Projects.
The PostTeamIterationAsync method with the TeamSettingsIteration object and the context team as parameters will add iterations to a team. For a TeamSettingsIteration object is important only the unique ID of a iteration, which can be accessed through the GetClassificationNodeAsync method of the WorkItemTrackingHttpClient class. The example of adding an iteration:
WorkItemClassificationNode projectIt = WitClient.GetClassificationNodeAsync(TeamProjectName, TreeStructureGroup.Iterations, iterationName).Result; // get iteration from project
TeamSettingsIteration teamIt = WorkClient.PostTeamIterationAsync(new TeamSettingsIteration { Id = projectIt.Identifier }, teamContext).Result; //add iteration to a team by guid
Console.WriteLine(“Added iteration “ + teamIt.Name);
The DeleteTeamIterationAsync method removes an iteration from team settings with a team context and an ID of a iteration:
WorkItemClassificationNode projectIt = WitClient.GetClassificationNodeAsync(TeamProjectName, TreeStructureGroup.Iterations, iterationNameToRemove).Result;
WorkClient.DeleteTeamIterationAsync(teamContext, projectIt.Identifier).SyncResult(); //delete iteration from team settings by guid
Console.WriteLine(“Removed iteration “ + projectIt.Name);
With the GetTeamIterationsAsync method, you can view a set of team iterations. This method takes as parameters: a team context and an iteration time frame (past, present and future). The example of the method:
TeamSettingsIteration currentiteration = (WorkClient.GetTeamIterationsAsync(teamContext, “Current”).Result).FirstOrDefault();
The result is a TeamSettingsIteration object that contains:
- Id – an iteration GUID
- Name – an iteration name
- Path – an iteration path
-
Attributes – an additional iteration attributes:
- StartDate – a start date
- FinishDate – a finish date
- TimeFrame – an iteration timeframe: Past, Current, Future
The example:
List<TeamSettingsIteration> teamIterations = WorkClient.GetTeamIterationsAsync(teamContext).Result; //get all iterations
Console.WriteLine(“Team Iterations: “);
foreach (TeamSettingsIteration teamIteration in teamIterations)
Console.WriteLine(“{0} : {1} : {2}-{3}”, teamIteration.Attributes.TimeFrame, teamIteration.Name, teamIteration.Attributes.StartDate, teamIteration.Attributes.FinishDate);
Areas
Area makes sense to update automatically if you manage basic team responsibilities in an external system (CMDB, etc.) and they must be migrated into the relevant Azure DevOps Teams.
Before add area to a team, you have to add it to project settings (Manage Areas and Iterations in Team Projects).
You can view team areas through the method GetTeamFieldValuesAsync that will return a TeamFieldValues object with the following attributes:
- DefaultValue – a default area value.
- Values – an area list with TeamFieldValue objects that a team will control. The TeamFieldValue includes an area name (Value) and an attribute of including of subareas (IncludeChildren).
The example:
TeamFieldValues teamAreas = WorkClient.GetTeamFieldValuesAsync(teamContext).Result; //Get All Areas
Console.WriteLine(“Default Area: “ + teamAreas.DefaultValue);
Console.WriteLine(“Team Areas : “);
foreach (TeamFieldValue teamField in teamAreas.Values)
Console.WriteLine(“\t” + teamField.Value + ((teamField.IncludeChildren)? ” (include sub-areas)” : “”));
To update a set of areas, we have to use the UpdateTeamFieldValuesAsync method with the TeamFieldValuesPatch parameter. The TeamFieldValuesPatch class contains the same attributes as TeamFieldValues. Therefore, to update settings, you can get current values and add or remove the necessary ones:
string[] areas = { @”Application\WinClient”, @”Application\WebClient” };
TeamFieldValues currentTeamAreas = WorkClient.GetTeamFieldValuesAsync(teamContext).Result; // get current areas
TeamFieldValuesPatch teamAreasPatch = new TeamFieldValuesPatch();
List<TeamFieldValue> newTeamAreas = new List<TeamFieldValue>(currentTeamAreas.Values); // just copy old areas. Here we may remove unneeded areas
foreach (string area in areas)
newTeamAreas.Add(new TeamFieldValue { Value = TeamProjectName + “\\” + area, IncludeChildren = false }); // add new areas
teamAreasPatch.DefaultValue = currentTeamAreas.DefaultValue;
teamAreasPatch.Values = newTeamAreas;
TeamFieldValues updatedTeamAreas = WorkClient.UpdateTeamFieldValuesAsync(teamAreasPatch, teamContext).Result;
Common settings
Change common settings rarely may need through automation, perhaps if only basic team backlogs differ from the default settings and it is easier to change them automatically.
You can get current settings through the GetTeamSettingsAsync method, which returns TeamSetting with the attributes:
- DefaultIteration – an iteration that will be inserted into new work items in the team context.
- BacklogIteration – an iteration for a team requirements backlog.
- DefaultIterationMacro – a marco to define a current iteration: https://docs.microsoft.com/ru-ru/azure/devops/boards/queries/query-by-date-or-current-iteration?view=vsts#query-for-items-based-on-belonging-to-a-teams-current-iteration
- BacklogVisibilities – a backlog list that a team uses.
- WorkingDays – team working days.
The example:
TeamContext teamContext = new TeamContext(TeamProjectName, TeamName);
TeamSetting teamSetting = WorkClient.GetTeamSettingsAsync(teamContext).Result;
Console.WriteLine(“Settings for the team “ + TeamName);
Console.WriteLine(“Backlog Iteration : “ + teamSetting.BacklogIteration.Name);
Console.WriteLine(“Default Iteration : “ + teamSetting.DefaultIteration.Name);
Console.WriteLine(“Macro of Iteration : “ + teamSetting.DefaultIterationMacro);
Console.WriteLine(“Categories of backlog:”);
foreach(string bkey in teamSetting.BacklogVisibilities.Keys)
if (teamSetting.BacklogVisibilities[bkey]) Console.WriteLine(“\t” + bkey);
Console.WriteLine(“Working days :”);
foreach (var wday in teamSetting.WorkingDays) Console.WriteLine(“\t” + wday.ToString());
switch (teamSetting.BugsBehavior)
{
case BugsBehavior.AsRequirements:
Console.WriteLine(“Bugs Behavior: Bugs in a requirements backlog.”);
break;
case BugsBehavior.AsTasks:
Console.WriteLine(“Bugs Behavior: Bugs in a sprint backlog as tasks.”);
break;
case BugsBehavior.Off:
Console.WriteLine(“Bugs Behavior: Find bugs through queries.”);
break;
}
The UpdateTeamSettingsAsync method updates team settings with the TeamSettingsPatch parameter, which has the same attributes as TeamSetting. This method will update only initialized attributes in a TeamSettingsPatch object:
TeamSetting teamSetting = WorkClient.GetTeamSettingsAsync(teamContext).Result;
TeamSettingsPatch teamSettingsPatch = new TeamSettingsPatch();
teamSettingsPatch.BacklogVisibilities = teamSetting.BacklogVisibilities;
if (teamSettingsPatch.BacklogVisibilities.ContainsKey(“Microsoft.EpicCategory”) && teamSettingsPatch.BacklogVisibilities[“Microsoft.EpicCategory”])
teamSettingsPatch.BacklogVisibilities[“Microsoft.EpicCategory”] = false;
if (teamSettingsPatch.BacklogVisibilities.ContainsKey(“Microsoft.FeatureCategory”) && teamSettingsPatch.BacklogVisibilities[“Microsoft.FeatureCategory”])
teamSettingsPatch.BacklogVisibilities[“Microsoft.FeatureCategory”] = false;
teamSetting = WorkClient.UpdateTeamSettingsAsync(teamSettingsPatch, teamContext).Result;
The sample application:
https://github.com/ashamrai/TFRestApi/tree/master/10.TFRestApiAppManageTeamSettings
DevOps Notes 