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 to download. Omitted: newest build of the track.
 
    .PARAMETER AppVersion
        Track to download as version, track or full build. Omitted: from -Build, else newest.
 
    .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
        Environment for the auth context only. Omitted: first FinOps environment is used.
 
    .EXAMPLE
        PS C:\> Get-PpacFinOpsAsset -Build "10.0.2790.46"
 
        Resolves download URLs for that build.
 
    .EXAMPLE
        PS C:\> Get-PpacFinOpsBuild -Latest | Get-PpacFinOpsAsset -Kind NuGet -Download
 
        Downloads all NuGet packages of the newest build.
 
    .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.
 
    .EXAMPLE
        PS C:\> Get-PpacFinOpsAsset -Build "10.0.2790.46" -Asset Vhd -Download
 
        Downloads the VHD image parts.
 
    .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.
 
    .NOTES
        Author: Mötz Jensen (@Splaxi)
#>

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

        [Parameter(ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [string] $Build,

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

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

        [switch] $Download,

        [string] $Path = "C:\Temp\d365bap.tools\PpacFinOpsAssets",

        [switch] $Force,

        [Parameter(ValueFromPipelineByPropertyName = $true)]
        [Alias("PpacEnvId")]
        [string] $EnvironmentId,

        [string] $OutputPath
    )

    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 }

        $ctx = Get-DevToolsAuthContext -EnvironmentId $EnvironmentId

        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 $appGiven -and "$Build" -like '@{*}') {
            $Build = ''
            $buildGiven = $false
        }

        $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) {
            $colAssets | Select-PSFObject -TypeName "D365Bap.Tools.PpacFinOpsAsset" `
                -Property *, `
            @{Name = "Status"; Expression = { "Available" } }
            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()

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

    end {
    }
}