internal/functions/Get-Environment.ps1
|
<# .SYNOPSIS Gets environments in the cheapest shape a caller needs. .DESCRIPTION Returns BAP environments by default and only pays for richer shapes on request. When no environment matches, it stops execution with an actionable message so callers never need a null check. .PARAMETER EnvironmentId Environment name, GUID, or LCS id. Supports wildcards. Default: "*". .PARAMETER Unified Return unified environments instead of every BAP environment. .PARAMETER VersionDetails Include the per-environment provisioning data. Requires -Unified. .EXAMPLE PS C:\> Get-Environment -EnvironmentId "env-123" Returns the BAP environment without extra data. It uses -EnvironmentId to match name, GUID, or LCS id. .EXAMPLE PS C:\> Get-Environment -EnvironmentId "env-123" -Unified Returns the unified environment without extra data. It uses -EnvironmentId to match name, GUID, or LCS id. It uses -Unified to filter to unified environments. .EXAMPLE PS C:\> Get-Environment -EnvironmentId "env-123" -Unified -VersionDetails Returns the unified environment with provisioning data. It uses -EnvironmentId to match name, GUID, or LCS id. It uses -Unified to filter to unified environments. It uses -VersionDetails to include per-environment data. .NOTES Author: Motz Jensen (@Splaxi) #> function Get-Environment { [CmdletBinding(DefaultParameterSetName = 'Bap')] [OutputType([PSCustomObject])] param ( [SupportsWildcards()] [string] $EnvironmentId = '*', [Parameter(ParameterSetName = 'Unified', Mandatory = $true)] [switch] $Unified, [Parameter(ParameterSetName = 'Unified')] [switch] $VersionDetails ) $result = if ($Unified) { if ($VersionDetails) { Get-UnifiedEnvironment -EnvironmentId $EnvironmentId } else { Get-UnifiedEnvironment -EnvironmentId $EnvironmentId -SkipVersionDetails } } else { Get-BapEnvironment -EnvironmentId $EnvironmentId } if ($null -eq $result -or @($result).Count -eq 0) { $messageString = "Could not find any environment matching <c='em'>$EnvironmentId</c>. Please verify the id or list the available environments using <c='em'>Get-BapEnvironment</c> or <c='em'>Get-UnifiedEnvironment</c>." Write-PSFMessage -Level Important -Message $messageString Stop-PSFFunction -Message "Stopping because no environment matched the supplied id." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', ''))) -EnableException $true } $result } |