AreaIteration/Area/AreaIteration_Area.ps1
|
<#
.SYNOPSIS Gets one or more Work Item Areas from a given Team Project. .PARAMETER Area Specifies the name, URI or path of an Area. Wildcards are permitted. If omitted, all Areas in the given Team Project are returned. To supply a path, use a backslash ('\') between the path segments. Leading and trailing backslashes are optional. When supplying a URI, use URIs in the form of 'vstfs:///Classification/Node/<GUID>' (where <GUID> is the unique identifier of the given node) .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. .INPUTS Microsoft.TeamFoundation.WorkItemTracking.Client.Project System.String .EXAMPLE Get-TfsArea Returns all area paths in the currently connected Team Project (as defined by a previous call to Connect-TfsTeamProject) .EXAMPLE Get-TfsArea 'Fabrikam Web Team' -Project 'Fabrikam Fiber' Returns information on an area path called 'Fabrikam Web Team' in a team project called 'Fabrikam Fiber' .EXAMPLE Get-TfsArea '\**\Support' -Project Tailspin Performs a recursive search and returns all area paths named 'Support' that may exist in a team project called Tailspin #> Function Get-TfsArea { [CmdletBinding()] [OutputType('Microsoft.TeamFoundation.Server.NodeInfo')] Param ( [Parameter(Position=0)] [Alias("Path")] [ValidateScript({($_ -is [string]) -or ($_ -is [uri]) -or ($_ -is [Microsoft.TeamFoundation.Server.NodeInfo])})] [SupportsWildcards()] [object] $Area = '\**', [Parameter(ValueFromPipeline=$true)] [object] $Project, [Parameter()] [object] $Collection ) Process { return _GetCssNodes -Node $Area -Scope Area -Project $Project -Collection $Collection } } <# .SYNOPSIS Moves a Work Item Area from its parent area to another one in the same Team Project. .PARAMETER Area Specifies the name, URI or path of an Area. Wildcards are permitted. If omitted, all Areas in the given Team Project are returned. To supply a path, use a backslash ('\') between the path segments. Leading and trailing backslashes are optional. When supplying a URI, use URIs in the form of 'vstfs:///Classification/Node/<GUID>' (where <GUID> is the unique identifier of the given node) .PARAMETER Destination Specifies the name, URI or path of an Area Path that will become the new parent of the given source area .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. .INPUTS Microsoft.TeamFoundation.Server.NodeInfo System.String System.Uri #> Function Move-TfsArea { [CmdletBinding(ConfirmImpact='Medium')] [OutputType('Microsoft.TeamFoundation.Server.NodeInfo')] Param ( [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)] [Alias("Path")] [ValidateScript({($_ -is [string]) -or ($_ -is [uri]) -or ($_ -is [Microsoft.TeamFoundation.Server.NodeInfo])})] [object] $Area, [Parameter(Position=1l)] [ValidateScript({($_ -is [string]) -or ($_ -is [uri]) -or ($_ -is [Microsoft.TeamFoundation.Server.NodeInfo])})] [object] $Destination, [Parameter()] [object] $Project, [Parameter()] [object] $Collection, [Parameter()] [switch] $Passthru ) Process { $node = Get-TfsArea -Area $Area -Project $Project -Collection $Collection if (-not $node) { throw "Invalid or non-existent area $Area" } $destinationNode = Get-TfsArea -Area $Destination -Project $Project -Collection $Collection if (-not $node) { throw "Invalid or non-existent destination area $Destination" } $cssService = _GetCssService -Project $Project -Collection $Collection $cssService.MoveBranch($node.Uri, $destinationNode.Uri) $node = $cssService.GetNode($node.Uri) if ($Passthru) { return $node } } } <# .SYNOPSIS Creates a new Work Item Area in the given Team Project. .PARAMETER Area Specifies the path of the new Area. When supplying a path, use a backslash ("\") between the path segments. Leading and trailing backslashes are optional. The last segment in the path will be the area name. .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. .INPUTS System.String #> Function New-TfsArea { [CmdletBinding(ConfirmImpact='Medium', SupportsShouldProcess=$true)] [OutputType('Microsoft.TeamFoundation.Server.NodeInfo')] Param ( [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)] [Alias("Path")] [string] $Area, [Parameter()] [object] $Project, [Parameter()] [object] $Collection, [Parameter()] [switch] $Passthru ) Process { if($PSCmdlet.ShouldProcess($Area, 'Create Area Path')) { $node = _NewCssNode -Path $Area -Scope Area -Project $Project -Collection $Collection if ($Passthru) { return $node } } } } <# .SYNOPSIS Deletes one or more Work Item Areas. .PARAMETER Area Specifies the name, URI or path of an Area. Wildcards are permitted. If omitted, all Areas in the given Team Project are returned. To supply a path, use a backslash ('\') between the path segments. Leading and trailing backslashes are optional. When supplying a URI, use URIs in the form of 'vstfs:///Classification/Node/<GUID>' (where <GUID> is the unique identifier of the given node) .PARAMETER MoveTo Specifies the new area path for the work items currently assigned to the area being deleted, if any. When omitted, defaults to the root area .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. .INPUTS Microsoft.TeamFoundation.WorkItemTracking.Client.Project System.String #> Function Remove-TfsArea { [CmdletBinding(ConfirmImpact='High', SupportsShouldProcess=$true)] Param ( [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)] [Alias("Path")] [ValidateScript({($_ -is [string]) -or ($_ -is [Microsoft.TeamFoundation.Server.NodeInfo])})] [object] $Area, [Parameter(Position=1)] [Alias("NewPath")] [ValidateScript({ ($_ -is [string]) -or ($_ -is [Microsoft.TeamFoundation.Server.NodeInfo]) })] [object] $MoveTo = '\', [Parameter()] [object] $Project, [Parameter()] [object] $Collection ) Process { $areas = Get-TfsArea -Area $Area -Project $Project -Collection $Collection | Sort-Object -Property Path -Descending foreach($item in $areas) { $projectName = $item.Path.Split("\")[1] if (-not ($PSCmdlet.ShouldProcess($projectName, "Delete Area '$($item.RelativePath)' and move orphaned work items to area '$MoveTo'"))) { continue } _DeleteCssNode -Node $item -MoveToNode $MoveTo -Scope Area -Project $projectName -Collection $Collection } } } <# .SYNOPSIS Renames a Work Item Area. .PARAMETER Area Specifies the name, URI or path of an Area. Wildcards are permitted. If omitted, all Areas in the given Team Project are returned. To supply a path, use a backslash ('\') between the path segments. Leading and trailing backslashes are optional. When supplying a URI, use URIs in the form of 'vstfs:///Classification/Node/<GUID>' (where <GUID> is the unique identifier of the given node) .PARAMETER NewName Specifies the new name of the area. Enter only a name, not a path and name. If you enter a path that is different from the path that is specified in the Area parameter, Rename-TfsArea generates an error. To rename and move an item, use the Move-TfsArea cmdlet. .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. .INPUTS Microsoft.TeamFoundation.WorkItemTracking.Client.Project System.String #> Function Rename-TfsArea { [CmdletBinding(ConfirmImpact='Medium')] [OutputType('Microsoft.TeamFoundation.Server.NodeInfo')] Param ( [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)] [ValidateScript({($_ -is [string]) -or ($_ -is [Microsoft.TeamFoundation.Server.NodeInfo])})] [Alias("Path")] [object] $Area, [Parameter(Position=1)] [string] $NewName, [Parameter()] [object] $Project, [Parameter()] [object] $Collection, [Parameter()] [switch] $Passthru ) Process { $result = Set-TfsArea -Area $Area -NewName $NewName -Project $Project -Collection $Collection if ($Passthru) { return $result } } } <# .SYNOPSIS Modifies the name and/or the position of a Work Item Area. .PARAMETER Area Specifies the name, URI or path of an Area. Wildcards are permitted. If omitted, all Areas in the given Team Project are returned. To supply a path, use a backslash ('\') between the path segments. Leading and trailing backslashes are optional. When supplying a URI, use URIs in the form of 'vstfs:///Classification/Node/<GUID>' (where <GUID> is the unique identifier of the given node) .PARAMETER NewName Specifies the new name of the area. Enter only a name, not a path and name. If you enter a path that is different from the path that is specified in the area parameter, Rename-Tfsarea generates an error. To rename and move an item, use the Move-Tfsarea cmdlet. .PARAMETER MoveBy Reorders an area by moving it either up or down inside its parent. A positive value moves an area down, whereas a negative one moves it up. .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. .INPUTS Microsoft.TeamFoundation.WorkItemTracking.Client.Project System.String #> Function Set-TfsArea { [CmdletBinding(ConfirmImpact='Medium', SupportsShouldProcess=$true)] [OutputType('Microsoft.TeamFoundation.Server.NodeInfo')] Param ( [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)] [ValidateScript({($_ -is [string]) -or ($_ -is [Microsoft.TeamFoundation.Server.NodeInfo])})] [Alias("Path")] [object] $Area, [Parameter()] [string] $NewName, [Parameter()] [int] $MoveBy, [Parameter()] [object] $Project, [Parameter()] [object] $Collection ) Process { $node = Get-TfsArea -Area $Area -Project $Project -Collection $Collection if (-not $node) { throw "Invalid or non-existent area $Area" } $cssService = _GetCssService -Project $Project -Collection $Collection if ($NewName) { if ($PSCmdlet.ShouldProcess($Area, "Rename area to $NewName")) { $cssService.RenameNode($node.Uri, $NewName) } } if ($MoveBy) { if ($PSCmdlet.ShouldProcess($Area, "Reorder area by moving it $MoveBy positions (negative is up, positive is down)")) { $cssService.ReorderNode($node.Uri, $MoveBy) } } return $cssService.GetNode($node.Uri) } } <# .SYNOPSIS Determines whether the specified Areas Paths exist. .PARAMETER Area Specifies the name, URI or path of an Area. Wildcards are permitted. If omitted, all Areas in the given Team Project are returned. To supply a path, use a backslash ('\') between the path segments. Leading and trailing backslashes are optional. When supplying a URI, use URIs in the form of 'vstfs:///Classification/Node/<GUID>' (where <GUID> is the unique identifier of the given node) .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. .INPUTS Microsoft.TeamFoundation.WorkItemTracking.Client.Project System.String .EXAMPLE Test-TfsArea 'Fabrikam Web Team' -Project 'Fabrikam Fiber' Returns $true if an area path called 'Fabrikam Web Team' exists in a team project called 'Fabrikam Fiber' #> Function Test-TfsArea { [CmdletBinding()] [OutputType('bool')] Param ( [Parameter(Position=0)] [Alias("Path")] [ValidateScript({($_ -is [string]) -or ($_ -is [uri]) -or ($_ -is [Microsoft.TeamFoundation.Server.NodeInfo])})] [SupportsWildcards()] [object] $Area = '\**', [Parameter(ValueFromPipeline=$true)] [object] $Project, [Parameter()] [object] $Collection ) Process { try { return [bool] (_GetCssNodes -Node $Area -Scope Area -Project $Project -Collection $Collection) } catch { Write-Warning "Error testing path: $_" return $false } } } |