Connection/Connection.ps1
|
<#
.SYNOPSIS Connects to a configuration server. .PARAMETER Server #Specifies either a URL/name of the Team Foundation Server to connect to, or a previously initialized TfsConfigurationServer object. When using a URL, it must be fully qualified. The format of this string is as follows: http[s]://<ComputerName>:<Port>/[<TFS-vDir>/] Valid values for the Transport segment of the URI are HTTP and HTTPS. If you specify a connection URI with a Transport segment, but do not specify a port, the session is created with standards ports: 80 for HTTP and 443 for HTTPS.nnTo connect to a Team Foundation Server instance by using its name, it must have been previously registered. .PARAMETER Credential Specifies a user account that has permission to perform this action. The default is the cached credential of the user under which the PowerShell process is being run - in most cases that corresponds to the user currently logged in. To provide a user name and password, and/or to open a input dialog to enter your credentials, call Get-TfsCredential with the appropriate arguments and pass its return to this argument. For more information, refer to https://msdn.microsoft.com/en-us/library/microsoft.teamfoundation.client.tfsclientcredentials.aspx .PARAMETER Interactive Prompts for user credentials. Can be used for any Azure DevOps account - the proper login dialog is automatically selected. Should only be used in an interactive PowerShell session (i.e., a PowerShell terminal window), never in an unattended script (such as those executed during an automated build). .PARAMETER Passthru Returns the results of the command. By default, this cmdlet does not generate any output. .DESCRIPTION The Connect-TfsConfigurationServer function connects to a TFS configuration server. Functions that operate on a server level (as opposed to those operation on a team project collection level) will use by default a connection opened by this function. .NOTES A TFS Configuration Server represents the server that is running Team Foundation Server. On a database level, it is represented by the Tfs_Configuration database. Operations that should be performed on a server level (such as setting server-level permissions) require a connection to a TFS configuration server. Internally, this connection is represented by an instance of the Microsoft.TeamFoundation.Client.TfsConfigurationServer class and is kept in a PowerShell global variable caled TfsServerConnection. .EXAMPLE Connect-TfsConfigurationServer -Server http://vsalm:8080/tfs Connects to the TFS server specified by the URL in the Server argument .EXAMPLE Connect-TfsConfigurationServer -Server vsalm Connects to a previously registered TFS server by its user-defined name "vsalm". For more information, see Get-TfsRegisteredConfigurationServer .INPUTS Microsoft.TeamFoundation.Client.TfsConfigurationServer System.String System.Uri .LINK Microsoft.TeamFoundation.Client.TfsConfigurationServer .LINK https://blogs.msdn.microsoft.com/taylaf/2010/02/23/introducing-the-tfsconnection-tfsconfigurationserver-and-tfsteamprojectcollection-classes/ #> Function Connect-TfsConfigurationServer { [CmdletBinding(DefaultParameterSetName="Explicit credentials")] [OutputType('Microsoft.TeamFoundation.Client.TfsConfigurationServer')] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingPlainTextForPassword', '')] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUsePSCredentialType', '')] Param ( [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)] [ValidateNotNull()] [object] $Server, [Parameter(ParameterSetName="Explicit credentials")] [object] $Credential, [Parameter(ParameterSetName="Prompt for credentials", Mandatory=$true)] [switch] $Interactive, [Parameter()] [switch] $Passthru ) Process { if ($PSCmdlet.ParameterSetName -eq 'Prompt for credentials') { $Credential = (Get-TfsCredential -Interactive) } $configServer = Get-TfsConfigurationServer -Server $Server -Credential $Credential if (-not $configServer) { throw "Error connecting to TFS" } $script:TfsTeamConnection = $null $script:TfsProjectConnection = $null $script:TfsTpcConnection = $null $script:TfsServerConnection = $configServer if ($Passthru) { return $configServer } } } <# .SYNOPSIS Connects to a team project. .DESCRIPTION The Connect-TfsTeamProject cmdlet "connects" (initializes a Microsoft.TeamFoundation.WorkItemTracking.Client.Project object) to a TFS Team Project. That connection is subsequently kept in a global variable to be later reused until it's closed by a call to Disconnect-TfsTeamProject. Cmdlets in the TfsCmdlets module that require a team project object to be provided via their -Project argument in order to access a TFS project will use the connection opened by this cmdlet as their "default project". In other words, TFS cmdlets (e.g. New-TfsArea) that have a -Project argument will use the connection provided by Connect-TfsTeamProject by default. .PARAMETER Project Specifies either the name of the Team Project or a previously initialized Microsoft.TeamFoundation.WorkItemTracking.Client.Project object to connect to. If omitted, it defaults to the connection opened by Connect-TfsTeamProject (if any). For more details, see the Get-TfsTeamProject cmdlet. .PARAMETER Collection Specifies either a URL/name of the Team Project Collection to connect to, or a previously initialized TfsTeamProjectCollection object. When using a URL, it must be fully qualified. The format of this string is as follows: http[s]://<ComputerName>:<Port>/[<TFS-vDir>/]<CollectionName> Valid values for the Transport segment of the URI are HTTP and HTTPS. If you specify a connection URI with a Transport segment, but do not specify a port, the session is created with standards ports: 80 for HTTP and 443 for HTTPS. To connect to a Team Project Collection by using its name, a TfsConfigurationServer object must be supplied either via -Server argument or via a previous call to the Connect-TfsConfigurationServer cmdlet. For more details, see the Get-TfsTeamProjectCollection cmdlet. .PARAMETER Credential Specifies a user account that has permission to perform this action. The default is the cached credential of the user under which the PowerShell process is being run - in most cases that corresponds to the user currently logged in. To provide a user name and password, and/or to open a input dialog to enter your credentials, call Get-TfsCredential with the appropriate arguments and pass its return to this argument. For more information, refer to https://msdn.microsoft.com/en-us/library/microsoft.teamfoundation.client.tfsclientcredentials.aspx .PARAMETER Interactive Prompts for user credentials. Can be used for any Azure DevOps account - the proper login dialog is automatically selected. Should only be used in an interactive PowerShell session (i.e., a PowerShell terminal window), never in an unattended script (such as those executed during an automated build). .PARAMETER Passthru Returns the results of the command. By default, this cmdlet does not generate any output. .INPUTS Microsoft.TeamFoundation.WorkItemTracking.Client.Project System.String .EXAMPLE Connect-TfsTeamProject -Project FabrikamFiber Connects to a project called FabrikamFiber in the current team project collection (as specified in a previous call to Connect-TfsTeamProjectCollection) .EXAMPLE Connect-TfsTeamProject -Project FabrikamFiber -Collection http://vsalm:8080/tfs/FabrikamFiberCollection Connects to a project called FabrikamFiber in the team project collection specified in the given URL #> Function Connect-TfsTeamProject { [CmdletBinding(DefaultParameterSetName="Explicit credentials")] [OutputType('Microsoft.TeamFoundation.WorkItemTracking.Client.Project')] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalVars', '')] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingPlainTextForPassword', '')] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '')] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUsePSCredentialType', '')] Param ( [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)] [ValidateNotNull()] [object] $Project, [Parameter()] [object] $Collection, [Parameter(ParameterSetName="Explicit credentials")] [object] $Credential, [Parameter(ParameterSetName="Prompt for credentials", Mandatory=$true)] [switch] $Interactive, [Parameter()] [switch] $Passthru ) Process { if ($Interactive.IsPresent) { $Credential = (Get-TfsCredential -Interactive) } $tp = (Get-TfsTeamProject -Project $Project -Collection $Collection -Credential $Credential | Select-Object -First 1) if (-not $tp) { throw "Error connecting to team project $Project" } $script:TfsTeamConnection = $null $script:TfsProjectConnection = $tp $script:TfsTpcConnection = $tp.Store.TeamProjectCollection $script:TfsServerConnection = $script:TfsTpcConnection.ConfigurationServer if ($Passthru) { return $tp } } } <# .SYNOPSIS Connects to a team project collection. .DESCRIPTION The Connect-TfsTeamProjectCollection cmdlet "connects" (initializes a Microsoft.TeamFoundation.Client.TfsTeamProjectCollection object) to a TFS Team Project Collection. That connection is subsequently kept in a global variable to be later reused until it's closed by a call to Disconnect-TfsTeamProjectCollection. Most cmdlets in the TfsCmdlets module require a TfsTeamProjectCollection object to be provided via their -Collection argument in order to access a TFS instance. Those cmdlets will use the connection opened by Connect-TfsTeamProjectCollection as their "default connection". In other words, TFS cmdlets (e.g. New-TfsWorkItem) that have a -Collection argument will use the connection provided by Connect-TfsTeamProjectCollection by default. .PARAMETER Collection Specifies either a URL/name of the Team Project Collection to connect to, or a previously initialized TfsTeamProjectCollection object. When using a URL, it must be fully qualified. The format of this string is as follows: http[s]://<ComputerName>:<Port>/[<TFS-vDir>/]<CollectionName> Valid values for the Transport segment of the URI are HTTP and HTTPS. If you specify a connection URI with a Transport segment, but do not specify a port, the session is created with standards ports: 80 for HTTP and 443 for HTTPS. To connect to a Team Project Collection by using its name, a TfsConfigurationServer object must be supplied either via -Server argument or via a previous call to the Connect-TfsConfigurationServer cmdlet. For more details, see the Get-TfsTeamProjectCollection cmdlet. .PARAMETER Server Specifies either a URL/name of the Team Foundation Server to connect to, or a previously initialized TfsConfigurationServer object. When using a URL, it must be fully qualified. The format of this string is as follows: http[s]://<ComputerName>:<Port>/[<TFS-vDir>/] Valid values for the Transport segment of the URI are HTTP and HTTPS. If you specify a connection URI with a Transport segment, but do not specify a port, the session is created with standards ports: 80 for HTTP and 443 for HTTPS.nnTo connect to a Team Foundation Server instance by using its name, it must have been previously registered. .PARAMETER Credential Specifies a user account that has permission to perform this action. The default is the cached credential of the user under which the PowerShell process is being run - in most cases that corresponds to the user currently logged in. To provide a user name and password, and/or to open a input dialog to enter your credentials, call Get-TfsCredential with the appropriate arguments and pass its return to this argument. For more information, refer to https://msdn.microsoft.com/en-us/library/microsoft.teamfoundation.client.tfsclientcredentials.aspx .PARAMETER Interactive Prompts for user credentials. Can be used for any Azure DevOps account - the proper login dialog is automatically selected. Should only be used in an interactive PowerShell session (i.e., a PowerShell terminal window), never in an unattended script (such as those executed during an automated build). .PARAMETER Passthru Returns the results of the command. By default, this cmdlet does not generate any output. .EXAMPLE Connect-TfsTeamProjectCollection -Collection http://tfs:8080/tfs/DefaultCollection Connects to a collection called "DefaultCollection" in a TF server called "tfs" using the cached credentials of the logged-on user .EXAMPLE Connect-TfsTeamProjectCollection -Collection http://tfs:8080/tfs/DefaultCollection -Interactive Connects to a collection called "DefaultCollection" in a Team Foundation server called "tfs", firstly prompting the user for credentials (it ignores the cached credentials for the currently logged-in user). It's equivalent to the command: PS> Connect-TfsTeamProjectCollection -Collection http://tfs:8080/tfs/DefaultCollection -Credential (Get-TfsCredential -Interactive) .LINK Get-TfsTeamProjectCollection .LINK https://msdn.microsoft.com/en-us/library/microsoft.teamfoundation.client.tfsteamprojectcollection.aspx .INPUTS Microsoft.TeamFoundation.Client.TfsTeamProjectCollection System.String System.Uri #> Function Connect-TfsTeamProjectCollection { [CmdletBinding(DefaultParameterSetName="Cached credentials")] [OutputType('Microsoft.TeamFoundation.Client.TfsTeamProjectCollection')] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalVars', '')] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingPlainTextForPassword', '')] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '')] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUsePSCredentialType', '')] Param ( [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)] [ValidateNotNull()] [object] $Collection, [Parameter(ParameterSetName="Cached credentials")] [switch] $Cached, [Parameter(ParameterSetName="User name and password", Mandatory=$true, Position=1)] [string] $UserName, [Parameter(ParameterSetName="User name and password", Position=2)] [securestring] $Password, [Parameter(ParameterSetName="Credential object", Mandatory=$true)] [ValidateNotNull] [object] $Credential, [Parameter(ParameterSetName="Personal Access Token", Mandatory=$true)] [Alias('Pat')] [string] $PersonalAccessToken, [Parameter(ParameterSetName="Prompt for credential", Mandatory=$true)] [switch] $Interactive, [Parameter()] [object] $Server, [Parameter()] [switch] $Passthru ) Begin { if ($PSVersionTable.PSEdition -ne 'Desktop') { throw "This cmdlet requires does not work in PowerShell Core. It uses TFS Client Object Model, which only works in Windows PowerShell" } #_ImportRequiredAssembly -AssemblyName 'Microsoft.TeamFoundation.Client' } Process { $tpc = $null if ($Collection -is [Microsoft.TeamFoundation.Client.TfsTeamProjectCollection]) { _Log "Collection argument is of type TfsTeamProjectCollection. Reusing object." $tpc = $Collection } else { _Log "Connecting with $($PSCmdlet.ParameterSetName)" if ($PSBoundParameters.ContainsKey('Collection')) { [void] $PSBoundParameters.Remove('Collection') } if ($PSBoundParameters.ContainsKey('Server')) { [void] $PSBoundParameters.Remove('Server') } if ($PSBoundParameters.ContainsKey('Passthru')) { [void] $PSBoundParameters.Remove('Passthru') } $creds = Get-TfsCredential @PSBoundParameters $tpc = Get-TfsTeamProjectCollection -Collection $Collection -Server $Server -Credential $Creds if (-not $tpc -or ($tpc.Count -ne 1)) { throw "Invalid or non-existent team project collection $Collection" } try { _Log "Calling TfsTeamProjectCollection.EnsureAuthenticated()" $tpc.EnsureAuthenticated() } catch { throw "Error connecting to team project collection $Collection ($_)" } } $script:TfsTeamConnection = $null $script:TfsProjectConnection = $null $script:TfsTpcConnection = $tpc $script:TfsServerConnection = $tpc.ConfigurationServer $script:AzDevTeamConnection = $null $script:AzDevProjectConnection = $null _Log "Connected to $($tpc.Uri)" if ($Passthru) { return $tpc } } } <# .SYNOPSIS Disconnects from the currently connected configuration server. .DESCRIPTION The Disconnect-TfsConfigurationServer cmdlet removes the global variable set by Connect-TfsConfigurationServer. Therefore, cmdlets relying on a "default server" as provided by "Get-TfsConfigurationServer -Current" will no longer work after a call to this cmdlet, unless their -Server argument is provided or a new call to Connect-TfsConfigurationServer is made. .EXAMPLE Disconnect-TfsConfigurationServer Disconnects from the currently connected TFS configuration server #> Function Disconnect-TfsConfigurationServer { [CmdletBinding()] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalVars', '')] Param ( ) Process { Disconnect-TfsTeamProjectCollection if ($script:TfsServerConnection) { Remove-Variable -Name TfsServerConnection -Scope Script } } } <# .SYNOPSIS Disconnects from the currently connected team project. .DESCRIPTION The Disconnect-TfsTeamProject cmdlet removes the global variable set by Connect-TfsTeamProject . Therefore, cmdlets relying on a "default project" as provided by "Get-TfsTeamProject -Current" will no longer work after a call to this cmdlet, unless their -Project argument is provided or a new call to Connect-TfsTeamProject is made. .EXAMPLE Disconnect-TfsTeamProject Disconnects from the currently connected TFS team project #> Function Disconnect-TfsTeamProject { [CmdletBinding()] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalVars', '')] Param ( ) Process { if ($script:TfsProjectConnection) { Remove-Variable -Name TfsProjectConnection -Scope Script } } } <# .SYNOPSIS Disconnects from the currently connected team project collection. .DESCRIPTION The Disconnect-TfsTeamProjectCollection cmdlet removes the global variable set by Connect-TfsTeamProjectCollection. Therefore, cmdlets relying on a "default collection" as provided by "Get-TfsTeamProjectCollection -Current" will no longer work after a call to this cmdlet, unless their -Collection argument is provided or a new call to Connect-TfsTeamProjectCollection is made. .EXAMPLE Disconnect-TfsTeamProjectCollection Disconnects from the currently connected TFS team project collection #> Function Disconnect-TfsTeamProjectCollection { [CmdletBinding()] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalVars', '')] Param ( ) Process { Disconnect-TfsTeamProject if ($script:TfsTpcConnection) { Remove-Variable -Name TfsTpcConnection -Scope Script } } } <# .SYNOPSIS Provides credentials to use when you connect to a Team Foundation Server or Visual Studio Team Services account. .DESCRIPTION .NOTES .INPUTS #> Function Get-TfsCredential { [CmdletBinding(DefaultParameterSetName="Cached credentials")] [OutputType('Microsoft.TeamFoundation.Client.TfsClientCredentials')] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingPlainTextForPassword', '')] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUsePSCredentialType', '')] Param ( [Parameter(ParameterSetName="Cached credentials")] [switch] $Cached, [Parameter(ParameterSetName="User name and password", Mandatory=$true, Position=1)] [string] $UserName, [Parameter(ParameterSetName="User name and password", Position=2)] [securestring] $Password, [Parameter(ParameterSetName="Credential object", Mandatory=$true)] [AllowNull()] [object] $Credential, [Parameter(ParameterSetName="Personal Access Token", Mandatory=$true)] [Alias('Pat')] [string] $PersonalAccessToken, [Parameter(ParameterSetName="Prompt for credential", Mandatory=$true)] [switch] $Interactive ) Process { $parameterSetName = $PSCmdlet.ParameterSetName if (($parameterSetName -eq 'Credential object') -and (-not $Credential)) { $parameterSetName = 'Cached Credentials' } $allowInteractive = $false switch($parameterSetName) { 'Cached Credentials' { $fedCred = New-Object 'Microsoft.TeamFoundation.Client.CookieCredential' -ArgumentList $true $winCred = New-Object 'Microsoft.TeamFoundation.Client.WindowsCredential' -ArgumentList $true } 'User name and password' { $netCred = New-Object 'System.Net.NetworkCredential' -ArgumentList $UserName, $Password $fedCred = New-Object 'Microsoft.TeamFoundation.Client.BasicAuthCredential' -ArgumentList $netCred $winCred = New-Object 'Microsoft.TeamFoundation.Client.WindowsCredential' -ArgumentList $netCred } 'Credential object' { if ($Credential -is [Microsoft.TeamFoundation.Client.TfsClientCredentials]) { return $Credential } if($Credential -is [pscredential]) { $netCred = $Credential.GetNetworkCredential() } elseif ($Credential -is [System.Net.NetworkCredential]) { $netCred = $Credential } else { throw "Invalid argument Credential. Supply either a PowerShell credential (PSCredential object) or a System.Net.NetworkCredential object." } $fedCred = New-Object 'Microsoft.TeamFoundation.Client.BasicAuthCredential' -ArgumentList $netCred $winCred = New-Object 'Microsoft.TeamFoundation.Client.WindowsCredential' -ArgumentList $netCred } 'Personal Access Token' { $netCred = New-Object 'System.Net.NetworkCredential' -ArgumentList 'dummy-pat-user', $PersonalAccessToken $fedCred = New-Object 'Microsoft.TeamFoundation.Client.BasicAuthCredential' -ArgumentList $netCred $winCred = New-Object 'Microsoft.TeamFoundation.Client.WindowsCredential' -ArgumentList $netCred } 'Prompt for credential' { $fedCred = New-Object 'Microsoft.TeamFoundation.Client.CookieCredential' -ArgumentList $false $winCred = New-Object 'Microsoft.TeamFoundation.Client.WindowsCredential' -ArgumentList $false $allowInteractive = $true } else { throw "Invalid parameter set $($PSCmdlet.ParameterSetName)" } } return New-Object 'Microsoft.TeamFoundation.Client.TfsClientCredentials' -ArgumentList $winCred, $fedCred, $allowInteractive } } |