使用 Bicep 模块(预览版)Use Bicep modules (Preview)

使用 Bicep 可将复杂的解决方案分解为模块。Bicep enables you to break down a complex solution into modules. Bicep 模块是要一起部署的一个或多个资源的集。A Bicep module is a set of one or more resources to be deployed together. 模块抽象掉了原始资源声明的复杂细节,从而提高了可读性。Modules abstract away complex details of the raw resource declaration, which can increase readability. 可以重用这些模块并将其与他人共享。You can reuse these modules, and share them with other people. 将模块与模板规范相结合可以创建一种方式来实现模块化和代码重用。Combined with template specs, it creates a way for modularity and code reuse. Bicep 模块将转译为包含嵌套模板的单个 ARM 模板以进行部署。Bicep modules are transpiled into a single ARM template with nested templates for deployment. 在 Bicep 中,dependsOn 会自动进行处理。In Bicep, dependsOn gets handled automatically.

有关教程,请参阅教程:添加 Bicep 模块For a tutorial, see Tutorial: Add Bicep modules.

定义模块Define modules

可将每个 Bicep 文件用作模块。Every Bicep file can be consumed as a module. 模块只会按照协定向其他 Bicep 文件公开参数和输出。A module only exposes parameters and outputs as contract to other Bicep files. 参数和输出都是可选的。Both parameters and outputs are optional.

可以直接部署以下 Bicep 文件,以创建存储帐户或将其用作模块。The following Bicep file can be deployed directly to create a storage account or be used as a module. 下一部分将介绍如何使用模块:The next section shows you how to consume modules:

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Premium_LRS'
])
param storageSKU string = 'Standard_LRS'
param location string

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2019-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

输出用于将值传递给父 Bicep 文件。Output is used to pass values to the parent Bicep files.

使用模块Consume modules

通过 module 关键字使用模块。Use the module keyword to consume a module. 以下 Bicep 文件部署所引用的模块文件中定义的资源:The following Bicep file deploys the resource defined in the module file being referenced:

@minLength(3)
@maxLength(11)
param namePrefix string
param location string = resourceGroup().location

module stgModule './storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: namePrefix
    location: location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint
  • 模块:关键字。module: Keyword.

  • 符号名称 (stgModule):模块的标识符。symbolic name (stgModule): Identifier for the module.

  • 模块文件:在此示例中,模块的路径是使用相对路径 (./storageAccount.bicep) 指定的。module file: The path to the module in this example is specified using a relative path (./storageAccount.bicep). 必须使用正斜杠 (/) 目录分隔符来指定 Bicep 中的所有路径,以确保跨平台编译时的一致性。All paths in Bicep must be specified using the forward slash (/) directory separator to ensure consistent compilation cross-platform. 不支持 Windows 反斜杠 (\) 字符。The Windows backslash (\) character is unsupported.

  • 使用模块时,name 属性 (storageDeploy) 是必需的。The name property (storageDeploy) is required when consuming a module. 当 Bicep 生成模板 IL 时,此字段将用作为模块生成的嵌套部署资源的名称:When Bicep generates the template IL, this field is used as the name of the nested deployment resource, which is generated for the module:

    ...
    ...
    "resources": [
      {
        "type": "Microsoft.Resources/deployments",
        "apiVersion": "2020-10-01",
        "name": "storageDeploy",
        "properties": {
          ...
        }
      }
    ]
    ...
    

若要从模块中获取输出值,请使用如下所示的语法检索属性值:stgModule.outputs.storageEndpoint,其中 stgModule 是模块的标识符。To get an output value from a module, retrieve the property value with syntax like: stgModule.outputs.storageEndpoint where stgModule is the identifier of the module.

配置模块范围Configure module scopes

声明模块时,可以提供 scope 属性来设置部署模块的范围:When declaring a module, you can supply a scope property to set the scope at which to deploy the module:

module stgModule './storageAccount.bicep' = {
  name: 'storageDeploy'
  scope: resourceGroup('someOtherRg') // pass in a scope to a different resourceGroup
  params: {
    storagePrefix: namePrefix
    location: location
  }
}

当模块的目标范围和父级的目标范围相同时,可以省略 scope 属性。The scope property can be omitted when the module's target scope and the parent's target scope are the same. 未提供 scope 属性时,将在父级的目标范围部署模块。When the scope property is not provided, the module is deployed at the parent's target scope.

以下 Bicep 文件演示了如何创建资源组并将模块部署到资源组:The following Bicep file shows how to create a resource group and deploy a module to the resource group:

// set the target scope for this file
targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

param location string = deployment().location

var resourceGroupName = '${namePrefix}rg'
resource myResourceGroup 'Microsoft.Resources/resourceGroups@2020-01-01' = {
  name: resourceGroupName
  location: location
  scope: subscription()
}

module stgModule './storageAccount.bicep' = {
  name: 'storageDeploy'
  scope: myResourceGroup
  params: {
    storagePrefix: namePrefix
    location: location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

后续步骤Next steps