functions/Get-PpacFinOpsAsset.ps1

<#
    .SYNOPSIS
        Downloads FinOps assets for any build.
 
    .DESCRIPTION
        Resolves and downloads NuGet packages, developer files and VHD images. Any published version can be selected.
 
    .PARAMETER Build
        Full build, track or short form. Omitted: newest.
 
        ByBuild set; excludes -EnvironmentId.
 
    .PARAMETER AppVersion
        Track selector. Omitted: from -Build, else newest.
 
        ByBuild set; excludes -EnvironmentId.
 
    .PARAMETER Asset
        Names to download; "*" selects everything including VHD.
 
        Default: "*".
 
    .PARAMETER Kind
        Kind to keep: NuGet, DeveloperFile or Vhd.
 
        Default: "*".
 
    .PARAMETER Download
        Download the files instead of only resolving URLs.
 
    .PARAMETER Path
        Target folder with a subfolder per build.
 
        Default: C:\Temp\d365bap.tools\PpacFinOpsAssets
 
    .PARAMETER OutputPath
        Custom extraction root. Build and asset folders are appended.
 
    .PARAMETER Force
        Re-download files and re-extract folders.
 
    .PARAMETER EnvironmentId
        Build source and auth context.
 
        ByEnvironment set; excludes -Build and -AppVersion.
 
    .PARAMETER AsExcelOutput
        Instructs the cmdlet to output the results as an Excel file.
 
    .EXAMPLE
        PS C:\> Get-PpacFinOpsAsset -Build "10.0.2790.46"
 
        Resolves download URLs for that build.
        It selects the version with -Build.
        It keeps downloads under the default -Path.
 
    .EXAMPLE
        PS C:\> Get-PpacFinOpsBuild -Latest | Get-PpacFinOpsAsset -Kind NuGet -Download
 
        Downloads all NuGet packages of the newest build.
        It takes the newest build with -Latest.
        It keeps only the -Kind NuGet packages.
        It downloads the files with -Download.
        It keeps downloads under the default -Path.
 
    .EXAMPLE
        PS C:\> Get-PpacFinOpsAsset -Build "10.0.49" -Kind DeveloperFile | Where-Object { $_.Asset -eq 'SystemMetadata' } | Get-PpacFinOpsAsset -Download
 
        Downloads the system metadata of that track.
        It selects the track with -Build.
        It keeps only the -Kind DeveloperFile files.
        It filters to the SystemMetadata asset.
        It downloads the files with -Download.
        It keeps downloads under the default -Path.
 
    .EXAMPLE
        PS C:\> Get-PpacFinOpsAsset -Build "10.0.2790.46" -Asset Vhd -Download
 
        Downloads the VHD image parts.
        It selects the version with -Build.
        It keeps only -Asset Vhd.
        It downloads the files with -Download.
        It keeps downloads under the default -Path.
 
    .EXAMPLE
        PS C:\> Get-PpacFinOpsAsset -Build "10.0.2790.46" -Kind NuGet -Download -OutputPath "C:\tmp\D365"
 
        Downloads NuGet files, extracting under C:\tmp\D365.
        It selects the version with -Build.
        It keeps only the -Kind NuGet packages.
        It downloads the files with -Download.
        It extracts under -OutputPath C:\tmp\D365.
        It keeps downloads under the default -Path.
 
    .EXAMPLE
        PS C:\> Get-PpacFinOpsAsset -Build "10.0.2790.46" -AsExcelOutput
 
        Resolves download URLs for that build into an Excel file.
        It selects the version with -Build.
        It writes an Excel file with -AsExcelOutput.
        It keeps downloads under the default -Path.
 
    .EXAMPLE
        PS C:\> Get-PpacFinOpsAsset -EnvironmentId "es-ude-motz-01"
 
        Resolves download URLs for the provisioned build of that environment.
        It uses the environment build with -EnvironmentId.
        It keeps downloads under the default -Path.
 
    .NOTES
        Author: Mötz Jensen (@Splaxi)
#>

function Get-PpacFinOpsAsset {
    [CmdletBinding(DefaultParameterSetName = 'ByBuild')]
    [OutputType('System.Object[]')]
    param (
        [Parameter(ParameterSetName = 'ByBuild', ValueFromPipelineByPropertyName = $true, Position = 0)]
        [string] $AppVersion,

        [Parameter(ParameterSetName = 'ByBuild', ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, Position = 1)]
        [string] $Build,

        [ValidateSet('*', 'CompilerPackage', 'Platform', 'ApplicationSuite', 'Application1', 'Application2', 'SystemMetadata', 'FinOpsVsix22', 'TraceParser', 'CrossReference', 'Vhd')]
        [Parameter(ValueFromPipelineByPropertyName = $true, Position = 2)]
        [string[]] $Asset = '*',

        [ValidateSet('*', 'NuGet', 'DeveloperFile', 'Vhd')]
        [Parameter(ValueFromPipelineByPropertyName = $true, Position = 3)]
        [string] $Kind = '*',

        [switch] $Download,

        [Parameter(Position = 4)]
        [string] $Path = "C:\Temp\d365bap.tools\PpacFinOpsAssets",

        [switch] $Force,

        [Parameter(ParameterSetName = 'ByEnvironment', Mandatory = $true, ValueFromPipelineByPropertyName = $true, Position = 5)]
        [Alias("PpacEnvId")]
        [string] $EnvironmentId,

        [Parameter(Position = 6)]
        [string] $OutputPath,

        [switch] $AsExcelOutput
    )

    begin {
        Add-Type -AssemblyName System.IO.Compression.FileSystem

        $executable = Get-PSFConfigValue -FullName "d365bap.tools.path.azcopy"

        $nugetMap = [ordered]@{
            "CompilerPackage"  = "Microsoft.Dynamics.AX.Platform.CompilerPackage"
            "Platform"         = "Microsoft.Dynamics.AX.Platform.DevALM.BuildXpp"
            "ApplicationSuite" = "Microsoft.Dynamics.AX.ApplicationSuite.DevALM.BuildXpp"
            "Application1"     = "Microsoft.Dynamics.AX.Application1.DevALM.BuildXpp"
            "Application2"     = "Microsoft.Dynamics.AX.Application2.DevALM.BuildXpp"
        }

        $fileEndpoints = [ordered]@{
            "SystemMetadata" = "systemmetadata"
            "FinOpsVsix22"   = "finopsvsix22"
            "TraceParser"    = "traceparser"
            "CrossReference" = "crossreference"
        }
    }

    process {
        if (Test-PSFFunctionInterrupt) { return }

        $isByEnvironment = $PSCmdlet.ParameterSetName -eq 'ByEnvironment'

        if ($isByEnvironment) {
            $ctx = Get-DevToolsAuthContext -EnvironmentId $EnvironmentId
        }
        else {
            $ctx = Get-DevToolsAuthContext
        }

        if ($null -eq $ctx) { return }

        $headers = @{
            "Correlationid"           = [guid]::NewGuid().ToString()
            "Dataverseenvironmenturi" = $ctx.Env.PpacEnvUri
            "Authorization"           = "Bearer $($ctx.Token)"
            "Odata-Maxversion"        = "4.0"
            "Odata-Version"           = "4.0"
            "Accept"                  = "application/json"
        }

        try {
            $catalog = Invoke-RestMethod -Method Get `
                -Uri "https://developertools.powerplatform.microsoft.com/api/clientmetadata/finopsversions" `
                -Headers $headers
        }
        catch {
            $messageString = "Failed retrieving the FinOps version catalog from the developer tools service."
            Write-PSFMessage -Level Important -Message $messageString -ErrorRecord $_
            Stop-PSFFunction -Message "Stopping because the finopsversions request failed." -ErrorRecord $_
            return
        }

        $fullBuild = $null
        $track = $null
        $trackAppVersion = $null

        $buildGiven = $PSBoundParameters.ContainsKey('Build') -and -not [string]::IsNullOrWhiteSpace($Build)
        $appGiven = $PSBoundParameters.ContainsKey('AppVersion') -and -not [string]::IsNullOrWhiteSpace($AppVersion)

        if ($buildGiven -and "$Build" -like '@{*}') {
            $Build = ''
            $buildGiven = $false
        }

        if ($isByEnvironment) {
            $envBuild = $null

            if ($null -ne $ctx.Env -and $null -ne $ctx.Env.PSObject.Properties['PpacProvApp'] -and -not [string]::IsNullOrWhiteSpace("$($ctx.Env.PpacProvApp)")) {
                $envBuild = "$($ctx.Env.PpacProvApp)"
            }
            else {
                $envDetail = Get-UnifiedEnvironment -EnvironmentId $EnvironmentId | Select-Object -First 1

                if ($null -eq $envDetail) {
                    $messageString = "Could not find environment with Id <c='em'>$EnvironmentId</c>. Please verify the Id and try again, or list available environments using <c='em'>Get-UnifiedEnvironment</c>. Consider using wildcards if needed."
                    Write-PSFMessage -Level Important -Message $messageString
                    Stop-PSFFunction -Message "Stopping because environment was NOT found based on the id." `
                        -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
                    return
                }

                if ($null -ne $envDetail.PSObject.Properties['PpacProvApp']) {
                    $envBuild = "$($envDetail.PpacProvApp)"
                }
            }

            if ([string]::IsNullOrWhiteSpace($envBuild)) {
                $messageString = "Could not determine the provisioned application build for environment <c='em'>$EnvironmentId</c>. Use <c='em'>-Build</c> or <c='em'>-AppVersion</c> instead (without <c='em'>-EnvironmentId</c>)."
                Write-PSFMessage -Level Important -Message $messageString
                Stop-PSFFunction -Message "Stopping because the environment version is unknown." `
                    -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
                return
            }

            $Build = $envBuild
            $buildGiven = $true
            $appGiven = $false

            Write-PSFMessage -Level Verbose -Message "Using provisioned build <c='em'>$Build</c> from environment <c='em'>$EnvironmentId</c>."
        }

        $appTrack = $null

        if ($appGiven) {
            $appTrack = Get-FinOpsTrackForAppVersion -Catalog $catalog -AppVersion $AppVersion

            if ($null -eq $appTrack) {
                $valid = ($catalog | Sort-Object -Property { [version]$_.appVersion } | ForEach-Object { $_.appVersion }) -join ", "
                $messageString = "Unknown application track <c='em'>$AppVersion</c>. Valid application versions are: $valid."
                Write-PSFMessage -Level Important -Message $messageString
                Stop-PSFFunction -Message "Stopping because the application track was not recognized." `
                    -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
                return
            }
        }

        if ([string]::IsNullOrWhiteSpace($Build)) {
            $candidates = @($catalog | Sort-Object -Property { [version]$_.appVersion })

            if ($appGiven) {
                $candidates = @($candidates | Where-Object { $_.appBuild -eq $appTrack })
            }

            $entry = @($candidates | Select-Object -Last 1)

            if ($null -eq $entry -or $entry.Count -eq 0) {
                Stop-PSFFunction -Message "Stopping because the version catalog is empty."
                return
            }

            $track = $entry[0].appBuild
            $trackAppVersion = $entry[0].appVersion

            try {
                $trackBuilds = Invoke-RestMethod -Method Get `
                    -Uri "https://developertools.powerplatform.microsoft.com/api/clientmetadata/finopsbuilds?version=$($track.Replace('.', '-'))" `
                    -Headers $headers
            }
            catch {
                $messageString = "Failed retrieving FinOps builds for track <c='em'>$track</c> from the developer tools service."
                Write-PSFMessage -Level Important -Message $messageString -ErrorRecord $_
                Stop-PSFFunction -Message "Stopping because the finopsbuilds request failed." -ErrorRecord $_
                return
            }

            $fullBuild = @($trackBuilds | Sort-Object -Property { [version]$_ } -Descending | Select-Object -First 1)

            if ([string]::IsNullOrWhiteSpace("$fullBuild")) {
                Stop-PSFFunction -Message "Stopping because no builds were found for track $track."
                return
            }

            $fullBuild = "$fullBuild"
        }
        else {
            $normalized = "$Build".Replace("-", ".").Trim()
            $parts = @($normalized -split "\.")

            if ($parts.Count -eq 4) {
                $fullBuild = $normalized
                $track = "$($parts[0]).$($parts[1]).$($parts[2])"
                $byBuild = @($catalog | Where-Object { $_.appBuild -eq $track } | Select-Object -First 1)

                if ($byBuild.Count -gt 0) {
                    $trackAppVersion = $byBuild[0].appVersion
                }

                if ($appGiven -and $track -ne $appTrack) {
                    $messageString = "Build <c='em'>$Build</c> is not on the <c='em'>$AppVersion</c> track. Specify a matching build or omit <c='em'>-AppVersion</c>."
                    Write-PSFMessage -Level Important -Message $messageString
                    Stop-PSFFunction -Message "Stopping because the build does not match the application track." `
                        -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
                    return
                }
            }
            else {
                $byAppVersion = @($catalog | Where-Object { $_.appVersion -eq $normalized } | Select-Object -First 1)

                if ($byAppVersion.Count -gt 0) {
                    $track = $byAppVersion[0].appBuild
                    $trackAppVersion = $byAppVersion[0].appVersion
                }
                else {
                    $byBuild = @($catalog | Where-Object { $_.appBuild -eq $normalized } | Select-Object -First 1)

                    if ($byBuild.Count -gt 0) {
                        $track = $byBuild[0].appBuild
                        $trackAppVersion = $byBuild[0].appVersion
                    }
                }

                if ([string]::IsNullOrWhiteSpace($track)) {
                    $valid = ($catalog | Sort-Object -Property { [version]$_.appVersion } | ForEach-Object { $_.appVersion }) -join ", "
                    $messageString = "Unknown build or track <c='em'>$Build</c>. Valid application versions are: $valid."
                    Write-PSFMessage -Level Important -Message $messageString
                    Stop-PSFFunction -Message "Stopping because the build was not recognized." `
                        -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
                    return
                }

                if ($appGiven -and $track -ne $appTrack) {
                    $messageString = "Build <c='em'>$Build</c> is not on the <c='em'>$AppVersion</c> track. Specify a matching build or omit <c='em'>-AppVersion</c>."
                    Write-PSFMessage -Level Important -Message $messageString
                    Stop-PSFFunction -Message "Stopping because the build does not match the application track." `
                        -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
                    return
                }

                try {
                    $trackBuilds = Invoke-RestMethod -Method Get `
                        -Uri "https://developertools.powerplatform.microsoft.com/api/clientmetadata/finopsbuilds?version=$($track.Replace('.', '-'))" `
                        -Headers $headers
                }
                catch {
                    $messageString = "Failed retrieving FinOps builds for track <c='em'>$track</c> from the developer tools service."
                    Write-PSFMessage -Level Important -Message $messageString -ErrorRecord $_
                    Stop-PSFFunction -Message "Stopping because the finopsbuilds request failed." -ErrorRecord $_
                    return
                }

                $fullBuild = @($trackBuilds | Sort-Object -Property { [version]$_ } -Descending | Select-Object -First 1)

                if ([string]::IsNullOrWhiteSpace("$fullBuild")) {
                    Stop-PSFFunction -Message "Stopping because no builds were found for track $track."
                    return
                }

                $fullBuild = "$fullBuild"
            }
        }

        $wanted = @()
        $assetExplicit = $PSBoundParameters.ContainsKey('Asset')

        if (-not $assetExplicit) {
            $wanted = @($nugetMap.Keys) + @($fileEndpoints.Keys)
        }
        else {
            foreach ($name in @($Asset)) {
                if ($name -eq '*') {
                    $wanted += @($nugetMap.Keys) + @($fileEndpoints.Keys) + @('Vhd')
                }
                else {
                    $wanted += $name
                }
            }

            $wanted = @($wanted | Sort-Object -Unique)
        }

        if (-not $assetExplicit -and $PSBoundParameters.ContainsKey('Kind') -and $Kind -ne '*' -and ('Vhd' -like $Kind) -and 'Vhd' -notin $wanted) {
            $wanted += 'Vhd'
        }

        if ($Kind -ne '*') {
            $kindOf = {
                param ([string] $Name)

                if ($Name -eq 'Vhd') { return 'Vhd' }
                if ($nugetMap.Contains($Name)) { return 'NuGet' }

                return 'DeveloperFile'
            }

            $wanted = @($wanted | Where-Object { (& $kindOf $_) -like $Kind })

            if ($wanted.Count -eq 0) {
                Write-PSFMessage -Level Important -Message "No assets match <c='em'>$($Asset -join ', ')</c> filtered by kind <c='em'>$Kind</c>. Note that VHD is only included when explicitly requested via <c='em'>-Asset Vhd</c>."
                return
            }
        }

        $buildDashed = $fullBuild.Replace(".", "-")

        if ($Download) {
            $downloadDir = Join-Path $Path $fullBuild

            $null = New-Item -Path $downloadDir `
                -ItemType Directory `
                -Force `
                -WarningAction SilentlyContinue
        }

        $colAssets = @(
            foreach ($name in $wanted) {
                if ($name -eq 'Vhd') {
                    if ([string]::IsNullOrWhiteSpace($trackAppVersion)) {
                        Write-PSFMessage -Level Important -Message "Skipping <c='em'>Vhd</c>: the application version for build <c='em'>$fullBuild</c> is unknown."
                        continue
                    }

                    try {
                        $vhdUris = Invoke-RestMethod -Method Get `
                            -Uri "https://developertools.powerplatform.microsoft.com/api/clientmetadata/vhd?version=$($trackAppVersion.Replace('.', '-'))" `
                            -Headers $headers
                    }
                    catch {
                        Write-PSFMessage -Level Important -Message "Skipping <c='em'>Vhd</c> for <c='em'>$trackAppVersion</c>: $($_.Exception.Message)" -ErrorRecord $_
                        continue
                    }

                    foreach ($vhdUri in @($vhdUris)) {
                        $vhdFileName = (Split-Path "$vhdUri" -Leaf).Split("?")[0]

                        [PsCustomObject][Ordered]@{
                            "Asset"    = "Vhd"
                            "Kind"     = "Vhd"
                            "FileName" = $vhdFileName
                            "Build"    = $fullBuild
                            "Uri"      = "$vhdUri"
                        }
                    }

                    continue
                }

                try {
                    if ($nugetMap.Contains($name)) {
                        $packageId = $nugetMap[$name]
                        $assetUri = Invoke-RestMethod -Method Get `
                            -Uri "https://developertools.powerplatform.microsoft.com/api/clientmetadata/nugetpackage?packageName=$([uri]::EscapeDataString($packageId))&version=$buildDashed" `
                            -Headers $headers
                    }
                    else {
                        $assetUri = Invoke-RestMethod -Method Get `
                            -Uri "https://developertools.powerplatform.microsoft.com/api/clientmetadata/$($fileEndpoints[$name])?version=$buildDashed" `
                            -Headers $headers
                    }
                }
                catch {
                    Write-PSFMessage -Level Important -Message "Skipping <c='em'>$name</c> for build <c='em'>$fullBuild</c>: not published for this build." -ErrorRecord $_
                    continue
                }

                $assetFileName = (Split-Path "$assetUri" -Leaf).Split("?")[0]

                $assetKind = if ($nugetMap.Contains($name)) { "NuGet" } else { "DeveloperFile" }

                [PsCustomObject][Ordered]@{
                    "Asset"    = $name
                    "Kind"     = $assetKind
                    "FileName" = $assetFileName
                    "Build"    = $fullBuild
                    "Uri"      = "$assetUri"
                }
            }
        )

        $versionInfo = Resolve-FinOpsVersionFromCache -Build $fullBuild
        $mapAppVersion = if ($null -ne $versionInfo) { $versionInfo.AppVersion } else { '' }
        $mapAppBuild = if ($null -ne $versionInfo) { $versionInfo.AppBuild } else { '' }
        $mapPlatVersion = if ($null -ne $versionInfo) { $versionInfo.PlatVersion } else { '' }
        $mapPlatBuild = if ($null -ne $versionInfo) { $versionInfo.PlatBuild } else { '' }

        foreach ($assetObj in $colAssets) {
            $assetObj | Add-Member -NotePropertyName "AppVersion" -NotePropertyValue $mapAppVersion -Force
            $assetObj | Add-Member -NotePropertyName "AppBuild" -NotePropertyValue $mapAppBuild -Force
            $assetObj | Add-Member -NotePropertyName "Track" -NotePropertyValue $mapAppBuild -Force
            $assetObj | Add-Member -NotePropertyName "PlatVersion" -NotePropertyValue $mapPlatVersion -Force
            $assetObj | Add-Member -NotePropertyName "PlatBuild" -NotePropertyValue $mapPlatBuild -Force
        }

        $colAssets = @($colAssets | Sort-Object -Property Kind, Asset, FileName)

        if (-not $Download) {
            $output = $colAssets | Select-PSFObject -TypeName "D365Bap.Tools.PpacFinOpsAsset" `
                -Property *, `
            @{Name = "Status"; Expression = { "Available" } }

            if ($AsExcelOutput) {
                $output | Export-Excel -WorksheetName "Get-PpacFinOpsAsset" `
                    -NoNumberConversion AppVersion, AppBuild, Track, Build, PlatVersion, PlatBuild
                return
            }

            $output
            return
        }

        if (-not [System.IO.File]::Exists($executable)) {
            $messageString = "AzCopy executable not found at <c='em'>$executable</c>. Please install AzCopy using <c='em'>Invoke-BapInstallAzCopy</c> or configure the path using <c='em'>Set-BapAzCopyPath</c>."
            Write-PSFMessage -Level Important -Message $messageString
            Stop-PSFFunction -Message "Stopping because AzCopy executable was not found." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
            return
        }

        if ($PSBoundParameters.ContainsKey('OutputPath') -and -not [string]::IsNullOrWhiteSpace($OutputPath)) {
            $baseRoot = Join-Path $OutputPath $fullBuild
            $pathNugetsRoot = Join-Path $baseRoot "NuGets"
            $pathPackagesLocalDirectory = Join-Path $baseRoot "PackagesLocalDirectory"
        }
        else {
            $pathNugetsRoot = "$env:LOCALAPPDATA\Microsoft\Dynamics365\$fullBuild\NuGets"
            $pathPackagesLocalDirectory = "$env:LOCALAPPDATA\Microsoft\Dynamics365\$fullBuild\PackagesLocalDirectory"
        }

        $retryCount = 0
        $maxRetries = 5

        do {
            $retryCount++

            foreach ($assetObj in $colAssets) {
                $outputPath = Join-Path $downloadDir $assetObj.FileName
                $assetObj | Add-Member -NotePropertyName "Path" -NotePropertyValue $outputPath -Force

                if ([System.IO.File]::Exists($outputPath) -and -not $Force) {
                    Write-PSFMessage -Level Verbose -Message "Skipping $($assetObj.FileName), already on disk. Use -Force to re-download."
                    $assetObj | Add-Member -NotePropertyName "Status" -NotePropertyValue "Skipped" -Force
                    continue
                }

                Write-PSFMessage -Level Important -Message "Downloading <c='em'>$($assetObj.FileName)</c>..."

                try {
                    $azCopyOut = & $executable copy "$($assetObj.Uri)" "$outputPath" --overwrite=true 2>&1
                    Write-PSFMessage -Level Verbose -Message ($azCopyOut -join [Environment]::NewLine)
                }
                catch {
                    Write-PSFMessage -Level Important -Message "Download of <c='em'>$($assetObj.FileName)</c> failed: $($_.Exception.Message)" -ErrorRecord $_
                }

                if ([System.IO.File]::Exists($outputPath)) {
                    Unblock-File -Path $outputPath
                    $assetObj | Add-Member -NotePropertyName "Status" -NotePropertyValue "Downloaded" -Force
                }
                else {
                    $assetObj | Add-Member -NotePropertyName "Status" -NotePropertyValue "Failed" -Force
                }
            }
        } while (
            ($colAssets | `
                Where-Object { $_.Status -ne "Downloaded" -and $_.Status -ne "Skipped" }) `
                -and $retryCount -lt $maxRetries
        )

        foreach ($assetObj in $colAssets) {
            $assetObj | Add-Member -NotePropertyName "ExtractedPath" -NotePropertyValue $null -Force

            if ($assetObj.Status -ne "Downloaded" -and -not ([System.IO.File]::Exists($assetObj.Path))) {
                continue
            }

            if ($assetObj.Asset -in @($nugetMap.Keys)) {
                $null = New-Item -Path $pathNugetsRoot `
                    -ItemType Directory `
                    -Force `
                    -WarningAction SilentlyContinue

                $extractDirName = [System.IO.Path]::GetFileNameWithoutExtension($assetObj.Path)
                $extractPath = Join-Path $pathNugetsRoot $extractDirName
                $assetObj.ExtractedPath = $extractPath

                if ([System.IO.Path]::Exists($extractPath) -and -not $Force) {
                    Write-PSFMessage -Level Verbose -Message "Extraction of $extractDirName already in place. Use -Force to re-extract."
                    continue
                }

                if ([System.IO.Path]::Exists($extractPath)) {
                    Remove-Item -Path $extractPath -Recurse -Force
                }

                Write-PSFMessage -Level Important -Message "Extracting <c='em'>$extractDirName</c>..."
                [IO.Compression.ZipFile]::ExtractToDirectory($assetObj.Path, $extractPath, $true)
            }
            elseif ($assetObj.Asset -eq "SystemMetadata") {
                $assetObj.ExtractedPath = $pathPackagesLocalDirectory

                if ([System.IO.Path]::Exists($pathPackagesLocalDirectory) -and -not $Force) {
                    Write-PSFMessage -Level Verbose -Message "PackagesLocalDirectory already in place. Use -Force to re-extract."
                    continue
                }

                Write-PSFMessage -Level Important -Message "Extracting <c='em'>PackagesLocalDirectory</c> for build <c='em'>$fullBuild</c>..."
                [IO.Compression.ZipFile]::ExtractToDirectory($assetObj.Path, $pathPackagesLocalDirectory, $true)
            }
        }

        [GC]::Collect()
        [GC]::WaitForPendingFinalizers()

        $output = $colAssets | Select-PSFObject -TypeName "D365Bap.Tools.PpacFinOpsAsset" `
            -Property *

        if ($AsExcelOutput) {
            $output | Export-Excel -WorksheetName "Get-PpacFinOpsAsset" `
                -NoNumberConversion AppVersion, AppBuild, Track, Build, PlatVersion, PlatBuild
            return
        }

        $output
    }

    end {
    }
}