Use dynamic types for Microsoft Graph Bicep resources

The Microsoft Graph Bicep extension uses dynamic types which enables semantic versioning for both Microsoft Graph beta and v1.0. Using dynamic types allows for future breaking changes in existing Microsoft Graph Bicep resource types without impacting the deployment of your existing Bicep files that use older versions of those resource types. When you use dynamic types, a specific versioned Microsoft Graph Bicep types repo is referenced and fetched from the Microsoft Artifact Registry. These type versions are decoupled from the Bicep compiler NuGet package.

There are two ways to configure dynamic types either directly within the main.bicep file or with a user-friendly type version alias in the bicepconfig.json file which can be referenced in the main.bicep file.

Choose a type version

You need to add a reference to the Microsoft Graph Bicep resources types repo from the Microsoft Artifact Registry. To find the latest or appropriate repo version, go to the Microsoft Artifact Registry and search for "Microsoft Graph Bicep Extension". There are versions for both Microsoft Graph beta and v1.0.

Configure dynamic types in a Bicep file

In the main.bicep file, you can reference the Microsoft Graph Bicep types repo version to use, replacing the <v1.0-version> placeholder with the type version you want to use for Microsoft Graph v1.0.

extension 'br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:<v1.0-version>'

You can also specify a beta version in the same Bicep file and then use types from both versions.

extension 'br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:<v1.0-version>'
extension 'br:mcr.microsoft.com/bicep/extensions/microsoftgraph/beta:<beta-version>'

// using Microsoft Graph v1.0
resource group 'Microsoft.Graph/groups@v1.0' existing = {
    uniqueName: groupName
}

// using Microsoft Graph beta
resource app 'Microsoft.Graph/applications@beta' existing = {
    uniqueName: appName
}

Additionally, it's possible to declare resources that use older and newer Bicep type versions. The example shows how to use an older and newer type. It disambiguates between a type of the same name that's available in two different imported extensions, by using a fully qualified type name:

extension 'br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:<v1.0-version-latest>' as latestGraphV1
extension 'br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:<v1.0-version-older>' as olderGraphV1

// using the latest version of the Microsoft Graph v1.0 Bicep types
resource group 'latestGraphV1:Microsoft.Graph/groups@v1.0' existing = {
    uniqueName: groupName
}

// using and older version of the Microsoft Graph v1.0 Bicep types
resource app 'olderGraphV1:Microsoft.Graph/applications@v1.0' existing = {
    uniqueName: appName
}

Configure dynamic types in the Bicep config

You can specify a user-friendly alias that references the Microsoft Graph Bicep types repo version to use in the bicepconfig.json file, replacing the <v1.0-version> and <beta-version> placeholders with the type versions you want to use.

{  
    "experimentalFeaturesEnabled": {  
        "extensibility": true  
    },
    "extensions": {  
        "graphV1": "br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:<v1.0-version>",
        "graphBeta": "br:mcr.microsoft.com/bicep/extensions/microsoftgraph/beta:<beta-version>"  
    }  
}

Those aliases can then be used in a main.bicep file when specifying the extension to use. As shown, you can declare use of a v1.0 and beta extension which allows you to declare resources from Microsoft Graph v1.0 and Microsoft Graph beta versions.

extension graphV1
extension graphBeta

// using Microsoft Graph v1.0
resource group 'Microsoft.Graph/groups@v1.0' existing = {
    uniqueName: groupName
}

// using Microsoft Graph beta
resource app 'Microsoft.Graph/applications@beta' existing = {
    uniqueName: appName
}

Note

You can also declare aliases for different type versions from the same Microsoft Graph version (like a newer and older Bicep type version from Microsoft Graph v1.0) in the bicepconfig.json file and reference those aliases in the main.bicep file when importing extensions and declaring resources using fully qualified type names.

Migrate to using dynamic types from built-in types

Microsoft Graph Bicep types are also built into the Bicep compiler NuGet package. This NuGet package contains Microsoft Graph type definitions for both Microsoft Graph beta and v1.0. Built-in types were the only option available before September 2024.

Important

Built-in types are deprecated and will be retired on January 24, 2025. Until the retirement date, built-in types, denoted by extension microsoftGraph, will coexist with the new dynamic types. Any Microsoft Graph Bicep type changes will only be available through new versions of the dynamic types.

Switch to dynamic types from built-in types:

1. Launch VS Code and open the folder containing your main.bicep and bicepconfig.json files.

2. In the main.bicep file, there's a warning under the microsoftGraph built-in extension. Hover your cursor over the warning to see the details.

   

3. To fix the issue, select the Quick Fix link at the bottom of the warning details.