Edit

Share via

Import and export blueprint definitions with PowerShell

  • Article

Important

On July 11, 2026, Blueprints (Preview) will be deprecated. Migrate your existing blueprint definitions and assignments to Template Specs and Deployment Stacks. Blueprint artifacts are to be converted to ARM JSON templates or Bicep files used to define deployment stacks. To learn how to author an artifact as an ARM resource, see:

Azure Blueprints can be fully managed through Azure portal. As organizations advance in their use of Azure Blueprints, they should start thinking of blueprint definitions as managed code. This concept is often referred to as Infrastructure as Code (IaC). Treating your blueprint definitions as code offers additional advantages beyond what Azure portal offers. These benefits include:

  • Sharing blueprint definitions
  • Backing up your blueprint definitions
  • Reusing blueprint definitions in different tenants or subscriptions
  • Placing the blueprint definitions in source control
    • Automated testing of blueprint definitions in test environments
    • Support of continuous integration and continuous deployment (CI/CD) pipelines

Whatever your reasons, managing your blueprint definitions as code has benefits. This article shows how to use the Import-AzBlueprintWithArtifact and Export-AzBlueprintWithArtifact commands in the Az.Blueprint module.

Prerequisites

This article assumes a moderate working knowledge of Azure Blueprints. If you haven't done so yet, work through the following articles:

If it isn't already installed, follow the instructions in Add the Az.Blueprint module to install and validate the Az.Blueprint module from the PowerShell Gallery.

Folder structure of a blueprint definition

Before looking at exporting and importing blueprints, let's look at how the files that make up the blueprint definition are structured. A blueprint definition should be stored in its own folder.

Important

If no value is passed to the Name parameter of the Import-AzBlueprintWithArtifact cmdlet, the name of the folder the blueprint definition is stored in is used.

Along with the blueprint definition, which must be named blueprint.json, are the artifacts that the blueprint definition is composed of. Each artifact must be in the subfolder named artifacts. Put together, the structure of your blueprint definition as JSON files in folders should look as follows:

.
|
|- MyBlueprint/  _______________ # Root folder name becomes default name of blueprint definition
|  |- blueprint.json  __________ # The blueprint definition. Fixed name.
|
|  |- artifacts/  ______________ # Subfolder for all blueprint artifacts. Fixed name.
|     |- artifact.json  ________ # Blueprint artifact as JSON file. Artifact named from file.
|     |- ...
|     |- more-artifacts.json

Export your blueprint definition

The steps to exporting your blueprint definition are straightforward. Exporting the blueprint definition can be useful for sharing, backup, or placing into source control.

  • Blueprint [required]
    • Specifies the blueprint definition
    • Use Get-AzBlueprint to get the reference object
  • OutputPath [required]
    • Specifies the path to save the blueprint definition JSON files to
    • The output files are in a subfolder with the name of the blueprint definition
  • Version (optional)
    • Specifies the version to output if the Blueprint reference object contains references to more than one version.

  1. Get a reference to the blueprint definition to export from the subscription represented as {subId}:

    # Login first with Connect-AzAccount if not using Cloud Shell

# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'MyBlueprint' -Version '1.1'

  2. Use the Export-AzBlueprintWithArtifact cmdlet to export the specified blueprint definition:

    Export-AzBlueprintWithArtifact -Blueprint $bpDefinition -OutputPath 'C:\Blueprints'

Import your blueprint definition

Once you have either an exported blueprint definition or have a manually created blueprint definition in the required folder structure, you can import that blueprint definition to a different management group or subscription.

For examples of built-in blueprint definitions, see the Azure Blueprints GitHub repo.

  • Name [required]
    • Specifies the name for the new blueprint definition
  • InputPath [required]
  • ManagementGroupId (optional)
    • The management group ID to save the blueprint definition to if not the current context default
    • Either ManagementGroupId or SubscriptionId must be specified
  • SubscriptionId (optional)
    • The subscription ID to save the blueprint definition to if not the current context default
    • Either ManagementGroupId or SubscriptionId must be specified

  1. Use the Import-AzBlueprintWithArtifact cmdlet to import the specified blueprint definition:

    # Login first with Connect-AzAccount if not using Cloud Shell

Import-AzBlueprintWithArtifact -Name 'MyBlueprint' -ManagementGroupId 'DevMG' -InputPath 'C:\Blueprints\MyBlueprint'

Once the blueprint definition is imported, assign it with PowerShell.

For information about creating advanced blueprint definitions, see the following articles:

Next steps