Connection/Connection.psm1
|
<# .SYNOPSIS Connects to a configuration server. .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 . #> Function Connect-TfsConfigurationServer { [CmdletBinding()] [OutputType([Microsoft.TeamFoundation.Client.TfsConfigurationServer])] Param ( [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)] [ValidateNotNull()] [object] $Server, [Parameter(Position=1)] [System.Management.Automation.Credential()] [System.Management.Automation.PSCredential] $Credential = [System.Management.Automation.PSCredential]::Empty, [Parameter()] [switch] $Passthru ) Process { $configServer = Get-TfsConfigurationServer -Server $Server -Credential $Credential if (-not $configServer) { throw "Error connecting to TFS" } $Global:TfsTeamConnection = $null $Global:TfsProjectConnection = $null $Global:TfsTpcConnection = $null $Global:TfsServerConnection = $configServer if ($Passthru) { return $configServer } } } <# .SYNOPSIS Connects to a team project. .PARAMETER Passthru Returns the results of the command. By default, this cmdlet does not generate any output. #> Function Connect-TfsTeamProject { [CmdletBinding()] [OutputType([Microsoft.TeamFoundation.WorkItemTracking.Client.Project])] Param ( [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)] [ValidateNotNull()] [object] $Project, [Parameter()] [object] $Collection, [Parameter()] [System.Management.Automation.Credential()] [System.Management.Automation.PSCredential] $Credential = [System.Management.Automation.PSCredential]::Empty, [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:TfsTeamConnection = $null $Global:TfsProjectConnection = $tp $Global:TfsTpcConnection = $tp.Store.TeamProjectCollection $Global:TfsServerConnection = $Global: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. 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)] [ValidateNotNull()] [object] $Collection, [Parameter()] [object] $Server, [Parameter()] [System.Management.Automation.Credential()] [System.Management.Automation.PSCredential] $Credential = [System.Management.Automation.PSCredential]::Empty, [Parameter()] [switch] $Passthru ) Process { $tpc = $null try { $tpc = (Get-TfsTeamProjectCollection -Collection $Collection -Server $Server -Credential $Credential | Select -First 1) $tpc.EnsureAuthenticated() } catch { throw "Error connecting to team project collection $Collection ($_)" } $Global:TfsTeamConnection = $null $Global:TfsProjectConnection = $null $Global:TfsTpcConnection = $tpc $Global:TfsServerConnection = $tpc.ConfigurationServer 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 { Process { Disconnect-TfsTeamProjectCollection if ($Global:TfsServerConnection) { Remove-Variable -Name TfsServerConnection -Scope Global } } } <# .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 { Process { if ($Global:TfsProjectConnection) { Remove-Variable -Name TfsProjectConnection -Scope Global } } } <# .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 { Process { Disconnect-TfsTeamProject if ($Global:TfsTpcConnection) { Remove-Variable -Name TfsTpcConnection -Scope Global } } } |