DOCSEARCHbyAlgolia
Submit Docs

Power Platform Build Tools

repository·main·Indexed 43 days ago

https://github.com/microsoft/powerplatform-build-tools

Azure DevOps tasks for Power Platform that automate build and deployment workflows by wrapping the Power Platform CLI (pac CLI). Key capabilities include solution synchronization, artifact generation, environment provisioning, and static analysis using the PowerApps checker service. Version 2 (v2) provides cross-platform support for Windows and Linux agents (with some exceptions) and supports authentication via Service Principals for MFA-enabled tenants.

Tokens
17.2K
Snippets
46
Records
62
Agent score
55%

What's inside Power Platform Build Tools

  1. Overview of Power Platform Build Tools

    main

    Power Platform Build Tools is a set of automation tools designed to handle common build and deployment tasks for the Power Platform. The tools are designed to wrap the existing Power Platform CLI to provide streamlined automation for DevOps workflows.

    Key capabilities include:

    • Solution Synchronization: Moving solution metadata (solutions) between development environments and source control.
    • Artifact Generation: Creating build artifacts from your solutions.
    • Deployment: Deploying solutions to downstream environments.
    • Environment Management: Provisioning and de-provisioning environments.
    • Static Analysis: Performing checks against your solutions using the PowerApps checker service.

  2. Use BuildTools pipeline variables for environment metadata

    main

    Certain environment management tasks (Create, Copy, and Restore Environment) automatically create or overwrite specific pipeline variables to help downstream tasks identify the target environment.

    Automatically created variables:

    • BuildTools.OrganizationId: The organization ID of the connected environment.
    • BuildTools.OrgUniqueName: The unique name of the connected environment.
    • BuildTools.EnvironmentUrl: The URL of the newly created or restored environment.

    Usage Pattern: Other tasks in your pipeline can reference the environment URL by using the BuildTools.EnvironmentUrl variable. If this variable is not defined, tasks will default to using the URL from the active ServiceConnection.

  4. Authenticate Power Platform tasks using Service Principals

    main

    For modern, MFA-enabled tenants, the preferred authentication method is using an Azure DevOps ServiceConnection of type Power Platform with a Service Principal (AppID) and Client Secret.

    Setup Steps:

    1. Create and configure an Azure AppID/Service Principal and Client Secret.
    2. Follow the configuration guide at: https://aka.ms/buildtools-spn
    3. Use the Power Platform ServiceConnection type in Azure DevOps to provide these credentials to the tasks.

    Note on Username/Password Authentication: Generic ServiceConnections using username/password are supported but are not MFA capable because Azure DevOps tasks run in a non-interactive context. If your tenant requires MFA, you must use the Service Principal method.

  5. Migrate from v0 to v2 Power Platform Build Tools tasks

    main

    Tasks in version 2 (v2) are implemented using the Power Platform CLI (pac CLI). To benefit from new features and fixes, you must migrate your pipelines to version 2.

    Critical Constraints:

    • No Mixed Versions: You cannot mix v0 and v2 tasks in the same pipeline. You must migrate all tasks to v2.
    • Cross-Platform Support: Most v2 tasks can run on either Windows or Linux build agents, with the exception of the Package Deploy task, which requires Windows.

    For migration guidance, refer to the official migration documentation at https://aka.ms/pp-bt-migrate-to-v2.

  6. Download Code Site task

    main

    The download-code-site-v2 task is used to download code sites. It is designed to run within an Azure Pipelines agent environment. The task automatically resolves credentials and the environment URL from the host environment and requires specific parameters to identify the target website and destination path.

    {
  "DownloadPath": "<path_to_destination>",
  "WebsiteId": "<website_id>",
  "Overwrite": "<true|false>"
}

  7. Security validation requirements for PAC paths

    main

    The validatePacPath function enforces strict security constraints on the path provided via POWERPLATFORMTOOLS_PACCLIPATH. To pass validation, the path must meet the following criteria:

    1. Operating System: Must be win32 or linux.
    2. Path Format: Must be a fully qualified platform path without directory traversal (..), null characters, or device namespaces.
    3. Task Cache Integrity: The path must reside within the trusted task cache directory established by the PowerPlatformToolInstaller task.
    4. Directory Structure: The path must follow a specific hierarchy: PowerPlatformToolInstaller_GUID/v2.x.x/bin.
    5. Executable Verification: The path must contain a valid pac (Linux) or pac.exe (Windows) executable within a tools subdirectory, and all components must be located within the verified installation directory.

    If validation fails, the tool throws an error indicating that the PowerPlatformToolInstaller@2 task may not have run or that the environment variable has been tampered with.

  8. How task output variables are resolved

    main

    When a task requires a variable (e.g., an Environment URL), the build tools look for it using a specific priority order to ensure compatibility between different pipeline setups:

    1. Pipeline Variables: It first checks for a standard pipeline variable matching the requested name.
    2. Task Output Variables: If no pipeline variable is found, it searches for output variables generated by specific Power Platform tasks. The search follows this priority order for task origins:
      • PowerPlatformCreateEnvironment
      • PowerPlatformCopyEnvironment
      • PowerPlatformResetEnvironment
      • PowerPlatformRestoreEnvironment

    When searching task outputs, the tool converts the variable name by replacing dots (.) and hyphens (-) with underscores (_). For example, if looking for BuildTools.EnvironmentUrl, it will check for PowerPlatformCreateEnvironment_BuildTools_EnvironmentUrl.

  9. How the environment URL is resolved

    main

    The Power Platform Build Tools resolve the target environment URL using a specific hierarchy of precedence. If you need to override the default environment URL used by a task, you can provide it via one of the following methods, in order of priority:

    1. Explicit Task Input: Provide the URL directly in the Environment input parameter of the task. If the input is an Azure DevOps variable expression (e.g., $(MyEnvUrl)), the tool will resolve it to the variable name.
    2. Pipeline/Task Output Variables: The tool looks for a variable matching the name defined by EnvUrlVariableName. This is commonly used when a previous task (like a createEnv task) outputs the environment URL as a variable.
    3. OS Environment Variables: The tool checks for a system environment variable matching the EnvUrlVariableName.
    4. Service Connection Fallback: If no other method provides a URL, the tool falls back to the endpoint URL configured within the Azure DevOps Service Connection used by the task.

  10. Delete a Power Platform solution

    main

    The delete-solution task allows you to remove a specific solution from a Power Platform environment. This task is designed to run within an Azure DevOps pipeline agent. It automatically retrieves environment credentials and the environment URL from the host environment.

    To use this task, you must provide the SolutionName parameter. If agent.diagnostic is set to true in your pipeline environment, the task will enable verbose console logging.

    # Example Azure DevOps task usage
- task: DeleteSolutionV2@2
  inputs:
    SolutionName: 'YourSolutionName'

  11. Use Set Connection Variables task to configure authentication

    main

    The set-connection-variables-v2 task automates the creation of environment URLs and Dataverse connection strings by extracting credentials from Azure DevOps Service Connections. It supports two primary authentication modes: PowerPlatformSPN (Service Principal) and PowerPlatformEnvironment (User-based OAuth).

    Authentication Modes

    1. PowerPlatformSPN

    Used when using a Service Principal. It requires a Service Connection configured with applicationId, clientSecret, and tenantId.

    Outputs:

    • EnvUrlVariableName: The environment URL.
    • ApplicationIdlVariableName: The Client ID.
    • ClientSecretVariableName: The Client Secret.
    • TenantIdVariableName: The Tenant ID.
    • DataverseConnectionStringVariableName: A connection string formatted as: AuthType=ClientSecret;url={url};ClientId={id};ClientSecret={secret}.

    2. PowerPlatformEnvironment

    Used for user-based authentication. It requires a Service Connection configured with UserName and Password, plus manual inputs for ApplicationId and RedirectUri.

    Outputs:

    • EnvUrlVariableName: The environment URL.
    • UserNameVariableName: The username.
    • PasswordVariableName: The password.
    • DataverseConnectionStringVariableName: A connection string formatted as: AuthType=OAuth;url={url};UserName={user};Password={pass};AppId={appId};RedirectUri={uri}.

  12. Reset an environment using the Reset Environment task

    main

    The reset-environment-v2 task allows you to reset a Power Platform environment to a specific state using templates, language, and currency settings.

    When the task completes successfully, it sets the following pipeline output variables which can be used in subsequent tasks:

    • environmentUrl: The URL of the reset environment.
    • environmentId: The unique ID of the reset environment.

    If the task completes but fails to return an environment URL or ID, it will report a status of SucceededWithIssues.