AreaIteration/Iteration/AreaIteration_Iteration.ps1
|
<#
.SYNOPSIS Gets one or more Work Item Iterations from a given Team Project. .PARAMETER Iteration Specifies the name, URI or path of an Iteration. Wildcards are permitted. If omitted, all Iterations in the given Team Project are returned.nnTo supply a path, use a backslash ('\') between the path segments. Leading and trailing backslashes are optional.nnWhen 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 #> Function Get-TfsIteration { [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] $Iteration = '\**', [Parameter(ValueFromPipeline=$true)] [object] $Project, [Parameter()] [object] $Collection ) Process { return _GetCssNodes -Node $Iteration -Scope Iteration -Project $Project -Collection $Collection } } <# .SYNOPSIS Moves a Work Item Iteration from its parent iteration to another one in the same Team Project. .PARAMETER Iteration Specifies the name, URI or path of an Iteration. Wildcards are permitted. If omitted, all Iterations in the given Team Project are returned.nnTo supply a path, use a backslash ('\') between the path segments. Leading and trailing backslashes are optional.nnWhen 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 Iteration Path that will become the new parent of the given source iteration .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-TfsIteration { [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] $Iteration, [Parameter(Position=1)] [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-TfsIteration -Iteration $Iteration -Project $Project -Collection $Collection if (-not $node) { throw "Invalid or non-existent iteration $Iteration" } $destinationNode = Get-TfsIteration -Iteration $Destination -Project $Project -Collection $Collection if (-not $node) { throw "Invalid or non-existent destination iteration $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 Iteration in the given Team Project. .PARAMETER Iteration Specifies the path of the new Iteration. 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 iteration name. .PARAMETER StartDate Specifies the start of a timed iteration, such as a sprint. Enter a string that represents the date and time, such as "12/01/2015" or a DateTime object, such as one from a Get-Date command. When omitted, no start date is set. .PARAMETER FinishDate Specifies the end of a timed iteration, such as a sprint. Enter a string that represents the date and time, such as "12/01/2015" or a DateTime object, such as one from a Get-Date command. When omitted, no finish date is set. .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-TfsIteration { [CmdletBinding(ConfirmImpact='Medium', SupportsShouldProcess=$true)] [OutputType('Microsoft.TeamFoundation.Server.NodeInfo')] Param ( [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)] [Alias("Path")] [string] $Iteration, [Parameter()] [DateTime] $StartDate, [Parameter()] [DateTime] $FinishDate, [Parameter()] [object] $Project, [Parameter()] [object] $Collection, [Parameter()] [switch] $Passthru ) Process { if($PSCmdlet.ShouldProcess($Iteration, 'Create iteration path')) { $node = _NewCssNode -Path $Iteration -Scope Iteration -Project $Project -Collection $Collection -StartDate $StartDate -FinishDate $FinishDate if ($Passthru) { return $node } } } } <# .SYNOPSIS Deletes one or more Work Item Iterations. .PARAMETER Iteration Specifies the name, URI or path of an Iteration. Wildcards are permitted. If omitted, all Iterations in the given Team Project are returned.nnTo supply a path, use a backslash ('\') between the path segments. Leading and trailing backslashes are optional.nnWhen 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 iteration path for the work items currently assigned to the iteration being deleted, if any. When omitted, defaults to the root iteration .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-TfsIteration { [CmdletBinding(ConfirmImpact='High', SupportsShouldProcess=$true)] Param ( [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)] [SupportsWildcards()] [Alias("Path")] [ValidateScript({($_ -is [string]) -or ($_ -is [Microsoft.TeamFoundation.Server.NodeInfo])})] [object] $Iteration, [Parameter(Position=1)] [Alias("NewPath")] [ValidateScript({ ($_ -is [string]) -or ($_ -is [Microsoft.TeamFoundation.Server.NodeInfo]) })] [object] $MoveTo = '\', [Parameter()] [object] $Project, [Parameter()] [object] $Collection ) Process { $iterations = Get-TfsIteration -Iteration $Iteration -Project $Project -Collection $Collection | Sort-Object -Property Path -Descending foreach($i in $iterations) { $projectName = $i.Path.Split("\")[1] if (-not ($PSCmdlet.ShouldProcess($projectName, "Delete Iteration '$($i.RelativePath)' and move orphaned work items to iteration '$MoveTo'"))) { continue } _DeleteCssNode -Node $i -MoveToNode $MoveTo -Scope Iteration -Project $projectName -Collection $Collection } } } <# .SYNOPSIS Renames a Work Item Iteration. .PARAMETER Iteration Specifies the name, URI or path of an Iteration. Wildcards are permitted. If omitted, all Iterations in the given Team Project are returned.nnTo supply a path, use a backslash ('\') between the path segments. Leading and trailing backslashes are optional.nnWhen 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 iteration. 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 Iteration parameter, Rename-TfsIteration generates an error. To rename and move an item, use the Move-TfsIteration 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-TfsIteration { [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] $Iteration, [Parameter(Position=1)] [string] $NewName, [Parameter()] [object] $Project, [Parameter()] [object] $Collection, [Parameter()] [switch] $Passthru ) Process { $result = Set-TfsIteration -Iteration $Iteration -NewName $NewName -Project $Project -Collection $Collection if ($Passthru) { return $result } } } <# .SYNOPSIS Modifies the name, position and/or the dates of a Work Item Iteration. .PARAMETER Iteration Specifies the name, URI or path of an Iteration. Wildcards are permitted. If omitted, all Iterations in the given Team Project are returned.nnTo supply a path, use a backslash ('\') between the path segments. Leading and trailing backslashes are optional.nnWhen 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 iteration. 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 Iteration parameter, Rename-TfsIteration generates an error. To rename and move an item, use the Move-TfsIteration cmdlet. .PARAMETER MoveBy Reorders an iteration by moving it either up or down inside its parent. A positive value moves an iteration down, whereas a negative one moves it up. .PARAMETER StartDate Sets the start date of the iteration. To clear the start date, set it to $null. Note that when clearing a date, both must be cleared at the same time (i.e. setting both StartDate and FinishDate to $null) .PARAMETER FinishDate Sets the finish date of the iteration. To clear the finish date, set it to $null. Note that when clearing a date, both must be cleared at the same time (i.e. setting both StartDate and FinishDate to $null) .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-TfsIteration { [CmdletBinding(ConfirmImpact='Medium', SupportsShouldProcess=$true)] [OutputType('Microsoft.TeamFoundation.Server.NodeInfo')] Param ( [Parameter(Position=0, Mandatory=$true, ValueFromPipeline=$true)] [Alias("Path")] [ValidateScript({($_ -is [string]) -or ($_ -is [Microsoft.TeamFoundation.Server.NodeInfo])})] [SupportsWildcards()] [object] $Iteration, [Parameter()] [string] $NewName, [Parameter()] [int] $MoveBy, [Parameter()] [Nullable[DateTime]] $StartDate, [Parameter()] [Nullable[DateTime]] $FinishDate, [Parameter()] [object] $Project, [Parameter()] [object] $Collection ) Process { $node = Get-TfsIteration -Iteration $Iteration -Project $Project -Collection $Collection if (-not $node) { throw "Invalid or non-existent iteration $Iteration" } $cssService = _GetCssService -Project $Project -Collection $Collection $cssService4 = _GetCssService -Project $Project -Collection $Collection -Version 4 if ($NewName) { if ($PSCmdlet.ShouldProcess($Iteration, "Rename iteration to $NewName")) { $cssService.RenameNode($node.Uri, $NewName) } } if ($MoveBy) { if ($PSCmdlet.ShouldProcess($Area, "Reorder iteration by moving it $MoveBy positions (negative is up, positive is down)")) { $cssService.ReorderNode($node.Uri, $MoveBy) } } if ($StartDate -or $FinishDate) { if (-not $PSBoundParameters.ContainsKey("StartDate")) { $StartDate = $node.StartDate } if (-not $PSBoundParameters.ContainsKey("FinishDate")) { $FinishDate = $node.FinishDate } if ($PSCmdlet.ShouldProcess($Area, "Set iteration start and finish dates to $StartDate and $FinishDate, respectively")) { [void]$cssService4.SetIterationDates($node.Uri, $StartDate, $FinishDate) } } return $cssService.GetNode($node.Uri) } } <# .SYNOPSIS Determines whether the specified Iterations Paths exist. .PARAMETER Iteration Specifies the name, URI or path of an Iteration. Wildcards are permitted. If omitted, all Iterations in the given Team Project are returned.nnTo supply a path, use a backslash ('\') between the path segments. Leading and trailing backslashes are optional.nnWhen 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-TfsIteration 'Fabrikam Web Team' -Project 'Fabrikam Fiber' Returns $true if an iteration path called 'Fabrikam Web Team' exists in a team project called 'Fabrikam Fiber' #> Function Test-TfsIteration { [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] $Iteration = '\**', [Parameter(ValueFromPipeline=$true)] [object] $Project, [Parameter()] [object] $Collection ) Process { try { return [bool] (_GetCssNodes -Node $Iteration -Scope Iteration -Project $Project -Collection $Collection) } catch { Write-Warning "Error testing path: $_" return $false } } } |