Next release

.devcontainer/devcontainer.json

@@ -0,0 +1,20 @@
+{
+	"image": "mcr.microsoft.com/powershell:latest",
+	"features": {
+		"ghcr.io/devcontainers/features/git:1": {},
+		"ghcr.io/natescherer/devcontainers-custom-features/powershell-resources": {
+			"resources": "d365bap.tools"
+		},
+		"ghcr.io/devcontainers/features/dotnet:2": {
+			"version": "8.0"
+		}
+	},
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"ms-vscode.powershell",
+				"ms-dotnettools.dotnet-interactive-vscode"
+			]
+		}
+	}
+}

README.md

@@ -58,6 +58,16 @@ Depending on which PowerShell console (v5 / v7+) - you will have different sign-
 Login-AzAccount -UseDeviceAuthentication -TenantId abd...
 ```
 
+## Learn interactively
+
+We have implemented a **Jupyter Notebook** to help you learn interactively about the different cmdlets / functions available in the module. The notebook is located inside the **'notebooks'** folder in this repository. Click this link [**notebooks**](/learning/notebooks/get-started.ipynb) to jump straight inside.
+
+While the notebook is already helpful in itself, its interactive nature will help you learn on another level. To do that, open the notebook in Visual Studio Code with the [Polyglot](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-interactive-vscode) extension installed.
+
+The repository also contains a [devcontainer](.devcontainer/devcontainer.json) that has everything installed to run the notebook. The easiest way to get started is to use GitHub Codespaces. Click the button below to start a new Codespace with the repository.
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/d365collaborative/d365bap.tools)
+
 ## Getting help
 
 [The wiki](https://github.com/d365collaborative/d365bap.tools/wiki) contains more details about installation and also guides to help you with some common tasks. It also contains documentation for all the module's commands. Expand the wiki's `Pages` control at the top of the content sidebar to view and search the list of command documentation pages.

d365bap.tools/d365bap.tools.psd1

@@ -44,6 +44,7 @@
 	FunctionsToExport = @(
 		'Compare-BapEnvironmentD365App'
 		, 'Compare-BapEnvironmentUser'
+		, 'Compare-BapEnvironmentVirtualEntity'
 
 		, 'Confirm-BapEnvironmentIntegration'
 
@@ -57,6 +58,10 @@
 		, 'Get-BapEnvironmentVirtualEntity'
 
 		, 'Invoke-BapEnvironmentInstallD365App'
+
+		, 'Set-BapEnvironmentVirtualEntity'
+
+		, 'Update-BapEnvironmentVirtualEntityMetadata'
 	)
 
 	# Cmdlets to export from this module

d365bap.tools/functions/Compare-BapEnvironmentD365App.ps1

@@ -4,7 +4,7 @@
         Compare environment D365 Apps
 
     .DESCRIPTION
-        This enables the user to compare 2 x environments, with one as a source and the other as a destination
+        Enables the user to compare 2 x environments, with one as a source and the other as a destination
 
         It will only look for installed D365 Apps on the source, and use this as a baseline against the destination
 

d365bap.tools/functions/Compare-BapEnvironmentUser.ps1

@@ -4,7 +4,7 @@
         Compare the environment users
 
     .DESCRIPTION
-        This enables the user to compare 2 x environments, with one as a source and the other as a destination
+        Enables the user to compare 2 x environments, with one as a source and the other as a destination
 
         It will only look for users on the source, and use this as a baseline against the destination
 

d365bap.tools/functions/Compare-BapEnvironmentVirtualEntity.ps1

@@ -0,0 +1,147 @@
+
+<#
+    .SYNOPSIS
+        Compare environment Virtual Entities
+
+    .DESCRIPTION
+        Enables the user to compare 2 x environments, with one as a source and the other as a destination
+
+        It will only look for enabled / visible Virtual Entities on the source, and use this as a baseline against the destination
+
+    .PARAMETER SourceEnvironmentId
+        Environment Id of the source environment that you want to utilized as the baseline for the compare
+
+    .PARAMETER DestinationEnvironmentId
+        Environment Id of the destination environment that you want to validate against the baseline (source)
+
+    .PARAMETER ShowDiffOnly
+        Instruct the cmdlet to only output the differences that are not aligned between the source and destination
+
+    .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:\> Compare-BapEnvironmentVirtualEntity -SourceEnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -DestinationEnvironmentId 32c6b196-ef52-4c43-93cf-6ecba51e6aa1
+
+        This will get all enabled / visible Virtual Entities from the Source Environment.
+        It will iterate over all of them, and validate against the Destination Environment.
+
+        Sample output:
+        EntityName                     SourceIsVisible SourceChangeTrackingEnabled Destination DestinationChange
+        IsVisible   TrackingEnabled
+        ----------                     --------------- --------------------------- ----------- -----------------
+        AccountantEntity               True            False                       True        False
+        CurrencyEntity                 True            False                       False       False
+        WMHEOutboundQueueEntity        True            False                       False       False
+
+    .EXAMPLE
+        PS C:\> Compare-BapEnvironmentVirtualEntity -SourceEnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -DestinationEnvironmentId 32c6b196-ef52-4c43-93cf-6ecba51e6aa1 -ShowDiffOnly
+
+        This will get all enabled / visible Virtual Entities from the Source Environment.
+        It will iterate over all of them, and validate against the Destination Environment.
+        It will filter out results, to only include those where the Source is different from the Destination.
+
+        Sample output:
+        EntityName                     SourceIsVisible SourceChangeTrackingEnabled Destination DestinationChange
+        IsVisible   TrackingEnabled
+        ----------                     --------------- --------------------------- ----------- -----------------
+        CurrencyEntity                 True            False                       False       False
+        WMHEOutboundQueueEntity        True            False                       False       False
+
+    .EXAMPLE
+        PS C:\> Compare-BapEnvironmentVirtualEntity -SourceEnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -DestinationEnvironmentId 32c6b196-ef52-4c43-93cf-6ecba51e6aa1
+
+        This will get all enabled / visible Virtual Entities from the Source Environment.
+        It will iterate over all of them, and validate against the Destination Environment.
+        Will output all details into an Excel file, that will auto open on your machine.
+
+    .NOTES
+        Author: Mötz Jensen (@Splaxi)
+#>
+function Compare-BapEnvironmentVirtualEntity {
+    [CmdletBinding()]
+    param (
+        [parameter (mandatory = $true)]
+        [string] $SourceEnvironmentId,
+
+        [parameter (mandatory = $true)]
+        [string] $DestinationEnvironmentId,
+
+        [switch] $ShowDiffOnly,
+
+        [switch] $AsExcelOutput
+    )
+
+    begin {
+        # Make sure all *BapEnvironment* cmdlets will validate that the environment exists prior running anything.
+        $envSourceObj = Get-BapEnvironment -EnvironmentId $SourceEnvironmentId | Select-Object -First 1
+
+        if ($null -eq $envSourceObj) {
+            $messageString = "The supplied SourceEnvironmentId: <c='em'>$SourceEnvironmentId</c> didn't return any matching environment details. Please verify that the SourceEnvironmentId 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 '<[^>]+>', '')))
+        }
+
+        # Make sure all *BapEnvironment* cmdlets will validate that the environment exists prior running anything.
+        $envDestinationObj = Get-BapEnvironment -EnvironmentId $DestinationEnvironmentId | Select-Object -First 1
+
+        if ($null -eq $envDestinationObj) {
+            $messageString = "The supplied DestinationEnvironmentId: <c='em'>$DestinationEnvironmentId</c> didn't return any matching environment details. Please verify that the DestinationEnvironmentId 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 }
+
+        $entitiesSourceEnvironment = @(Get-BapEnvironmentVirtualEntity -EnvironmentId $SourceEnvironmentId -VisibleOnly)
+        $entitiesDestinationEnvironment = @(
+            foreach ($entName in $entitiesSourceEnvironment.EntityName) {
+                Get-BapEnvironmentVirtualEntity -EnvironmentId $DestinationEnvironmentId -Name $entName
+            }
+        )
+    }
+
+    process {
+        if (Test-PSFFunctionInterrupt) { return }
+
+        $resCol = @(foreach ($sourceEntity in $($entitiesSourceEnvironment | Sort-Object -Property EntityName )) {
+                $destinationEntity = $entitiesDestinationEnvironment | Where-Object EntityName -eq $sourceEntity.EntityName | Select-Object -First 1
+
+                $tmp = [Ordered]@{
+                    EntityName                       = $sourceEntity.EntityName
+                    SourceIsVisible                  = $sourceEntity.IsVisible
+                    SourceChangeTrackingEnabled      = $sourceEntity.ChangeTrackingEnabled
+                    SourceEntityGuid                 = $sourceEntity.EntityGuid
+                    DestinationIsVisible             = ""
+                    DestinationChangeTrackingEnabled = ""
+                    DestinationEntityGuid            = ""
+                }
+
+                if (-not ($null -eq $destinationEntity)) {
+                    $tmp.DestinationIsVisible = $destinationEntity.IsVisible
+                    $tmp.DestinationChangeTrackingEnabled = $destinationEntity.ChangeTrackingEnabled
+                    $tmp.DestinationEntityGuid = $destinationEntity.EntityGuid
+                }
+
+                ([PSCustomObject]$tmp) | Select-PSFObject -TypeName "D365Bap.Tools.Compare.VirtualEntity"
+            }
+        )
+
+        if ($ShowDiffOnly) {
+            $resCol = $resCol | Where-Object { ($_.SourceIsVisible -ne $_.DestinationIsVisible) -or ($_.SourceChangeTrackingEnabled -ne $_.DestinationChangeTrackingEnabled) }
+        }
+
+        if ($AsExcelOutput) {
+            $resCol | Export-Excel -NoNumberConversion SourceVersion, DestinationVersion
+            return
+        }
+
+        $resCol
+    }
+
+    end {
+
+    }
+}

d365bap.tools/functions/Confirm-BapEnvironmentIntegration.ps1

@@ -68,6 +68,8 @@ function Confirm-BapEnvironmentIntegration {
     }
 
     process {
+        if (Test-PSFFunctionInterrupt) { return }
+
         $resValidate = Invoke-RestMethod -Method Get -Uri $($baseUri + '/api/data/v9.2/RetrieveFinanceAndOperationsIntegrationDetails') -Headers $headersWebApi
 
         $temp = $resValidate | Select-PSFObject -TypeName "D365Bap.Tools.Environment.Integration" -ExcludeProperty "@odata.context" -Property "Id as LinkedAppLcsEnvId",

d365bap.tools/functions/Get-BapEnvironment.ps1

@@ -4,7 +4,7 @@
         Get environment info
 
     .DESCRIPTION
-        This enables the user to query and validate all environments that are available from inside PPAC
+        Enables the user to query and validate all environments that are available from inside PPAC
 
         It utilizes the "https://api.bap.microsoft.com" REST API
 
@@ -67,7 +67,6 @@ function Get-BapEnvironment {
     }
 
     process {
-
         $resCol = @(
             foreach ($envObj in $resEnvs) {
                 if (-not ($envObj.Name -like $EnvironmentId)) { continue }
@@ -104,6 +103,7 @@ function Get-BapEnvironment {
                 @{Name = "LinkedMetaPpacOrgId"; Expression = { $envObj.Properties.linkedEnvironmentMetadata.resourceId } },
                 @{Name = "LinkedMetaPpacUniqueId"; Expression = { $envObj.Properties.linkedEnvironmentMetadata.uniqueName } },
                 @{Name = "LinkedMetaPpacEnvUri"; Expression = { $envObj.Properties.linkedEnvironmentMetadata.instanceUrl -replace "com/", "com" } },
+                @{Name = "LinkedMetaPpacEnvApiUri"; Expression = { $envObj.Properties.linkedEnvironmentMetadata.instanceApiUrl -replace "com/", "com" } },
                 @{Name = "LinkedMetaPpacEnvLanguage"; Expression = { $envObj.Properties.linkedEnvironmentMetadata.baseLanguage } },
                 @{Name = "PpacClusterIsland"; Expression = { $envObj.Properties.cluster.uriSuffix } },
                 "*"

d365bap.tools/functions/Get-BapEnvironmentApplicationUser.ps1

@@ -71,6 +71,8 @@ function Get-BapEnvironmentApplicationUser {
     }
 
     process {
+        if (Test-PSFFunctionInterrupt) { return }
+
         $resAppUsers = Invoke-RestMethod -Method Get -Uri $($baseUri + '/api/data/v9.2/applicationusers') -Headers $headersWebApi
         $resCol = @(
             foreach ($appUsrObj in  $($resAppUsers.value | Sort-Object -Property applicationname)) {

d365bap.tools/functions/Get-BapEnvironmentD365App.ps1

@@ -4,7 +4,7 @@
         Get D365 App from the environment
 
     .DESCRIPTION
-        This enables the user to analyze and validate the current D365 Apps and their state, on a given environment
+        Enables the user to analyze and validate the current D365 Apps and their state, on a given environment
 
         It can show all available D365 Apps - including their InstallState
 

d365bap.tools/functions/Get-BapEnvironmentUser.ps1

@@ -94,6 +94,8 @@ function Get-BapEnvironmentUser {
     }
 
     process {
+        if (Test-PSFFunctionInterrupt) { return }
+
         $resUsers = Invoke-RestMethod -Method Get -Uri $($baseUri + '/api/data/v9.2/systemusers?$select=fullname,internalemailaddress,applicationid&$expand=user_settings($select=uilanguageid)') -Headers $headersWebApi
 
         $resCol = @(

d365bap.tools/functions/Get-BapEnvironmentVirtualEntity.ps1

@@ -1,12 +1,12 @@
 
 <#
     .SYNOPSIS
-        Get Virutal Entity
+        Get Virtual Entity from environment
 
     .DESCRIPTION
         Enables the user to query against the Virtual Entities from the D365FO environment
 
-        This will help determine which Virtual Entities are already enabled / visible and their state
+        This will help determine which Virtual Entities are already enabled / visible and their state, as they are seeing from the Dataverse environment
 
     .PARAMETER EnvironmentId
         The id of the environment that you want to work against
@@ -80,6 +80,16 @@
         DimAttributeRetailTerminalEnt… False     False                 00002893-0000-0000-6e07-005001000000
         EcoResRetailProductEntity      False     False                 00002893-0000-0000-ae06-005001000000
 
+    .EXAMPLE
+        PS C:\> Get-BapEnvironmentVirtualEntity -EnvironmentId eec2c11a-a4c7-4e1d-b8ed-f62acc9c74c6 -Name AccountantEntity
+
+        This will fetch the specific virtual entity from the environment.
+
+        Sample output:
+        EntityName                     IsVisible ChangeTrackingEnabled EntityGuid
+        ----------                     --------- --------------------- ----------
+        AccountantEntity               False     False                 00002893-0000-0000-0003-005001000000
+
     .NOTES
         Author: Mötz Jensen (@Splaxi)
 #>
@@ -124,6 +134,8 @@ function Get-BapEnvironmentVirtualEntity {
     }
 
     process {
+        if (Test-PSFFunctionInterrupt) { return }
+
         $localUri = $($baseUri + '/api/data/v9.2/mserp_financeandoperationsentities')
 
         [System.Collections.Generic.List[System.String]]$filters = @()

d365bap.tools/functions/Invoke-BapEnvironmentInstallD365App.ps1

@@ -4,7 +4,7 @@
         Invoke the installation of a D365 App in a given environment
 
     .DESCRIPTION
-        This enables the invocation of the installation process against the PowerPlatform API (https://api.powerplatform.com)
+        Enables the invocation of the installation process against the PowerPlatform API (https://api.powerplatform.com)
 
         The cmdlet will keep requesting the status of all invoked installations, until they all have a NON "Running" state