Feature: Implement Export-BapEnvironmentSolution

d365bap.tools/d365bap.tools.psd1

@@ -48,11 +48,15 @@
 
 		, 'Confirm-BapEnvironmentIntegration'
 
+		, 'Export-BapEnvironmentSolution'
+
 		, 'Get-BapEnvironment'
 		, 'Get-BapEnvironmentApplicationUser'
 
 		, 'Get-BapEnvironmentD365App'
 
+		, 'Get-BapEnvironmentSolution'
+
 		, 'Get-BapEnvironmentUser'
 
 		, 'Get-BapEnvironmentVirtualEntity'

d365bap.tools/functions/Export-BapEnvironmentSolution.ps1

@@ -0,0 +1,113 @@
+
+<#
+    .SYNOPSIS
+        Export PowerPlatform / Dataverse Solution from the environment
+
+    .DESCRIPTION
+        Enables the user to export solutions, on a given environment
+
+        The cmdlet downloads the solution, extracts it and removes unnecessary  files
+
+    .PARAMETER EnvironmentId
+        The id of the environment that you want to work against
+
+        This can be obtained from the Get-BapEnvironment cmdlet
+
+    .PARAMETER SolutionId
+        The id of the solution that you want to work against
+
+        This can be obtained from the Get-BapEnvironmentSolution cmdlet
+
+    .PARAMETER Path
+        Path to the location that you want the files to be exported to
+
+    .EXAMPLE
+        PS C:\> Export-BapEnvironmentSolution -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -SolutionId 3ac10775-0808-42e0-bd23-83b6c714972f -Path "C:\Temp\"
+
+        This will export the solution from the environment.
+        It will extract the files into the "C:\Temp\" location.
+
+    .NOTES
+        Author: Mötz Jensen (@Splaxi)
+#>
+function Export-BapEnvironmentSolution {
+    [CmdletBinding()]
+    param (
+        [parameter (mandatory = $true)]
+        [string] $EnvironmentId,
+
+        [parameter (mandatory = $true)]
+        [string] $SolutionId,
+
+        [parameter (mandatory = $true)]
+        [string] $Path
+    )
+
+    begin {
+        # Make sure all *BapEnvironment* cmdlets will validate that the environment exists prior running anything.
+        $envObj = Get-BapEnvironment -EnvironmentId $EnvironmentId | Select-Object -First 1
+
+        if ($null -eq $envObj) {
+            $messageString = "The supplied EnvironmentId: <c='em'>$EnvironmentId</c> didn't return any matching environment details. Please verify that the EnvironmentId is correct - try running the <c='em'>Get-BapEnvironment</c> cmdlet."
+            Write-PSFMessage -Level Host -Message $messageString
+            Stop-PSFFunction -Message "Stopping because environment was NOT found based on the id." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
+        }
+
+        if (Test-PSFFunctionInterrupt) { return }
+
+        $solObj = Get-BapEnvironmentSolution -EnvironmentId $EnvironmentId -SolutionId $SolutionId | Select-Object -First 1
+
+        if ($null -eq $solObj) {
+            $messageString = "The supplied SolutionId: <c='em'>$SolutionId</c> didn't return any matching solution from the environment. Please verify that the SolutionId is correct - try running the <c='em'>Get-BapEnvironmentSolution</c> cmdlet."
+            Write-PSFMessage -Level Host -Message $messageString
+            Stop-PSFFunction -Message "Stopping because solution was NOT found based on the id." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
+        }
+    }
+
+    process {
+        if (Test-PSFFunctionInterrupt) { return }
+
+        $tmp = pac org list --filter $EnvironmentId
+
+        Write-PSFMessage -Level Host -Message "<c='em'>$($tmp[0])</c>"
+
+        $found = $false
+        foreach ($line in $tmp) {
+            $found = $line -like "*$EnvironmentId*"
+
+            if ($found) {
+                break
+            }
+        }
+
+        if (-not $found) {
+            $messageString = "It seems that the current pac cli session isn't connected to the correct tenant. Please run the <c='em'>pac auth create --name 'ChangeThis'</c> and make sure to use credentials that have enough privileges."
+            Write-PSFMessage -Level Host -Message $messageString
+            Stop-PSFFunction -Message "Stopping because pac cli session is NOT connected to the correct tenant." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
+        }
+
+        if (Test-PSFFunctionInterrupt) { return }
+
+        # pac cli is connected to the correct tenant
+        $pathDownload = [System.IO.Path]::ChangeExtension([System.IO.Path]::GetTempFileName(), 'zip')
+
+        $tmp = pac solution export --name $solObj.SystemName --environment $EnvironmentId --path $pathDownload --overwrite
+
+        if (-not (($tmp | Select-Object -Last 1) -eq "Solution export succeeded.")) {
+            $messageString = "It seems that export of the solution encountered some kind of error. Please run the cmdlet <c='em'>again in a few minutes</c>."
+            Write-PSFMessage -Level Host -Message $messageString
+            Stop-PSFFunction -Message "Stopping because export failed." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
+        }
+
+        Expand-Archive -Path $pathDownload -DestinationPath $Path -Force
+
+        # Give the file system time to persis the extracted files.
+        Start-Sleep -Seconds 2
+
+        Remove-Item -LiteralPath $(Join-Path -Path $Path -ChildPath "[Content_Types].xml") -ErrorAction SilentlyContinue -Force
+    }
+
+    end {
+
+    }
+}

d365bap.tools/functions/Get-BapEnvironmentSolution.ps1

@@ -0,0 +1,160 @@
+
+<#
+    .SYNOPSIS
+        Get PowerPlatform / Dataverse Solution from the environment
+
+    .DESCRIPTION
+        Enables the user to list solutions and their meta data, on a given environment
+
+    .PARAMETER EnvironmentId
+        The id of the environment that you want to work against
+
+        This can be obtained from the Get-BapEnvironment cmdlet
+
+    .PARAMETER SolutionId
+        The id of the solution that you want to work against
+
+        Leave blank to get all solutions
+
+    .PARAMETER IncludeManaged
+        Instruct the cmdlet to include all managed solution
+
+    .PARAMETER AsExcelOutput
+        Instruct the cmdlet to output all details directly to an Excel file
+
+        This makes it easier to deep dive into all the details returned from the API, and makes it possible for the user to persist the current state
+
+    .EXAMPLE
+        PS C:\> Get-BapEnvironmentSolution -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6
+
+        This will query the specific environment.
+        It will only list Unmanaged / NON-Managed solutions.
+
+        Sample output:
+
+        SolutionId                           Name                           IsManaged SystemName           Description
+        ----------                           ----                           --------- ----------           -----------
+        fd140aae-4df4-11dd-bd17-0019b9312238 Active Solution                False     Active               Placeholder solutio…
+
+    .EXAMPLE
+        PS C:\> Get-BapEnvironmentSolution -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -IncludeManaged
+
+        This will query the specific environment.
+        It will list all solutions.
+
+        Sample output:
+
+        SolutionId                           Name                           IsManaged SystemName           Description
+        ----------                           ----                           --------- ----------           -----------
+        169edc7d-5f1e-4ee4-8b5c-135b3ba82ea3 Access Team                    True      AccessTeam           Access Team solution
+        fd140aae-4df4-11dd-bd17-0019b9312238 Active Solution                False     Active               Placeholder solutio…
+        458c32fb-4476-4431-97cb-49cfd069c31d Activities                     True      msdynce_Activities   Dynamics 365 worklo…
+        7553bb8a-fc5e-424c-9698-113958c28c98 Activities Patch               True      msdynce_ActivitiesP… Patch for Dynamics …
+        3ac10775-0808-42e0-bd23-83b6c714972f ActivitiesInfra Solution Anch… True      msft_ActivitiesInfr… ActivitiesInfra Sol…
+
+    .EXAMPLE
+        PS C:\> Get-BapEnvironmentSolution -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -IncludeManaged
+
+        This will query the specific environment.
+        It will list all solutions, unmanaged / managed.
+
+        Sample output:
+
+        SolutionId                           Name                           IsManaged SystemName           Description
+        ----------                           ----                           --------- ----------           -----------
+        169edc7d-5f1e-4ee4-8b5c-135b3ba82ea3 Access Team                    True      AccessTeam           Access Team solution
+        fd140aae-4df4-11dd-bd17-0019b9312238 Active Solution                False     Active               Placeholder solutio…
+        458c32fb-4476-4431-97cb-49cfd069c31d Activities                     True      msdynce_Activities   Dynamics 365 worklo…
+        7553bb8a-fc5e-424c-9698-113958c28c98 Activities Patch               True      msdynce_ActivitiesP… Patch for Dynamics …
+        3ac10775-0808-42e0-bd23-83b6c714972f ActivitiesInfra Solution Anch… True      msft_ActivitiesInfr… ActivitiesInfra Sol…
+
+    .EXAMPLE
+        PS C:\> Get-BapEnvironmentSolution -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -IncludeManaged -SolutionId 3ac10775-0808-42e0-bd23-83b6c714972f
+
+        This will query the specific environment.
+        It will list all solutions, unmanaged / managed.
+        It will search for the 3ac10775-0808-42e0-bd23-83b6c714972f solution.
+
+        Sample output:
+
+        SolutionId                           Name                           IsManaged SystemName           Description
+        ----------                           ----                           --------- ----------           -----------
+        3ac10775-0808-42e0-bd23-83b6c714972f ActivitiesInfra Solution Anch… True      msft_ActivitiesInfr… ActivitiesInfra Sol…
+
+    .EXAMPLE
+        PS C:\> Get-BapEnvironmentSolution -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -IncludeManaged -AsExcelOutput
+
+        This will query the specific environment.
+        It will list all solutions, unmanaged / managed.
+        Will output all details into an Excel file, that will auto open on your machine.
+
+    .NOTES
+        Author: Mötz Jensen (@Splaxi)
+#>
+function Get-BapEnvironmentSolution {
+    [CmdletBinding()]
+    [OutputType('System.Object[]')]
+    param (
+        [parameter (mandatory = $true)]
+        [string] $EnvironmentId,
+
+        [string] $SolutionId,
+
+        [switch] $IncludeManaged,
+
+        [switch] $AsExcelOutput
+    )
+
+    begin {
+        # Make sure all *BapEnvironment* cmdlets will validate that the environment exists prior running anything.
+        $envObj = Get-BapEnvironment -EnvironmentId $EnvironmentId | Select-Object -First 1
+
+        if ($null -eq $envObj) {
+            $messageString = "The supplied EnvironmentId: <c='em'>$EnvironmentId</c> didn't return any matching environment details. Please verify that the EnvironmentId is correct - try running the <c='em'>Get-BapEnvironment</c> cmdlet."
+            Write-PSFMessage -Level Host -Message $messageString
+            Stop-PSFFunction -Message "Stopping because environment was NOT found based on the id." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', '')))
+        }
+
+        if (Test-PSFFunctionInterrupt) { return }
+
+        $baseUri = $envObj.LinkedMetaPpacEnvUri
+        $tokenWebApi = Get-AzAccessToken -ResourceUrl $baseUri
+        $headersWebApi = @{
+            "Authorization" = "Bearer $($tokenWebApi.Token)"
+        }
+    }
+
+    process {
+        if (Test-PSFFunctionInterrupt) { return }
+
+        $localUri = $baseUri + '/api/data/v9.2/solutions'
+        $search = '?$filter=ismanaged eq false'
+
+        if (-not $IncludeManaged) {
+            $localUri += $search
+        }
+
+        $resSolutions = Invoke-RestMethod -Method Get -Uri $localUri -Headers $headersWebApi
+
+        $resCol = @(
+            foreach ($solObj in  $($resSolutions.value | Sort-Object -Property friendlyname)) {
+                if ((-not [System.String]::IsNullOrEmpty($SolutionId)) -and $solObj.SolutionId -ne $SolutionId) { continue }
+
+                $solObj | Select-PSFObject -TypeName "D365Bap.Tools.Solution" -Property "uniquename as SystemName",
+                "friendlyname as Name",
+                *
+            }
+        )
+
+        if ($AsExcelOutput) {
+            $resCol | Export-Excel
+            return
+        }
+
+        $resCol
+    }
+
+    end {
+
+    }
+}

d365bap.tools/tests/functions/Export-BapEnvironmentSolution.Tests.ps1

@@ -0,0 +1,62 @@
+Describe "Export-BapEnvironmentSolution Unit Tests" -Tag "Unit" {
+	BeforeAll {
+		# Place here all things needed to prepare for the tests
+	}
+	AfterAll {
+		# Here is where all the cleanup tasks go
+	}
+
+	Describe "Ensuring unchanged command signature" {
+		It "should have the expected parameter sets" {
+			(Get-Command Export-BapEnvironmentSolution).ParameterSets.Name | Should -Be '__AllParameterSets'
+		}
+
+		It 'Should have the expected parameter EnvironmentId' {
+			$parameter = (Get-Command Export-BapEnvironmentSolution).Parameters['EnvironmentId']
+			$parameter.Name | Should -Be 'EnvironmentId'
+			$parameter.ParameterType.ToString() | Should -Be System.String
+			$parameter.IsDynamic | Should -Be $False
+			$parameter.ParameterSets.Keys | Should -Be '__AllParameterSets'
+			$parameter.ParameterSets.Keys | Should -Contain '__AllParameterSets'
+			$parameter.ParameterSets['__AllParameterSets'].IsMandatory | Should -Be $True
+			$parameter.ParameterSets['__AllParameterSets'].Position | Should -Be 0
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipeline | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False
+		}
+		It 'Should have the expected parameter SolutionId' {
+			$parameter = (Get-Command Export-BapEnvironmentSolution).Parameters['SolutionId']
+			$parameter.Name | Should -Be 'SolutionId'
+			$parameter.ParameterType.ToString() | Should -Be System.String
+			$parameter.IsDynamic | Should -Be $False
+			$parameter.ParameterSets.Keys | Should -Be '__AllParameterSets'
+			$parameter.ParameterSets.Keys | Should -Contain '__AllParameterSets'
+			$parameter.ParameterSets['__AllParameterSets'].IsMandatory | Should -Be $True
+			$parameter.ParameterSets['__AllParameterSets'].Position | Should -Be 1
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipeline | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False
+		}
+		It 'Should have the expected parameter Path' {
+			$parameter = (Get-Command Export-BapEnvironmentSolution).Parameters['Path']
+			$parameter.Name | Should -Be 'Path'
+			$parameter.ParameterType.ToString() | Should -Be System.String
+			$parameter.IsDynamic | Should -Be $False
+			$parameter.ParameterSets.Keys | Should -Be '__AllParameterSets'
+			$parameter.ParameterSets.Keys | Should -Contain '__AllParameterSets'
+			$parameter.ParameterSets['__AllParameterSets'].IsMandatory | Should -Be $True
+			$parameter.ParameterSets['__AllParameterSets'].Position | Should -Be 2
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipeline | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False
+		}
+	}
+
+	Describe "Testing parameterset __AllParameterSets" {
+		<#
+		__AllParameterSets -EnvironmentId -SolutionId -Path
+		__AllParameterSets -EnvironmentId -SolutionId -Path
+		#>
+	}
+
+}