Freigeben über

Schnellstart: Fehlerbehebung bei der Bereitstellung von Bicep-Dateien

In dieser Schnellstartanleitung wird beschrieben, wie Sie Bicep-Dateibereitstellungsfehler beheben. Sie erstellen eine Datei mit Fehlern und erfahren, wie Sie die Fehler beheben.

Es gibt drei Arten von Fehlern, die mit einer Bereitstellung zusammenhängen:

  • Validierungsfehler treten auf, bevor eine Bereitstellung beginnt und werden durch Syntaxfehler in Ihrer Datei verursacht. Mit einem Code-Editor wie Visual Studio Code können diese Fehler identifiziert werden.
  • Preflight-Überprüfungsfehler treten auf, wenn ein Bereitstellungsbefehl ausgeführt wird, ressourcen jedoch nicht bereitgestellt werden. Diese Fehler werden gefunden, ohne dass die Bereitstellung gestartet wird. Wenn zum Beispiel ein Parameterwert falsch ist, wird der Fehler bei der Preflight-Validierung gefunden.
  • Bereitstellungsfehler treten während des Bereitstellungsprozesses auf und können nur gefunden werden, indem der Fortschritt der Bereitstellung in Ihrer Azure-Umgebung bewertet wird.

Alle Fehlertypen geben einen Fehlercode zurück, den Sie bei der Fehlersuche in der Bereitstellung verwenden können. Validierungs- und Preflight-Fehler werden im Aktivitätsprotokoll angezeigt, aber nicht im Bereitstellungsverlauf. Eine Bicep-Datei mit Syntaxfehlern wird weder in JSON kompiliert noch im Aktivitätsprotokoll angezeigt.

Voraussetzungen

Um diesen Schnellstart durchzuführen, benötigen Sie die folgenden Gegenstände:

Erstellen einer Bicep-Datei mit Fehlern

Kopieren Sie die folgende Bicep-Datei, und speichern Sie sie lokal. Sie verwenden diese Datei, um einen Validierungsfehler, einen Preflight-Fehler und einen Bereitstellungsfehler zu beheben. In dieser Schnellstartanleitung wird davon ausgegangen, dass Sie die Datei "troubleshoot.bicep " benannt haben, aber Sie können ihm einen beliebigen Namen geben.

@description('SKU for the storage account')
@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
parameter storageAccountType string = 'Standard_LRS'

@description('Prefix for storage name.')
param prefixName string

var storageAccountName = '${prefixName}${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  ___location: resourceGroup().___location
  sku: {
    name: storageAccountType
  }
  kind: 'StorageV2'
  properties: {}
}

resource existingVNet 'Microsoft.Network/virtualNetworks@2021-03-01' existing = {
  name: 'doesnotexist'
}

output storageAccountName string = storageAccountName
output vnetResult object = existingVNet

Validierungsfehler beheben

Öffnen Sie die Datei in Visual Studio Code. Sie werden feststellen, dass Visual Studio Code einen Syntaxfehler identifiziert. Die erste Parameterdeklaration ist mit roten Schnörkeln markiert, um einen Fehler anzuzeigen.

Screenshot: Visual Studio Code mit roten Wellenlinien, die einen Syntaxfehler in einer Bicep-Datei hervorheben

Die Zeilen, die mit einem Fehler gekennzeichnet sind, sind:

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
parameter storageAccountType string = 'Standard_LRS'

Wenn Sie mit der Maus darauf zeigen parameter, wird eine Fehlermeldung angezeigt.

Screenshot einer detaillierten Fehlermeldung, die in Visual Studio Code beim Zeigen auf einen Syntaxfehler in einer Bicep-Datei angezeigt wird.

Die Meldung lautet: Dieser Deklarationstyp wird nicht erkannt. Geben Sie einen Parameter, eine Variable, eine Ressource oder eine Ausgabedeklaration an. Sollten Sie versuchen, diese Datei bereitzustellen, erhalten Sie dieselbe Fehlermeldung aus dem Bereitstellungsbefehl.

Wenn Sie sich die Dokumentation für eine Parameterdeklaration ansehen, werden Sie feststellen, dass das Schlüsselwort tatsächlich param ist. Wenn Sie diese Syntax ändern, wird der Überprüfungsfehler ausgeblendet. Der @allowed Dekorateur wurde auch als Fehler gekennzeichnet, aber dieser Fehler wird auch durch Ändern der Parameterdeklaration behoben. Das Decorator-Element wurde als Fehler markiert, weil nach dem Decorator eine Parameterdeklaration erwartet wird. Diese Bedingung war nicht wahr, wenn die Deklaration falsch war.

Die korrigierte Zeile lautet:

param storageAccountType string = 'Standard_LRS'

Preflight-Fehler beheben

Nachdem Sie den Überprüfungsfehler behoben haben, ist es an der Zeit, die Datei bereitzustellen. Wenn Sie einen falschen Parameterwert angeben, wird ein Preflight-Fehler angezeigt.

az group create --name troubleshootRG --___location westus
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.bicep \
  --parameters prefixName=longNamewith!!Charactersthatarenotallowed

Azure Resource Manager bestimmt, dass der Name des Speicherkontos Zeichen enthält, die nicht zulässig sind. Es wird nicht versucht, die Bereitstellung zu starten.

Es wird eine Fehlermeldung angezeigt, die angibt, dass die Vorabüberprüfung fehlgeschlagen ist. Sie erhalten auch eine Meldung, die besagt, dass der Name des Speicherkontos zwischen 3 und 24 Zeichen lang sein muss und nur Zahlen und Kleinbuchstaben verwenden. Das von Ihnen angegebene Präfix erfüllt diese Anforderung nicht. Weitere Informationen zu diesem Fehlercode finden Sie unter Beheben von Fehlern für Speicherkontonamen.

Da der Fehler beim Preflight aufgetreten ist, wird im Verlauf keine Bereitstellung angezeigt.

Screenshot des Abschnitts

Die fehlgeschlagene Bereitstellung ist jedoch im Aktivitätsprotokoll vorhanden.

Screenshot: Aktivitätsprotokoll für das Azure-Portal, in dem ein Preflight-Validierungsfehler für eine Bereitstellung der Bicep-Datei angezeigt wird

Sie können Details des Protokolleintrags öffnen, um die Fehlermeldung anzuzeigen.

Einsatzfehler beheben

Sie stellen die Datei erneut bereit und geben einen zulässigen Wert für den Namenspräfixparameter an.

az group create --name troubleshootRG --___location westus
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.bicep \
  --parameters prefixName=stg

Die Bereitstellung wird gestartet, schlägt jedoch fehl mit einer Meldung, dass das virtuelle Netzwerk nicht gefunden wurde. Normalerweise würden Sie diesen Fehler beheben, indem Sie den Verweis auf die Ressource ändern. In dieser Schnellstartanleitung löschen Sie den Verweis. Weitere Informationen zu diesem Fehlercode finden Sie unter Beheben von Fehlern des Typs „Ressource nicht gefunden“.

Beachten Sie im Portal, dass die Bereitstellung in der Historie angezeigt wird.

Screenshot des Abschnitts

Sie können den Eintrag im Bereitstellungsverlauf öffnen, um Details zum Fehler zu erhalten. Der Fehler ist auch im Aktivitätsprotokoll vorhanden.

Die Bicep-Datei versucht, auf ein virtuelles Netzwerk zu verweisen, das in Ihrer Ressourcengruppe nicht vorhanden ist. Löschen Sie den Verweis auf das vorhandene virtuelle Netzwerk, um den Fehler zu beheben.

@description('SKU for the storage account')
@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

@description('Prefix for storage name.')
param prefixName string

var storageAccountName = '${prefixName}${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  ___location: resourceGroup().___location
  sku: {
    name: storageAccountType
  }
  kind: 'StorageV2'
  properties: {}
}

output storageAccountName string = storageAccountName

Sie können diese Bicep-Datei ohne Fehler bereitstellen.

Bereinigen von Ressourcen

Wenn die Azure-Ressourcen nicht mehr benötigt werden, löschen Sie die Ressourcengruppe. Sie können die Ressourcengruppe aus Cloud Shell oder dem Portal löschen.

az group delete --name troubleshootRG

Um die Ressourcengruppe aus dem Portal zu löschen, gehen Sie wie folgt vor:

  1. Geben Sie im Azure-Portal Ressourcengruppen in das Suchfeld ein.
  2. Geben Sie im Feld "Nach Namen filtern " den Namen der Ressourcengruppe ein.
  3. Klicken Sie auf den Namen der Ressourcengruppe.
  4. Wählen Sie " Ressourcengruppe löschen" aus.
  5. Um den Löschvorgang zu bestätigen, geben Sie den Namen der Ressourcengruppe ein, und wählen Sie "Löschen" aus.

Nächste Schritte

In dieser Schnellstartanleitung haben Sie erfahren, wie Sie Bicep-Dateibereitstellungsfehler beheben.

Fehlerbehebung bei allgemeinen Azure-Bereitstellungsfehlern