Verwenden des ARM-Vorlagentest-Toolkits

2025-05-01

Die Azure Resource Manager Template (ARM-Vorlage) Test-Toolkit überprüft, ob Ihre Vorlage empfohlene Praktiken verwendet. Wenn Ihre Vorlage nicht den empfohlenen Methoden entspricht, wird eine Liste mit Warnungen mit den vorgeschlagenen Änderungen zurückgegeben. Mithilfe des Test-Toolkits erfahren Sie, wie Sie häufige Probleme bei der Vorlagenentwicklung vermeiden. In diesem Artikel wird beschrieben, wie Sie das Test-Toolkit ausführen und wie Sie Tests hinzufügen oder entfernen. Weitere Informationen zum Ausführen von Tests oder zum Ausführen eines bestimmten Tests finden Sie unter "Testparameter".

Das Toolkit ist eine Reihe von PowerShell-Skripts, die über einen Befehl in PowerShell oder CLI ausgeführt werden können. Diese Tests sind Empfehlungen, aber keine Anforderungen. Sie können entscheiden, welche Tests für Ihre Ziele relevant sind, und anpassen, welche Tests ausgeführt werden.

Das Toolkit enthält vier Testgruppen:

Hinweis

Das Test-Toolkit ist nur für ARM-Vorlagen verfügbar. Verwenden Sie zum Überprüfen von Bicep-Dateien den Bicep-Linter.

Schulungsressourcen

Weitere Informationen zum ARM-Vorlagentest-Toolkit und praktische Anleitungen finden Sie unter Überprüfen von Azure-Ressourcen mithilfe des ARM-Vorlagentest-Toolkits.

Installieren unter Windows

Wenn Sie noch nicht über PowerShell verfügen, installieren Sie PowerShell unter Windows.
Laden Sie die neueste .zip Datei für das Test-Toolkit herunter, und extrahieren Sie sie.
Starten Sie PowerShell.
Navigieren Sie zu dem Ordner, in dem Sie das Test-Toolkit extrahiert haben. Navigieren Sie in diesem Ordner zum Ordner "arm-ttk ".
Wenn Ihre Ausführungsrichtlinie Skripts aus dem Internet blockiert, müssen Sie die Blockierung der Skriptdateien aufheben. Stellen Sie sicher, dass Sie sich im Ordner "arm-ttk " befinden.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importieren Sie das Modul.
```
Import-Module .\arm-ttk.psd1
```
Verwenden Sie den folgenden Befehl, um die Tests auszuführen:
```
Test-AzTemplate -TemplatePath \path\to\template
```

Installation unter Linux

Wenn Sie noch nicht über PowerShell verfügen, installieren Sie PowerShell unter Linux.
Laden Sie die neueste .zip Datei für das Test-Toolkit herunter, und extrahieren Sie sie.
Starten Sie PowerShell.
```
pwsh
```
Navigieren Sie zu dem Ordner, in dem Sie das Test-Toolkit extrahiert haben. Navigieren Sie in diesem Ordner zum Ordner "arm-ttk ".
Wenn Ihre Ausführungsrichtlinie Skripts aus dem Internet blockiert, müssen Sie die Blockierung der Skriptdateien aufheben. Stellen Sie sicher, dass Sie sich im Ordner "arm-ttk " befinden.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importieren Sie das Modul.
```
Import-Module ./arm-ttk.psd1
```
Verwenden Sie den folgenden Befehl, um die Tests auszuführen:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Installieren unter macOS

Wenn Sie noch nicht über PowerShell verfügen, installieren Sie PowerShell unter macOS.
Installieren coreutils:
```
brew install coreutils
```
Laden Sie die neueste .zip Datei für das Test-Toolkit herunter, und extrahieren Sie sie.
Starten Sie PowerShell.
```
pwsh
```
Navigieren Sie zu dem Ordner, in dem Sie das Test-Toolkit extrahiert haben. Navigieren Sie in diesem Ordner zum Ordner "arm-ttk ".
Wenn Ihre Ausführungsrichtlinie Skripts aus dem Internet blockiert, müssen Sie die Blockierung der Skriptdateien aufheben. Stellen Sie sicher, dass Sie sich im Ordner "arm-ttk " befinden.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importieren Sie das Modul.
```
Import-Module ./arm-ttk.psd1
```
Verwenden Sie den folgenden Befehl, um die Tests auszuführen:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Ergebnisformat

Tests, die bestanden wurden, werden in Grün angezeigt und mit [+] vorangestellt.

Tests, die fehlschlagen, werden rot angezeigt und mit einem [-] vorangestellt.

Tests mit einer Warnung werden in Gelb und mit vorangestelltem [?] angezeigt.

Screenshot: Testergebnisse in verschiedenen Farben für Erfolg, Fehler und Warnung

Die Textergebnisse sind:

deploymentTemplate
[+] adminUsername Should Not Be A Literal (6 ms)
[+] apiVersions Should Be Recent In Reference Functions (9 ms)
[-] apiVersions Should Be Recent (6 ms)
    Api versions must be the latest or under 2 years old (730 days) - API version 2019-06-01 of
    Microsoft.Storage/storageAccounts is 760 days old
    Valid Api Versions:
    2021-04-01
    2021-02-01
    2021-01-01
    2020-08-01-preview

[+] artifacts parameter (4 ms)
[+] CommandToExecute Must Use ProtectedSettings For Secrets (9 ms)
[+] DependsOn Best Practices (5 ms)
[+] Deployment Resources Must Not Be Debug (6 ms)
[+] DeploymentTemplate Must Not Contain Hardcoded Uri (4 ms)
[?] DeploymentTemplate Schema Is Correct (6 ms)
    Template is using schema version '2015-01-01' which has been deprecated and is no longer
    maintained.

Testparameter

Wenn Sie den -TemplatePath Parameter angeben, sucht das Toolkit in diesem Ordner nach einer Vorlage mit dem Namen azuredeploy.json oder maintemplate.json. Sie testet diese Vorlage zuerst und testet dann alle anderen Vorlagen im Ordner und seinen Unterordnern. Die anderen Vorlagen werden als verknüpfte Vorlagen getestet. Wenn Ihr Pfad eine Datei mit dem Namen createUiDefinition.jsonenthält, werden Tests ausgeführt, die für die UI-Definition relevant sind. Tests werden auch für Parameterdateien und alle JSON-Dateien im Ordner ausgeführt.

Test-AzTemplate -TemplatePath $TemplateFolder

Um eine Datei in diesem Ordner zu testen, fügen Sie den -File Parameter hinzu. Der Ordner muss jedoch weiterhin über eine Hauptvorlage mit dem Namen azuredeploy.json oder maintemplate.jsonverfügen.

Test-AzTemplate -TemplatePath $TemplateFolder -File cdn.json

Standardmäßig werden alle Tests ausgeführt. Um einzelne auszuführende Tests anzugeben, verwenden Sie den -Test Parameter, und geben Sie den Testnamen an. Die Testnamen finden Sie unter ARM-Vorlagen, Parameterdateien, createUiDefinition.jsonund alle Dateien.

Test-AzTemplate -TemplatePath $TemplateFolder -Test "Resources Should Have Location"

Anpassen von Tests

Sie können die Standardtests anpassen oder eigene Tests erstellen. Wenn Sie einen Test endgültig entfernen möchten, löschen Sie die .test.ps1 Datei aus dem Ordner.

Das Toolkit verfügt über vier Ordner, die die Standardtests enthalten, die für bestimmte Dateitypen ausgeführt werden:

ARM-Vorlagen: \arm-ttk\testcases\deploymentTemplate
Parameterdateien: \arm-ttk\testcases\deploymentParameters
createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
Alle Dateien: \arm-ttk\testcases\AllFiles

Hinzufügen eines benutzerdefinierten Tests

Um Ihren eigenen Test hinzuzufügen, erstellen Sie eine Datei mit der Benennungskonvention: Your-Custom-Test-Name.test.ps1.

Der Test kann die Vorlage als Objektparameter oder als Zeichenfolgenparameter abrufen. In der Regel verwenden Sie eine oder die andere, aber Sie können beides verwenden.

Verwenden Sie den Objektparameter, wenn Sie einen Abschnitt der Vorlage abrufen und dessen Eigenschaften durchlaufen müssen. Ein Test, der den Objektparameter verwendet, weist das folgende Format auf:

param(
  [Parameter(Mandatory=$true,Position=0)]
  [PSObject]
  $TemplateObject
)

# Implement test logic that evaluates parts of the template.
# Output error with: Write-Error -Message

Das Vorlagenobjekt verfügt über die folgenden Eigenschaften:

$schema
contentVersion
parameters
variables
resources
outputs

Sie können z. B. die Sammlung von Parametern mit $TemplateObject.parameters erhalten.

Verwenden Sie den Zeichenfolgenparameter, wenn Sie einen Zeichenfolgenvorgang für die gesamte Vorlage ausführen müssen. Ein Test, der den Zeichenfolgenparameter verwendet, weist das folgende Format auf:

param(
  [Parameter(Mandatory)]
  [string]
  $TemplateText
)

# Implement test logic that performs string operations.
# Output error with: Write-Error -Message

Sie können beispielsweise einen regulären Ausdruck des Zeichenfolgenparameters ausführen, um festzustellen, ob eine bestimmte Syntax verwendet wird.

Weitere Informationen zur Implementierung des Tests finden Sie in den anderen Tests in diesem Ordner.

Überprüfen von Vorlagen für Azure Marketplace

Um ein Angebot auf Azure Marketplace zu veröffentlichen, verwenden Sie das Test-Toolkit, um die Vorlagen zu überprüfen. Wenn Ihre Vorlagen die Validierungstests bestehen, genehmigt Azure Marketplace Ihr Angebot schneller. Wenn sie die Tests nicht bestehen, kann das Angebot nicht zertifiziert werden.

Von Bedeutung

Die Marketplace-Tests wurden im Juli 2022 hinzugefügt. Aktualisieren Sie Ihr Modul, wenn Sie über eine frühere Version verfügen.

Ausführen der Tests in Ihrer Umgebung

Führen Sie nach der Installation des Toolkits und dem Import des Moduls das folgende Cmdlet aus, um Ihr Paket zu testen:

Test-AzMarketplacePackage -TemplatePath "Path to the unzipped package folder"

Interpretieren der Ergebnisse

Die Tests geben Ergebnisse in zwei Abschnitten zurück. Der erste Abschnitt enthält die obligatorischen Tests. Die Ergebnisse dieser Tests werden im Zusammenfassungsabschnitt angezeigt.

Von Bedeutung

Sie müssen alle Ergebnisse rot korrigieren, bevor das Marketplace-Angebot angenommen wird. Es wird empfohlen, alle Ergebnisse zu korrigieren, die gelb zurückgegeben werden.

Die Textergebnisse sind:

Validating nestedtemplates\AzDashboard.json
    [+] adminUsername Should Not Be A Literal (210 ms)
    [+] artifacts parameter (3 ms)
    [+] CommandToExecute Must Use ProtectedSettings For Secrets (201 ms)
    [+] Deployment Resources Must Not Be Debug (160 ms)
    [+] DeploymentTemplate Must Not Contain Hardcoded Url (13 ms)
    [+] Location Should Not Be Hardcoded (31 ms)
    [+] Min and Max Value Are Numbers (4 ms)
    [+] Outputs Must Not Contain Secrets (9 ms)
    [+] Password params must be secure (3 ms)
    [+] Resources Should Have Location (2 ms)
    [+] Resources Should Not Be Ambiguous (2 ms)
    [+] Secure Params In Nested Deployments (205 ms)
    [+] Secure String Parameters Cannot Have Default (3 ms)
    [+] URIs Should Be Properly Constructed (190 ms)
    [+] Variables Must Be Referenced (9 ms)
    [+] Virtual Machines Should Not Be Preview (173 ms)
    [+] VM Size Should Be A Parameter (165 ms)
Pass : 99
Fail : 3
Total: 102
Validating StartStopV2mkpl_1.0.09302021\anothertemplate.json
    [?] Parameters Must Be Referenced (86 ms)
        Unreferenced parameter: resourceGroupName
        Unreferenced parameter: location
        Unreferenced parameter: azureFunctionAppName
        Unreferenced parameter: applicationInsightsName
        Unreferenced parameter: applicationInsightsRegion

Der Abschnitt unterhalb des Zusammenfassungsabschnitts enthält Testfehler, die als Warnungen interpretiert werden können. Das Beheben der Fehler ist optional, aber dringend empfohlen. Die Fehler zeigen häufig auf häufige Probleme, die zu Fehlern führen, wenn ein Kunde Ihr Angebot installiert.

Um Ihre Tests zu beheben, befolgen Sie den für Sie zutreffenden Testfall:

Übermitteln des Angebots

Nachdem Sie alle erforderlichen Korrekturen vorgenommen haben, führen Sie das Test-Toolkit erneut aus. Bevor Sie Ihr Angebot an Azure Marketplace übermitteln, stellen Sie sicher, dass keine Fehler auftreten.

Integrieren mit Azure Pipelines

Sie können das Test-Toolkit Zu Ihrer Azure-Pipeline hinzufügen. Mit einer Pipeline können Sie den Test jedes Mal ausführen, wenn die Vorlage aktualisiert wird, oder sie als Teil des Bereitstellungsprozesses ausführen.

Die einfachste Möglichkeit zum Hinzufügen des Test-Toolkits zu Ihrer Pipeline ist mit Erweiterungen von Drittanbietern. Die folgenden beiden Erweiterungen sind verfügbar:

Oder Sie können Ihre eigenen Aufgaben implementieren. Das folgende Beispiel zeigt, wie Sie das Test-Toolkit herunterladen.

Für eine Releasepipeline:

{
  "environment": {},
  "enabled": true,
  "continueOnError": false,
  "alwaysRun": false,
  "displayName": "Download TTK",
  "timeoutInMinutes": 0,
  "condition": "succeeded()",
  "task": {
    "id": "e213ff0f-5d5c-4791-802d-52ea3e7be1f1",
    "versionSpec": "2.*",
    "definitionType": "task"
  },
  "inputs": {
    "targetType": "inline",
    "filePath": "",
    "arguments": "",
    "script": "New-Item '$(ttk.folder)' -ItemType Directory\nInvoke-WebRequest -uri '$(ttk.uri)' -OutFile \"$(ttk.folder)/$(ttk.asset.filename)\" -Verbose\nGet-ChildItem '$(ttk.folder)' -Recurse\n\nWrite-Host \"Expanding files...\"\nExpand-Archive -Path '$(ttk.folder)/*.zip' -DestinationPath '$(ttk.folder)' -Verbose\n\nWrite-Host \"Expanded files found:\"\nGet-ChildItem '$(ttk.folder)' -Recurse",
    "errorActionPreference": "stop",
    "failOnStderr": "false",
    "ignoreLASTEXITCODE": "false",
    "pwsh": "true",
    "workingDirectory": ""
  }
}

Für die YAML-Definition einer Pipeline:

- pwsh: |
   New-Item '$(ttk.folder)' -ItemType Directory
   Invoke-WebRequest -uri '$(ttk.uri)' -OutFile "$(ttk.folder)/$(ttk.asset.filename)" -Verbose
   Get-ChildItem '$(ttk.folder)' -Recurse
   
   Write-Host "Expanding files..."
   Expand-Archive -Path '$(ttk.folder)/*.zip' -DestinationPath '$(ttk.folder)' -Verbose
   
   Write-Host "Expanded files found:"
   Get-ChildItem '$(ttk.folder)' -Recurse
  displayName: 'Download TTK'

Das nächste Beispiel zeigt, wie die Tests ausgeführt werden.