Connection/Connection.psm1
|
<# .SYNOPSIS Connects to a Team Foundation Server configuration server. .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 . .LINK https://msdn.microsoft.com/en-us/library/vstudio/microsoft.teamfoundation.client.tfsconfigurationserver(v=vs.120).aspx #> Function Connect-TfsConfigurationServer { [CmdletBinding()] [OutputType([Microsoft.TeamFoundation.Client.TfsConfigurationServer])] Param ( [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)] [object] $Server, [Parameter(Position=1)] [System.Management.Automation.Credential()] [System.Management.Automation.PSCredential] $Credential, [Parameter()] [switch] $Passthru ) Process { $configServer = Get-TfsConfigurationServer -Server $Server -Credential $Credential if (-not $configServer) { throw "Error connecting to TFS" } $Global:TfsServerConnection = $configServer $Global:TfsServerConnectionCredential = $Credential if ($Passthru) { return $configServer } } } Function Connect-TfsTeamProject { [CmdletBinding()] [OutputType([Microsoft.TeamFoundation.WorkItemTracking.Client.Project])] Param ( [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)] [object] $Project, [Parameter()] [object] $Collection, [Parameter()] [System.Management.Automation.Credential()] [System.Management.Automation.PSCredential] $Credential, [Parameter()] [switch] $Passthru ) Process { $tp = (Get-TfsTeamProject -Project $Project -Collection $Collection -Credential $Credential | Select -First 1) if (-not $tp) { throw "Error connecting to team project $Project" } $Global:TfsProjectConnection = $tp Connect-TfsTeamProjectCollection -Collection $tp.Store.TeamProjectCollection if ($Passthru) { return $tp } } } <# .SYNOPSIS Connects to a TFS 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. Finally, if a TfsTeamProjectCollection object is provided via this argument, it will be used as the new default connection. This may be especially useful if you e.g. received a pre-initialized connection to a TFS collection via a call to an external library or API. For more details, see the -Collection argument in the Get-TfsTeamProjectCollection cmdlet. .PARAMETER Server Specifies either a URL or the name of the Team Foundation Server configuration server (the "root" of a TFS installation) to connect to, or a previously initialized Microsoft.TeamFoundation.Client.TfsConfigurationServer object. For more details, see the -Server argument in the Get-TfsConfigurationServer cmdlet. .PARAMETER Credential Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. To connect to Visual Studio Online you must enable Alternate Credentials for your user profile and supply that credential in this argument. For more information on Alternate Credentials for your Visual Studio Online account, please refer to https://msdn.microsoft.com/library/dd286572#setup_basic_auth. .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 default credentials of the logged-on user .LINK Get-TfsTeamProjectCollection .LINK https://msdn.microsoft.com/en-us/library/microsoft.teamfoundation.client.tfsteamprojectcollection.aspx #> Function Connect-TfsTeamProjectCollection { [CmdletBinding()] [OutputType([Microsoft.TeamFoundation.Client.TfsTeamProjectCollection])] Param ( [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)] [object] $Collection, [Parameter()] [object] $Server, [Parameter()] [System.Management.Automation.Credential()] [System.Management.Automation.PSCredential] $Credential, [Parameter()] [switch] $Passthru ) Process { $tpc = (Get-TfsTeamProjectCollection -Collection $Collection -Server $Server -Credential $Credential | Select -First 1) if (-not $tpc) { throw "Error connecting to team project collection $Collection" } $tpc.EnsureAuthenticated() $Global:TfsTpcConnection = $tpc $Global:TfsTpcConnectionCredential = $Credential Connect-TfsConfigurationServer -Server $tpc.ConfigurationServer if ($Passthru) { return $tpc } } } Function Disconnect-TfsConfigurationServer { Process { Remove-Variable -Name TfsServerConnection -Scope Global Remove-Variable -Name TfsServerConnectionUrl -Scope Global Remove-Variable -Name TfsServerConnectionCredential -Scope Global Remove-Variable -Name TfsServerConnectionUseDefaultCredentials -Scope Global } } Function Disconnect-TfsTeamProject { Process { Remove-Variable -Name TfsProjectConnection -Scope Global } } <# .SYNOPSIS Disconnects from the currently connected TFS Team Project Collection .DESCRIPTION The Disconnect-TfsTeamProjectCollection removes the global variable set by Connect-TfsTeamProjectCollection. Therefore, cmdlets relying on a "default collection" as provided by Connect-TfsTeamProjectCollection will no longer work after a call to this cmdlets, 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 { Process { Remove-Variable -Name TfsTpcConnection -Scope Global Remove-Variable -Name TfsTpcConnectionUrl -Scope Global Remove-Variable -Name TfsTpcConnectionCredential -Scope Global Remove-Variable -Name TfsTpcConnectionUseDefaultCredentials -Scope Global } } |