Freigeben über


Styleguide für Azure PowerShell-Dokumente

Dieser Artikel konzentriert sich auf konzeptionelle und referenzielle Azure PowerShell-Inhalte, die in den folgenden GitHub-Repositories verfügbar sind:

Version

Im Gegensatz zu den meisten Microsoft Learn Dokumentationen werden die Azure PowerShell Inhalte im azure-docs-powershell Repository für mehrere unterstützte Versionen gepflegt. Einzelheiten zu den unterstützten Versionen finden Sie unter Lebenszyklus der Unterstützung für Azure PowerShell.

Wenn ein Artikel auf Cmdlets aus einem Vorschau-Modul verweist, muss dieses Modul explizit installiert werden, es sei denn, das AzPreview-Modul ist bereits installiert. Dies liegt daran, dass nur allgemein verfügbare (AV) Module im Az PowerShell Modul enthalten sind.

Von Bedeutung

Verwenden Sie keine Befehle aus dem AzureRM PowerShell-Modul in Artikeln. AzureRM ist veraltet.

Voraussetzungen

Führen Sie die Voraussetzungen für den Azure-Dienst immer an vorderster Stelle auf, gefolgt von Azure PowerShell- und Azure Cloud Shell-Anweisungen. Zum Beispiel sollte "Sie müssen Microsoft.Authorization/roleAssignments/write-Berechtigungen haben, um die Anweisungen in diesem Tutorial auszuführen" an erster Stelle stehen.

Wenn alle Befehle nicht mit Cloud Shell kompatibel sind, weisen Sie den Benutzenden an, das Az PowerShell Modul lokal zu installieren. Fügen Sie den folgenden Text in einen Abschnitt "H2 Prerequisites" ein.

- This tutorial requires that you run Azure PowerShell locally:
  - [Install the latest version of the Az PowerShell module](/powershell/azure/install-azure-powershell).
  - Connect to your Azure account using the
    [Connect-AzAccount](/powershell/module/az.accounts/connect-azaccount) cmdlet.

Formatieren von Syntaxelementen in einem Absatz

Folgen Sie dem PowerShell-Styleguide für Dokumentationen und der Checkliste des Editors zum Formatieren von Befehlssyntaxelementen in der Azure PowerShell-Dokumentation.

Verweisen Sie nicht auf die Cmdlet-Dokumentation, wenn Sie Cmdlet-Namen in einem Absatz erwähnen. Umgeben Sie stattdessen den Cmdlet-Namen mit Backticks, was für Inline-Code (``) steht. Fügen Sie am Ende der Seite einen Abschnitt mit Referenzen hinzu. Listen Sie die Cmdlet-Namen im Abschnitt "Verweise" auf, und verknüpfen Sie sie mit ihrem zugehörigen Referenzartikel. Beispiel:

This is an example of using the `Connect-AzAccount` and `Get-AzVM` cmdlets within a
paragraph.

## References

- [Connect-AzAccount](/powershell/module/az.accounts/connect-azaccount)
- [Get-AzVM](/powershell/module/az.compute/get-azvm)

Hinweis

Formatieren Sie Text nicht innerhalb der eckigen Klammern eines Links. Weitere Informationen zum Verknüpfen mit Azure PowerShell-Inhalten finden Sie unter Verknüpfen mit anderen Dokumenten.

Parameterreihenfolge

Parameter für ein Azure PowerShell-Cmdlet sollten in der durch die Cmdlet-Hilfe definierten Reihenfolge erscheinen. Ein Cmdlet kann die erforderlichen Parameter auf mehrere Arten bereitstellen. Wenn dies der Fall ist, folgen Sie dem Parameter, der für die Verwendung festgelegt ist, die Sie demonstrieren. Connect-AzAccount ist ein Beispiel für ein Cmdlet mit mehreren Möglichkeiten, es aufzurufen.

Variablen

Verwenden Sie Variablen nicht über mehrere Codeblöcke hinweg.

Der Leser kann die Schritte des Artikels in verschiedenen Abschnitten ausführen. Die Verwendung von Variablen über Code-Blöcke hinweg kann zu Fehlern führen, wenn sie nicht korrekt festgelegt sind. Wenn Sie die Variablen über mehrere Schritten hinweg verwenden müssen, sollten Sie deutlich machen, dass sie in späteren Schritten wiederverwendet werden.

Kennwörter für neue Ressourcen zufällig festlegen

Wenn Sie eine Ressource erstellen, der ein Kennwort zugeordnet ist, verwenden Sie kein hartcodiertes Kennwort. Das Einchecken von Kennwörtern in die Quellcodeverwaltung ist ein Sicherheitsrisiko. Dies gilt auch für Beispiele.

Wenn die Azure-Ressourcen in Ihrem Artikel ein Nur-Text-Kennwort erfordern, verwenden Sie Read-Host, damit Benutzer ein eigenes Kennwort definieren können. Der Parameter MaskInput verhindert, dass das Kennwort im PowerShell-Verlauf aufgezeichnet wird.

$password = Read-Host 'Enter a Password' -MaskInput

Namenskonflikte vermeiden

Einige Azure-Ressourcen, z. B. Azure Container Registry und Key Vault, verfügen über Ressourcen, die an Domänennamen gebunden sind. Diese Ressourcen müssen einen global eindeutigen Namen haben. Verwenden Sie daher einen Zufallswert als Teil von Namen, wenn Eindeutigkeit erforderlich ist. Falls du es nicht tust, können Skripte erforderliche Ressourcen nicht erstellen, wenn mehrere Personen sie gleichzeitig ausführen. Zufälligkeit verhindert keinen Konflikt, kann ihn jedoch mindern.

Verwenden Sie Get-Random, um einem Namen eine Zufallszahl hinzuzufügen, z. B.:

$newAcrName = "myacr-$(Get-Random)"

Interaktive Codeausschnitte

Wann sollte man interaktive Codeausschnitte verwenden?

Wenn Cloud Shell jeden Azure PowerShell-Befehl in Ihrem Artikel unterstützt, markieren Sie Ihre Codeblöcke mit azurepowershell-interactive, um die Schaltfläche Open Cloud Shell den Codeausschnitten hinzuzufügen:

```azurepowershell-interactive
Get-AzResourceGroup | Select-Object -Property ResourceGroupName, Location
```

Wann NICHT interaktive Codeausschnitte verwendet werden sollen

Verwenden Sie azurepowershell-interactive nicht, wenn Ihr Artikel irgendwelche Azure PowerShell-Befehle enthält, die in Cloud Shell nicht funktionieren. Verwenden Sie nur azurepowershell. Beispielsweise wird das Cmdlet Install-AzAksCliTool in Cloud Shell nicht unterstützt:

Install-AzAksCliTool

Wenn Sie funktionierende Cloud Shell-Befehle mit Befehlen kombinieren, die in Cloud Shell nicht funktionieren, riskieren Sie, dass Kunden frustriert sind, wenn nur manche Befehle funktionieren. Verwenden Sie stattdessen das azurepowershell-Sprachtag für alle Codeblöcke, um Verwirrung zu vermeiden.

Da Benutzer bei der Anmeldung bei Cloud Shell bereits authentifiziert sind, sollten Sie das azurepowershell-interactive-Tag nicht für Codeblöcke verwenden, die nur Connect-AzAccount enthalten. Verwenden Sie stattdessen das azurepowershell Sprachtag.

Aktualisierung von AzureRM auf das Az PowerShell-Modul

Unter Migrieren von Azure PowerShell von AzureRM zu Az finden Sie Informationen zum Aktualisieren von Befehlen, die das AzureRM-PowerShell-Modul verwenden, auf das Az PowerShell-Modul.