Visual Studio Team Services

VSTS & TFS Rest API: 05 – Teams

While we are still quite top-level and just recently covered VSTS / TFS Project Collections and Projects, it’s worth taking a brief, initial detour towards Teams.
It’ll be brief only, because this post will only cover retrieving and deleting existing Teams but also creating new ones programmatically using the API – the Work related topics (Team assets, capacity and activity planning etc) will be covered in a Work-specific post later-on.

Teams in VSTS & TFS are exactly what the name suggests – a core concept and structural entity that groups users into one or more Team(s), typically each Team working on a specific Feature at a time and each user may be part of more than one team. Each Team can get and typically works with a focused view on their planned work and its progress but from a more global, aggregate bird’s-eye view of the overall product’s or project’s progress across multiple teams is also easily available.

However, as this is an introduction into the APIs for VSTS & TFS’s features, we’ll start by retrieving existing Team(s) of a given Project as this is where they are located. What you’ll need is

  • The URL of your Project Collection (see the previous post)
  • The Name or Id of the Project for which you want to retrieve (and later create and delete) Teams

Much like all other posts, the client library comes with a specific class that provides access to Teams-specific functionality, in this case it’s the TeamHttpClient one.

Retrieving existing Teams

// instantiate a vss connection using the Project Collection URI as Base Uri
var visualStudioServicesConnection = new VssConnection(new Uri(TeamProjectCollectionUri), new VssCredentials());

// Get a Team client
var teamHttpClient = visualStudioServicesConnection.GetClient<TeamHttpClient>();

// Retrieve existing Team(s)
// ##############################
// First lets retrieve the teams (first 10 again) for the given Project(Id)
var allTeams = teamHttpClient.GetTeamsAsync(ProjectId, 10, 0).Result;
foreach (var team in allTeams)
{
 Console.WriteLine("Team '{0}' (Id: {1})", team.Name, team.Id);
}

Retrieving Team Members

Besides retrieving the Teams, you can also retrieve the members of each team via the .GetTeamMembersAsync() method, i.e. like this:

// Retrieve Team Members
// ##############################
Console.WriteLine("Team with Id '{0}' contains the following member(s)", TeamIdKnownToContainMembers);
foreach (var identityReference in teamHttpClient.GetTeamMembersAsync(ProjectId, TeamIdKnownToContainMembers, 10, 0) .Result)
{
    Console.WriteLine("-- '{0}' (Id: {1})", identityReference.DisplayName, identityReference.Id);
}

Creating new Teams

Creaing new Teams is easily doable via the API, too, you’ll only need to provide the Name of the new Team and call the .CreateTeamAsync(..) method as shown below. Unlike other such activities, this one is not a queued job which we need to track its (completion or failure) progress for:

// Create Team(s)
// ##############################
var somewhatRandomValueForTeamName = (int)(DateTime.UtcNow - DateTime.UtcNow.Date).TotalSeconds;

// We can also create new Team(s), the minimum amount of information you have to provide is
var newTeam = new WebApiTeam()
{
 // .. only the .Name of the new Team
 // albeit it may NOT contain these characters: @ ~ ; ' + = , < > | / \ ? : & $ * " # [ ]
 // but i.e. whitespaces are just fine
 Name = $"My new Team {somewhatRandomValueForTeamName}"
};

// once we've prepared the team instance, we call the api endpoint using the teamHttpClient
var newlyCreatedTeam = teamHttpClient.CreateTeamAsync(newTeam, ProjectId).Result;

Console.WriteLine("Team '{0}' (Id: {1}) created", newlyCreatedTeam.Name, newlyCreatedTeam.Id);

Please note that new Teams are empty by default and adding members to that new Team seems to be.. well-hidden in the client at the moment – at least I couldn’t find it after digging around for a little while. It may not be (publicly) available in the API and REST endpoints just yet because the REST endpoint documentation also lacks any explanation if it’s possible or how to do it.
I’ll update this post whenever the functionality becomes available.

However, you can obviously manage Team members manually following the guidelines for VSTS & TFS.

Deleting Teams

Whenever you deem necessary, you can also delete Teams programmatically, i.e. like this:

// Delete Team(s)
// ##############################
// we can als delete existing Teams, i.e. the one we've just created
teamHttpClient.DeleteTeamAsync(ProjectId, newlyCreatedTeam.Id.ToString()).Wait();

Conclusion

Programmatically accessing and creating/deleting Team(s) is quite easy, you can similarly also update existing Team(s) via the .UpdateTeamAsync() method, but that only allows update(s) for .Name and .Description (not as mentioned above its Members).

The Work related functionality of VSTS and TFS which is closely tied to Teams will be covered in a later post, so stay tuned.

 

Index for all Posts | Full code is available at GitHub

Discussion

Comments disabled.