Donovan Brown

Technology Blog

PowerShell I would like you to meet TFS and VSTS

11 January 2017 Donovan Work (51)

Today I released my first PowerShell module to the PowerShell Gallery called VSTeam. VSTeam is a PowerShell module that exposes portions of the REST API for Visual Studio Team Services and Team Foundation Server.

It is written in pure PowerShell and can be used on Mac, Linux or Windows to connect to TFS or VSTS.  To install VSTeam you can use the Install-Module cmdlet.  Just make sure on Windows you run PowerShell as administrator and on Mac or Linux you sudo your PowerShell session.  Then simply issue the following command.

PS> Install-Module -Name VSTeam

Once the module is installed you can view all the provided functions by running Get-Command.

PS>Get-Command -Module VSTeam

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Function        Add-AzureRMServiceEndpoint                         0.1.1      Team
Function        Add-Build                                          0.1.1      Team
Function        Add-BuildDefinition                                0.1.1      Team
Function        Add-Project                                        0.1.1      Team
Function        Add-ReleaseDefinition                              0.1.1      Team
Function        Add-TeamAccount                                    0.1.1      Team
Function        Clear-DefaultProject                               0.1.1      Team
Function        Get-Build                                          0.1.1      Team
Function        Get-BuildDefinition                                0.1.1      Team
Function        Get-CloudSubscription                              0.1.1      Team
Function        Get-Pool                                           0.1.1      Team
Function        Get-Project                                        0.1.1      Team
Function        Get-Queue                                          0.1.1      Team
Function        Get-ReleaseDefinition                              0.1.1      Team
Function        Get-ServiceEndpoint                                0.1.1      Team
Function        Get-TeamInfo                                       0.1.1      Team
Function        Remove-Build                                       0.1.1      Team
Function        Remove-BuildDefinition                             0.1.1      Team
Function        Remove-Project                                     0.1.1      Team
Function        Remove-ReleaseDefinition                           0.1.1      Team
Function        Remove-ServiceEndpoint                             0.1.1      Team
Function        Remove-TeamAccount                                 0.1.1      Team
Function        Set-DefaultProject                                 0.1.1      Team
Function        Update-Project                                     0.1.1      Team

This is just what is there now and more will follow.  Once I put a coat of polish on the module I will open source it on GitHub.

To get started with the module make sure and call Add-VSTeamAccount first.  This will require your Team Services account name or full TFS URL including collection and a Personal Access Token. VSTeam only supports TFS 2017, TFS 2018 and Team Services.

Comments (51) -

  • Donovan

    1/12/2017 2:20:27 AM | Reply

    If you are having trouble with Install-Module on Linux you can use
    Save-Module -Name Team -Path .
    Then
    Import-Module ./Team/0.1.4/team.psd1

  • Alex Sarafian

    1/12/2017 8:11:26 AM | Reply

    Looking at the cmdlet names it looks very cool and useful. Are there any plans to offer some sort of documentation and examples online? Maybe when the github repository goes public?

    • Donovan

      1/12/2017 12:37:23 PM | Reply

      There is documentation and examples in the functions. Use
      help get-releasedefinition
      for example.  I will continue to polish and improve the help.

      • Alex Sarafian

        1/16/2017 12:09:06 PM | Reply

        As I like to read documentation from a centralized location outside the console, I created this gist-script to share and hel pothers (gist.github.com/.../f6df9af26c365b34dda496d9dfad1043)

        Once you install the Team module, execute:

        Export-ModuleDocumentation.ps1 -Module Team

        Markdown files are available in your temp folder under a folder TeamDocumentation.

        • Donovan

          1/16/2017 1:07:42 PM | Reply

          Cool!

  • Evgeniy Savchenko

    1/15/2017 7:26:36 PM | Reply

    Nothing on GitHub by the link

    • Donovan

      1/15/2017 9:25:37 PM | Reply

      It will be there in a week or two. But to use it just fire up PowerShell and type Install-Module Team.

  • Andreas Heimel

    2/21/2017 7:58:17 AM | Reply

    Exactly what I was looking for, however, we're still running TFS 2015 Update 3. Is there any chance to get it working with this version?

    • Donovan

      2/21/2017 3:14:12 PM | Reply

      I am afraid not. But you will not regret the upgrade to 2017. It is really nice and worth the effort.

  • Rob Cannon

    2/23/2017 11:57:16 AM | Reply

    Are you still planning to put this in GitHub?

    • Donovan

      2/23/2017 2:05:47 PM | Reply

      Yes I am in the process of polishing the code and increasing code coverage with Pester.

  • Assaf Stone

    3/2/2017 9:59:41 PM | Reply

    Hi Donovan - this looks awesome!

    I've installed the module, and am able to run Add-TeamAccount, but when I try to Get-Project, or Get-BuildDefinition, I  get a 401 error (not authorized). I am the account owner, mind you, so I shouldn't be blocked.

    Any idea why this might be?

  • Donovan

    3/9/2017 12:47:46 AM | Reply

    what version are you using and are you adding tfs or vsts?

  • TILAK KUNDU

    2/13/2018 9:44:26 PM | Reply

    I am getting the following error while connecting to On-Premise TFS
    Command Used :- Add-TeamAccount -Account http://XXXX.XXX:8080/tfs/CB/_projects -UseWindowsAuthentication

    Error:-  Page not found. - Microsoft Team Foundation Server.......
    ......

    C:\Program Files\WindowsPowerShell\Modules\Team\0.1.34\src\buildDefinitions.psm1:118 char:17
    + ...     $resp = Invoke-RestMethod -UserAgent (_getUserAgent) -Uri $listur ...
    +                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        + CategoryInfo          : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], WebException
        + FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand
    The property 'value' cannot be found on this object. Verify that the property exists.
    At C:\Program Files\WindowsPowerShell\Modules\Team\0.1.34\src\buildDefinitions.psm1:124 char:27
    +          foreach($item in $resp.value) {
    +                           ~~~~~~~~~~~
        + CategoryInfo          : NotSpecified: (Smile [], PropertyNotFoundException
        + FullyQualifiedErrorId : PropertyNotFoundStrict

    The property 'value' cannot be found on this object. Verify that the property exists.
    At C:\Program Files\WindowsPowerShell\Modules\Team\0.1.34\src\buildDefinitions.psm1:128 char:10
    +          Write-Output $resp.value
    +          ~~~~~~~~~~~~~~~~~~~~~~~~
        + CategoryInfo          : NotSpecified: (Smile [], PropertyNotFoundException
        + FullyQualifiedErrorId : PropertyNotFoundStrict

    I tried using PAT instead of "-UseWindowsAuthentication" , but no luck. It is working just fine against my personal VSTS account using PAT.

    Any idea?

    • Illan RUL-DA CUNHA

      8/27/2018 1:57:47 PM | Reply

      Hello, Donovan,

      Thank you very much for that useful PS scripts. ;)

      Unfortunately, I have the same problem as TILAK KUNDU, I can't do anything because the script seems to not managing connecting to my on-premises TFS. I have the last version of your scripts.

      Do you have a workaround on that problem?

      Thank you, have a great week.

  • James

    3/22/2018 8:40:14 PM | Reply

    Is there a way to interact with the library variable groups found in "Build and Releases?" I would like to make copies of a template between my projects. For example if I have static values to pass between my webapp.config values.

  • Andrea Rizzioli

    7/5/2018 5:02:12 PM | Reply

    Hi,
    I would like to know if it is possible to change the releaseNameFormat  via script.
    Running the 2 lines below is not sufficient:
    $a = get-release -ProjectName projectname -top 1
    $a.releaseNameFormat = 'Release-$(Release.DefinitionName)-$(Date:yyMMdd)-$(Date:HH).$(Date:mm)-$(Rev:r)'
    Which other command should I run to commit the change?
    Thanks.

  • Mahesh Aravapalli

    7/6/2018 2:40:09 PM | Reply

    Can you please add Description and Assigned to fields also to the function "Add-VSTeamWorkItem" or please guide me which all files to change to add "Description" and "Assigned To" fields

  • Sam

    7/10/2018 12:36:09 PM | Reply

    PS C:\Windows\system32> Get-ExecutionPolicy -List

            Scope ExecutionPolicy
            ----- ---------------
    MachinePolicy       Undefined
       UserPolicy       Undefined
          Process       Undefined
      CurrentUser       Undefined
    LocalMachine       AllSigned


    PS C:\Windows\system32> Get-ExecutionPolicy
    AllSigned
    PS C:\Windows\system32> Set-ExecutionPolicy AllSigned

    Execution Policy Change
    The execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expos
    you to the security risks described in the about_Execution_Policies help topic at
    http://go.microsoft.com/fwlink/?LinkID=135170. Do you want to change the execution policy?
    [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"): Y
    PS C:\Windows\system32> Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

    Execution Policy Change
    The execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expos
    you to the security risks described in the about_Execution_Policies help topic at
    http://go.microsoft.com/fwlink/?LinkID=135170. Do you want to change the execution policy?
    [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"): Y
    PS C:\Windows\system32> Get-ExecutionPolicy -List

            Scope ExecutionPolicy
            ----- ---------------
    MachinePolicy       Undefined
       UserPolicy       Undefined
          Process          Bypass
      CurrentUser       Undefined
    LocalMachine       AllSigned


    PS C:\Windows\system32> Import-Module PowerShellGet
    PS C:\Windows\system32> Install-Module -Name VSTeam

    NuGet provider is required to continue
    PowerShellGet requires NuGet provider version '2.8.5.201' or newer to interact with NuGet-based repositories. The Nu
    provider must be available in 'C:\Program Files (x86)\PackageManagement\ProviderAssemblies' or
    'C:\Users\sthurai\AppData\Local\PackageManagement\ProviderAssemblies'. You can also install the NuGet provider by
    running 'Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force'. Do you want PowerShellGet to install
    and import the NuGet provider now?
    [Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): Y

    Untrusted repository
    You are installing the modules from an untrusted repository. If you trust this repository, change its
    InstallationPolicy value by running the Set-PSRepository cmdlet. Are you sure you want to install the modules from
    'PSGallery'?
    [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"): Y
    PS C:\Windows\system32> Get-Command -Module VSTeam

  • Anindita

    8/13/2018 10:01:38 AM | Reply

    Is there any way we can auto-merge code from one folder to another in VSTS

  • Javier

    8/14/2018 9:06:51 AM | Reply

    Hi Donovan, thanks for the module, is very useful sincerely. I was just wondering if there is any limitation that I can remove on the "Get-VSTeamRelease" as by default I get only 50 and defining a -top the max seems to be 100.

    Thanks for this really nice module.

    Bye!

  • Tim

    9/13/2018 12:13:52 PM | Reply

    Is there any way this can be integrated into Azure Automation?  Use case is triggering builds from there.  REST API is the other choice, but this would be nicer Smile

  • skewee

    11/7/2018 7:42:53 AM | Reply

    Hi Donovan,

    Thanks for this very powerful module.
    Any way to add Areas and Iterations before adding Work Items, so we can match with existing Areas and Iterations paths ?

    Best !

    • Donovan

      11/8/2018 3:26:46 PM | Reply

      I would add this as an issue in GitHub. The community supporting it might add that for you.

  • skewee

    11/12/2018 6:16:24 PM | Reply

    Hi Donovan,

    This PS syntax is working fine :

    Add-VSTeamWorkItem -Title "Manhattan Work Item" -WorkItemType Task -Description "This is a description" -AssignedTo "John Doe" -IterationPath "\\Myproject\Food\Iteration 1\"

    Result :
    ID  Title               State  
    --  -----               -----  
    135 Manhattan Work Item Proposed

    But how could we add other parameters as -AreaPath, -Priority, -Severity ?

    Best !

  • Brain2000

    12/11/2018 5:00:07 PM | Reply

    Hi Donovan! I'm really looking forward to working with this utility for our on premise TFS, as the tf.exe command is not able to do everything we want!

    I find that I keep getting a 404 not found on all of my calls. I'm running TFS 2017 Update 3. I went into IIS and disabled Windows Authentication, and I started getting a 401 Access Denied. So I know that my credentials are at least working (I put that back before anyone using Visual Studio or the web interface also received an access denied).

    I made sure the SPN was set on the TFS server, and tried both http and https connections (server has a valid SSL certificate). Same 404 either way.

    I also tried the PSDrive, but it also received the 404 error and listed three folders:

    PS TFS:\> dir
    WARNING: An error occurred: The remote server returned an error: (404) Not Found.

    Mode   Name
    ----   ----
    d-r-s- Agent Pools
    d-r-s- Extensions
    d-r-s- Feeds

    • Donovan

      12/13/2018 3:17:04 PM | Reply

      Run the command with -verb and send me the verbose text. That way I can see the form of the URL being used. I bet it is the url passed to add-account.

  • Dave

    1/4/2019 8:54:37 PM | Reply

    Is there a way to update a work item to change the column from In Progress to Done

    • Donovan

      1/5/2019 6:38:05 PM | Reply

      Are you wanting to change the state of the work item or customize the states?

      • Dave

        1/7/2019 1:37:36 PM | Reply

        I want to change the state to Done and add comments

        • Donovan

          1/7/2019 5:00:26 PM | Reply

          That you would do with an update call to the work item. It issues a HTTP Patch to the URL with the body being an array of the fields to update. The docs are here docs.microsoft.com/.../update

  • Gabriel McColl

    1/6/2019 9:04:26 PM | Reply

    Hi , love this work. I've been trying to figure out how to help add to it.
    e.g. to be able to download the release definition template for editing as an object or something.
    But honestly I'm too thick to figure out the very advanced setup with ShIPs and the common.ps1
    Can you maybe hook me up with a way to ramp onto helping with this , maybe explain the inter-connectivity if you haven't already. Link me if you have?
    appreciated thanks

  • Donovan

    4/2/2019 8:59:34 PM | Reply

    Post this on the GitHub repo so others might be able to help resolve this.

  • Dave

    4/15/2019 8:58:52 PM | Reply

    Donovan, hello-

    Am interested in getting the TFS work-item history objects, Description fields, completed, remaining hours, etc.

    Where's my most direct link in pulling these down from an Azure TFS repository?

    Thanks

  • Andrew Konopik

    6/13/2019 9:11:11 PM | Reply

    Thank you for this tool. Great features. I am having trouble create a workitem when I run:
    Add-VSTeamWorkItem -Title "New Work Item" -WorkItemType Task -Description "This is a description"

    I get the following "Rule Error for field Task Type"
    Invoke-RestMethod : {"$id":"1","customProperties":{"FieldReferenceName":null,"FieldStatusFlags":"none","ErrorMessage":"TF401320: Rule Error for field Task Type. Error
    code: Required, HasValues, LimitedToValues, AllowsOldValue, InvalidEmpty. One additional error occurred during validation of the work item. Please correct all errors and
    try again.","FieldStatusCode":0,"RuleValidationErrors":[{"fieldReferenceName":"Microsoft.VSTS.CMMI.TaskType","fieldStatusFlags":"required, hasValues, limitedToValues,
    allowsOldValue, invalidEmpty","errorMessage":"TF401320: Rule Error for field Task Type. Error code: Required, HasValues, LimitedToValues, AllowsOldValue,
    InvalidEmpty.","fieldStatusCode":524365,"ruleValidationErrors":null},{"fieldReferenceName":"OSG.Product","fieldStatusFlags":"required, hasValues, limitedToValues,
    allowsOldValue, invalidEmpty","errorMessage":"TF401320: Rule Error for field Product. Error code: Required, HasValues, LimitedToValues, AllowsOldValue,
    InvalidEmpty.","fieldStatusCode":524365,"ruleValidationErrors":null}]},"innerException":null,"message":"TF401320: Rule Error for field Task Type. Error code: Required,
    HasValues, LimitedToValues, AllowsOldValue, InvalidEmpty. One additional error occurred during validation of the work item. Please correct all errors and try
    again.","typeName":"Microsoft.TeamFoundation.WorkItemTracking.Server.RuleValidationException,
    Microsoft.TeamFoundation.WorkItemTracking.Server","typeKey":"RuleValidationException","errorCode":0,"eventId":3200}
    At C:\Program Files\WindowsPowerShell\Modules\VSTeam\6.2.6\Private\common.ps1:625 char:12
    +    $resp = Invoke-RestMethod @params
    +            ~~~~~~~~~~~~~~~~~~~~~~~~~
        + CategoryInfo          : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], WebException
        + FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand

    Everything else work. I can retrieve workitems just fine.

  • Rahul

    6/24/2019 4:11:58 AM | Reply

    How to get the latest version of the Code from DevOps to local folder, where I like to do some manipulation on my code?

  • Gert

    6/26/2019 6:27:39 AM | Reply

    The login instructions (Add-VSTeamAccount) seems to refer to a cmdlet that no longer exists (with that name). (Set-VSTeamAccount seems to be the correct command as of 6.2.0 (I need to upgrade, I know))

    Some info (like how to login and get a list of cmdlets) would be useful in the README.

    • Donovan

      7/14/2019 6:17:33 PM | Reply

      Thanks we will update the docs.

  • A Kumar

    9/23/2020 6:27:39 PM | Reply

    Getting error:

    PackageManagement\Install-Package : No match was found for the specified search criteria and module name 'VSTeam'. Try
    Get-PSRepository to see all available registered module repositories.
    At C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.0.0.1\PSModule.psm1:1809 char:21
    + ...          $null = PackageManagement\Install-Package @PSBoundParameters

  • P Dlaney

    12/30/2020 4:39:19 PM | Reply

    Can I use the Team Module to check in files into TFS 2018 (TFVC). The proposed workflow is that I have a team that generates XML configuration files. They want the files in TFVC for they can Diff them to see what is different. I'm trying to write a PowerShell that will take the file and upload it to a TFVC repo. I chose TFVC because one of the developers her say that TFVC handles xml files better than Git.  My issue is Can TFVC tell the difference between the initial file and and updated file with the came call? Or would I have to know before hand whether its a new file or existing?

    I'm not sure if there is a REAT call to check in to TFVC either

  • Jason McMahan

    8/9/2021 2:33:18 AM | Reply

    The module looks very extensive, one thing that i was unable to locate was deployment agent installation. At my current employer this was one cmdlet I am actively working to investigate. Is this something in the works or something I over looked?

    Thank you

    • Donovan

      8/27/2021 5:14:00 PM | Reply

      Be sure and log this as an issue on the repo. Someone in the community might be working on it. If not we accept pull requests if you would like to add that support.

  • Kishore

    3/8/2022 1:30:35 PM | Reply

    Hi Donovan,
    Can I get all users and groups from Azure Devops and version is 'Azure DevOps Server Version Dev17.M153.3', if yes, which cmdlets I can you to do the work.
    Thanks

Add comment

Loading