PowerShell I would like you to meet TFS and VSTS

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 (25) -

  • 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
  • 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?
    • There is documentation and examples in the functions. Use
      help get-releasedefinition
      for example.  I will continue to polish and improve the help.
      • 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.
  • Nothing on GitHub by the link
    • It will be there in a week or two. But to use it just fire up PowerShell and type Install-Module Team.
  • 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?
    • I am afraid not. But you will not regret the upgrade to 2017. It is really nice and worth the effort.
  • 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?
  • what version are you using and are you adding tfs or vsts?
  • 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?
  • 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.
  • 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.
  • 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
    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
  • Is there any way we can auto-merge code from one folder to another in VSTS
  • 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!

Add comment

Loading