Erweiterbare Parameterdateien in Bicep

Mithilfe erweiterbarer Bicep Parameterdateien können Sie Parameter einmal in einer Basisparameterdatei definieren und für mehrere abgeleitete Parameterdateien wiederverwenden. Dieser Ansatz verbessert die Wiederverwendbarkeit von Parametern erheblich und sorgt für Konsistenz in allen Bereitstellungen. Bicep CLI Version 0.44.1 und höher unterstützt erweiterbare Parameterdateien sowie die extends und base Schlüsselwörter.

Eine abgeleitete Parameterdatei kann nur eine Basisparameterdatei erweitern. Sie kann nur eine extends Anweisung enthalten. Sie können jedoch geschachtelte Parameterdateien erstellen, indem Sie Erweiterungen über mehrere Dateien hinweg verketten. Weitere Informationen finden Sie unter Geschachtelte Parameterdateien.

Die extends Anweisung erbt nur Parameterzuweisungen.

• Sie können Variablen in der Basisparameterdatei definieren, um die Parameterwerte zu berechnen, diese Variablen werden jedoch nicht für abgeleitete Parameterdateien verfügbar gemacht.
• Sie können benutzerdefinierte Typen in Parameterdateien definieren. Sie können auch benutzerdefinierte Typen importieren, die in einer Bicep Datei definiert sind. Diese benutzerdefinierten Typen werden jedoch nicht für abgeleitete Parameterdateien verfügbar gemacht.
• Sie können benutzerdefinierte Funktionen nicht direkt in einer Parameterdatei deklarieren. Sie können sie jedoch in eine Parameterdatei importieren . Diese Funktionen werden nicht für abgeleitete Parameterdateien verfügbar gemacht.

Parameterdatei erweitern

Standardmäßig überschreiben die Parameter, die Sie in einer abgeleiteten Parameterdatei definieren, die Parameter in der Basisparameterdatei vollständig. Verwenden Sie zum Zusammenführen anstatt zu überschreiben das Schlüsselwort base mit der Spread-Syntax für Objekte oder Arrays. Weitere Informationen finden Sie unter Zugriff auf übergeordnete Parameter.

Verwenden Sie die using none Anweisung in Basisparameterdateien, um den Compiler anzuweisen, sie nicht an eine bestimmte Bicep Datei zu binden oder zu überprüfen.

Im folgenden Beispiel wird veranschaulicht, wie erweiterbare Parameterdateien in Bicep funktionieren.

Ihre primäre Bicep-Vorlage, main.bicep, definiert die Parameter, die Ihre Bereitstellung annimmt.

param namePrefix string
param location string
param tags object

Eine Basisparameterdatei, base.bicepparamdie Sie in mehreren Bereitstellungen und Umgebungen wiederverwenden können.

using none
// Notice that the first line of this .bicepparam file declares `using none` which tells the compiler not to validate this against any particular .bicep file.

param namePrefix = 'Prod'
param location = 'westus'
param tags = {
  environment: 'dev'
  owner: 'platform'
}

Eine erweiterte Parameterdatei, derived.bicepparamdie auf der Basisparameterdatei basiert. Sie verweist sowohl auf die Bicep-Datei als auch auf die Basisparameterdatei. Werte, die Sie hier definieren, setzen vorherige außer Kraft.

using 'main.bicep'

extends 'base.bicepparam'

param namePrefix = 'Dev'
param tags = {
  ...base.tags        // inherit the object from the base file
  environment: 'prod' // override a single property
  region: 'westus2'   // add new data
}

In diesem Beispiel werden Parameterwerte in Ebenen mit einer klaren Rangfolge angewendet. Die main.bicep Datei deklariert Parameter und kann Standardwerte bereitstellen. Eine abgeleitete.bicepparam Datei kann Werte überschreiben, die in einer Basisdatei.bicepparam definiert sind, und die endgültig zugewiesenen Parameterwerte haben Vorrang vor allen in der Zielvorlage definierten Standardwerten. Die aufgelösten Werte sind:

Auf übergeordnete Parameter zugreifen

Um das base Schlüsselwort zu verwenden, muss die abgeleitete Parameterdatei eine extends Klausel enthalten. Diese Klausel macht base als Bezeichner verfügbar, sodass Sie auf alle übergeordneten Parameter als Eigenschaften zugreifen können. Wenn Sie versuchen, base ohne eine extends-Klausel zu verwenden, erhalten Sie einen Fehler.

Sie können den Spread-Operator (...)base kombinieren, um komplexe Datentypen sauber zu erweitern oder zusammenzuführen. Mit diesem Ansatz können Sie vorhandene Array- oder Objektwerte aus der übergeordneten Datei kopieren und ändern, ohne die gesamte Datenstruktur neu einzugeben. Der Spread-Operator ist streng auf Objekte und Arrays beschränkt. Wenn Sie versuchen, einen Grundtypwert wie eine Zeichenfolge, eine ganze Zahl oder einen booleschen Wert zu verteilen, führen Sie zu einem Kompilierungsfehler.

Alle überschriebenen Werte müssen mit dem genauen Datentyp übereinstimmen, der vom Zielparameter erwartet wird. Das Bereitstellen eines inkompatiblen Typs führt während der Kompilierung zu einem Typfehler.

Die Bicep Datei "main.bicep":

param app object
param locations array
param fullName string

Die Basisparameterdatei base.bicepparam:

using none

param app = {
  name: 'demo'
  tags: {
    owner: 'platform'
    environment: 'dev'
  }
}
param locations = ['westus', 'eastus']

Die abgeleitete Parameterdatei derived.bicepparam:

using './main.bicep'
extends './base.bicepparam'

// Merge objects
param app = {
  ...base.app
  tags: {
    ...base.app.tags
    environment: 'prod'
    costCenter: '1234'
  }
}

// Merge arrays
param locations = [...base.locations, 'centralus']

// Use base in expressions or variables
var suffix = '-api'
param fullName = '${base.app.name}${suffix}'

Die aufgelösten Werte sind:

Geschachtelte Parameterdateien

Eine abgeleitete Parameterdatei kann zwar nur eine einzelne extends Anweisung enthalten, Bicep ermöglicht es Ihnen jedoch, Hierarchien mit mehreren Ebenen zu erstellen, indem Sie Parameterdateien sequenziell verketten (Parameterdatei A $\rightarrow$ Parameter File B $\rightarrow$ Parameter File C).

Diese Struktur ist nützlich zur Organisation von Bereitstellungen in Unternehmen. Sie können globale Standardwerte im Stammverzeichnis definieren, umgebungsweite Einstellungen auf der mittleren Ebene außer Kraft setzen und lokalisierte, ressourcenspezifische Konfigurationen auf Blattebene angeben.

Wenn Sie eine Kette erstellen, muss jede Zwischen- oder Stammparameterdatei in der Sequenz die using none Anweisung enthalten. Diese Anweisung signalisiert dem Bicep Compiler, dass die Datei streng als Konfigurationsschicht fungiert und nicht direkt an eine bestimmte .bicep Bereitstellungsvorlage gebunden wird.

Das folgende Beispiel zeigt, wie Sie eine dreistufige Kette einrichten können, um ein Azure Ressourcenlayout zu konfigurieren und von globalen Organisationseinstellungen zu einer bestimmten lokalisierten Entwicklungsumgebung zu wechseln.

Die Bicep-Datei (compute.bicep)

param primaryLocation string

param globalTags object 
param environmentTags object
param resourceTags object

param skuName string
param vmSku string
param vmName string
...

Die Stammebene: globale Standardwerte (global.bicepparam) richtet die Basisplaneigenschaften ein, die in der gesamten Organisation verwendet werden. Es verwendet using none, da es rein als Konfigurationsbasis dient.

using none

// Global baseline tags applied to every single resource
param globalTags = {
  BillingUnit: 'Enterprise-IT'
  DataClassification: 'Confidential'
}

// Default regional pair
param primaryLocation = 'eastus'

Die Zwischenebene: Umgebungseinstellungen (dev-defaults.bicepparam) erbt die globalen Eigenschaften, überschreibt den Umgebungstyp und fügt umgebungsspezifische Konfigurationen an. Da es sich um eine Zwischenschicht handelt, wird using noneauch verwendet.

using none
extends './global.bicepparam'

// Inherit global tags and inject the environment designation
param environmentTags = {
  ...base.globalTags
  Environment: 'Development'
}

// Override region for low-cost development testing
param primaryLocation = 'westus'

// Tier-specific infrastructure sizes
param skuName = 'Standard_D2s_v5'

Die Leaf-Ebene: gezielte Bereitstellung (compute.dev.bicepparam) zielt auf die Bereitstellung einer bestimmten Workload ab. Es stellt über die Standardanweisung using eine direkte Verbindung zur eigentlichen Bicep-Infrastrukturvorlage her und erbt dabei den gesamten kombinierten Zustand der Kette.

extends './dev-defaults.bicepparam'
using './compute.bicep' // Binds the final resolved values to the template

// Combine all inherited layers into the final parameters expected by compute.bicep
param resourceTags = {
  ...base.environmentTags
  Workload: 'Web-FrontEnd'
}

// Use inherited environment SKU directly, or override it if needed
param vmSku = base.skuName

// Explicit deployment property
param vmName = 'vm-web-dev-01'

Verwandte Inhalte

• Informationen zu Bicep Parameterdateien finden Sie unter Bicep Parameterdatei.
• Weitere Informationen zu using und using none finden Sie unter Verwenden von Anweisungen und Nicht-Anweisungen.
• Weitere Informationen zum Spread-Operator finden Sie unter Spread-Operator.