Explore TFS API with TFS PowerShell Examples

Published:8 August 2019 - 2 min. read

If you’re using Microsoft’s Team Foundation Server (TFS) and you need to manage it with PowerShell, this post is for you. In this tutorial, you’re going to learn with TFS PowerShell examples, how to manage TFS. You never know, you might just want to take this knowledge and build a TFS PowerShell module from it!

TFS provides a rich API that can be used in conjunction with PowerShell to build a handy way to control TFS with the command line and via PowerShell script.

In this article, we’re going to cover the basics of what it takes to make that initial connection to TFS with PowerShell. The code you’ll be using can then be used to explore more API operations with PowerShell to build more advanced functionality.

Authenticating to TFS

To access the TFS REST API , you’ll first need to authenticate. In this TFS PowerShell example, use a PSCredential object. To create a PSCredential object, run Get-Credential and provide an account that has access to TFS

PS51> $credential = Get-Credential

Once you have a credential saved as a variable, then use this throughout numerous calls to the PowerShell cmdlet Invoke-RestMethod.

Invoke-RestMethod is a PowerShell cmdlet that allows us to craft and send various HTTP requests to REST APIs quickly. Since I’ll need to use the Credential parameter for each Invoke-RestMethod call, I’ll create a splatted parameter set with Credential inside so I don’t have to specify it every time.

$invRestMethParams = @{
    Credential = $credential
}

TFS PowerShell Example with Invoke-RestMethod

Now send a test query to TFS just to ensure you don’t receive an error. Try to retrieve all of the projects available to you on the server. You can do this by sending the HTTP GET method to the API. But first, you need to know the URI. To retrieve all of the projects, the URL scheme will look like this:

http(s)://<TFSServer>/<TeamCollection>/<TeamProject>/_apis/projects?api-version=2.0

You can see that I’m using v2.0 of the API. My particular URI looks like this:

$uri = 'http://tfs.domain.local:8080/tfs/IT/_apis/projects?api-version=2.0'

Now that you know the URI, you can then add this to the parameters to Invoke-RestMethod.

PS51> $invRestMethParams.Uri = $uri

Next, I’ll need to add the other parameters to Invoke-RestMethod.

$invRestMethParams.Method = 'Get'
$invRestMethParams.ContentType = 'application/json'

## My final parameters and the Invoke-RestMethod call will look like this:

$invRestMethParams = @{
    Credential = $credential
    Uri = $uri
    Method = 'Get'
    ContentType = 'application/json'
}
Invoke-RestMethod @invRestMethParams

When I run the above code, you’ll get an output that looks like this. This TFS PowerShell example uses Invoke-RestMethod to initiate an API request.

Finding TFS projects with PowerShell
Finding TFS projects with PowerShell

This isn’t too helpful. To get at what you’re looking for, you need to look at the contents of the value property. You’ll immediately see once you look at the value property, each of the projects inside of the collection will show up.

Drilling down on TFS projects
Drilling down on TFS projects

This means that you’ve authenticated to TFS and have queried the correct URI.

At this point, the world is your oyster. Perhaps you’d like to see all of the builds available to you. Because I’ve stored all of the parameters inside of the hashtable, I just have to change the Uri parameter. You could use the below TFS PowerShell example.

$invRestMethParams.Uri = 'http://tfs.domain.local:8080/tfs/IT/IS-DevOps/_apis/build/builds?api-version=2.0'
Finding TFS builds with PowerShell
Finding TFS builds with PowerShell

You can see that after you get authenticated and figure out the correct URL scheme, it’s just a matter of changing up the URL to do what you want. To learn a lot more about what you can do with the TFS REST API, I encourage you to check out the Visual Studio getting started documentation.

Next Steps

Using PowerShell, you can begin managing and automating many things with TFS. Managing TFS with PowerShell allows you to integrate various TFS processes into concepts like a CI/CD pipeline among other things.

Now take what you’ve learned and see if you can improve upon it by creating a TFS PowerShell module!

Hate ads? Want to support the writer? Get many of our tutorials packaged as an ATA Guidebook.

Explore ATA Guidebooks

Looks like you're offline!