Provisioning New Unified Development Environments with PowerShell

Provisioning new environments using PowerShell is straightforward and efficient. For instance, you can create a basic development environment with the following command:

$templateMetadata = @{
    PostProvisioningPackages = @(
        @{
            applicationUniqueName = "msdyn_FinanceAndOperationsProvisioningAppAnchor"
            parameters = "DevToolsEnabled=true|DemoDataEnabled=false"
        }
    )
}
New-AdminPowerAppEnvironment `
    -DisplayName "Example Dev 1" `
    -EnvironmentSku Sandbox `
    -Templates "D365_FinOps_Finance" `
    -TemplateMetadata $templateMetadata `
    -LocationName "Canada" `
    -ProvisionDatabase `
    -WaitUntilFinished $false `

While this simple command initiates the creation of a new environment, managing the process effectively and handling potential errors requires additional parameters. One of the most important parameters, -WaitUntilFinished, determines whether the command waits for provisioning to complete before returning a response.

This article explores how this parameter affects the provisioning process and the structure of the response, providing guidance for building reliable automation.

In these examples, the location name Canada is used. For a complete list of available locations, refer to the Power Platform regions overview. You can also check the International availability of Dynamics 365 for regional support details.

The Importance of the -WaitUntilFinished Parameter

A critical aspect of environment provisioning is understanding how the -WaitUntilFinished parameter impacts the response and, consequently, your automation workflows. Depending on its use, the command either returns a minimal asynchronous response or waits to provide detailed information about the provisioned environment.

Without -WaitUntilFinished

When the -WaitUntilFinished switch is not used, the response primarily consists of a status code, such as HTTP 202, indicating that the request has been accepted for processing. This is an asynchronous process, so no immediate details about the environment are provided.

This is particularly useful in scenarios where automation scripts need to queue multiple environment creations without waiting for each to finish. However, additional monitoring logic will be required to track progress.

With -WaitUntilFinished

Using the -WaitUntilFinished switch provides a more detailed response, including information about the provisioned environment. This includes the environment's name, type, and URLs for Dataverse and Finance and Operations (FO) applications.

This synchronous approach is preferable in automation scenarios where real-time feedback or immediate validation of environment details is required. However, it requires configuring the -TimeoutInMinutes parameter appropriately to avoid timeouts.

Typical Responses

The response format depends on whether the -WaitUntilFinished switch is used.

Asynchronous Provisioning (Without -WaitUntilFinished)

When the -WaitUntilFinished switch is not used, the response looks like this:

{
    "Code": 202,
    "Description": "Accepted",
    "Headers": { ... },
    "Error": null,
    "Errors": null,
    ...
}

This response confirms that the request has been accepted. The actual provisioning happens in the background, and you may need additional logic to monitor its status.

Synchronous Provisioning (With -WaitUntilFinished)

When the -WaitUntilFinished switch is used, the response provides detailed information about the provisioned environment. An example response might look like this:

{
    "EnvironmentName": "12345678-abcd-1234-efgh-567890abcdef",
    "DisplayName": "Example Dev 1 (exampledev1)",
    "Description": "",
    "IsDefault": false,
    "Location": "Canada",
    "CreatedTime": "2024-11-27T08:00:00.0000000Z",
    "CreatedBy": {
        "id": "98765432-1234-5678-90ab-1234567890ab",
        "displayName": "Example User",
        "type": "User",
        "tenantId": "abcdef12-3456-7890-abcd-ef1234567890",
        "userPrincipalName": "example.user@example.com"
    },
    "LastModifiedTime": "2024-11-27T09:30:00.0000000Z",
    "LastModifiedBy": null,
    "CreationType": "User",
    "EnvironmentType": "Sandbox",
    ...
    "Internal": {
        "properties": {
            "finOpsMetadata": {
                "url": "https://exampledev1.operations.dynamics.com"
            },
            "linkedEnvironmentMetadata": {
                "instanceUrl": "https://exampledev1.crm4.dynamics.com"
            }
        }
    }
}

Error Handling and Example Script

Error handling is critical when provisioning environments to ensure reliability and maintain control over operations. The -WaitUntilFinished parameter determines whether the process runs synchronously or asynchronously, significantly impacting both the behavior and structure of the response. Configuring the -TimeoutInMinutes parameter is equally important, as it must provide sufficient time for the provisioning process to complete when running synchronously.

Below is an updated example script that reflects the command introduced earlier and demonstrates conditional response handling based on whether the -WaitUntilFinished parameter is used:

$response = New-AdminPowerAppEnvironment `
    -WaitUntilFinished $waitUntilFinished `
    -DisplayName "Example Dev 1" `
    -EnvironmentSku Sandbox `
    -Templates "D365_FinOps_Finance" `
    -TemplateMetadata $templateMetadata `
    -LocationName "Canada" `
    -ProvisionDatabase `
    -TimeoutInMinutes 360

if ($waitUntilFinished) {
    $envName = $response.EnvironmentName
    $envType = $response.EnvironmentType
    $url = $response.Internal.properties.linkedEnvironmentMetadata.instanceUrl
    $foUrl = $response.Internal.properties.finOpsMetadata.url

    Write-Host "Environment Provisioned Successfully:"
    Write-Host "Name: $envName"
    Write-Host "Type: $envType"
    Write-Host "Dataverse URL: $url"
    Write-Host "FO URL: $foUrl"
} else {
    Write-Host "Provisioning initiated. Response Code: $($response.Code)"
}

Summary

The response format of the New-AdminPowerAppEnvironment command varies significantly depending on the use of the -WaitUntilFinished parameter. Using this switch provides detailed real-time feedback, including environment metadata and URLs, while requiring an appropriately configured timeout. Without the switch, the command initiates provisioning asynchronously, returning only minimal status information. Proper error handling is essential to manage issues such as timeouts, template errors, or network delays, ensuring the reliability and robustness of your automation processes.

Documentation for setting up a new environment can be found on Microsoft Learn.