Aktualisierung der PowerShell-Dokumentation

Dieser Beitrag wurde vom Geschäftsführer des Teams „Azure Growth and Ecosystem“, Jeff Sandquist, verfasst.

Ab heute steht die überarbeitete Azure PowerShell-Umgebung für docs.microsoft.com zur Verfügung. Zu Optimierungen zählen z.B. die Modulversionierung, Codesyntaxhervorhebungen, ein leichter zu navigierendes Inhaltsverzeichnis, die Möglichkeit Dokumentationen zu bearbeiten und zu verbessern und mehr. Aufgrund von Kundenfeedback wissen wir, dass bei PowerShell-Inhalten Verbesserungsbedarf bestand, und diese Verbesserung ist der nächste Schritt auf dem Weg zur Verbesserung der Inhaltsqualität. Wir haben mit Azure begonnen, werden aber alle PowerShell-Inhalte in den nächsten Monaten in diese Umgebung verschieben.

Einheitliche PowerShell-Modulreferenz

Unsere PowerShell-Modulreferenzdokumentation soll für alle von Microsoft ausgelieferten PowerShell-Module eine einheitliche Umgebung bereitstellen. Dies umfasst u. a.:

  • Konsistente URL-Muster: Wenn Sie den Namen des Moduls oder eines Cmdlets kennen, kennen Sie auch die URL. Das in der Dokumentation verwendete URL-Muster lautet wie folgt: docs.microsoft.com/powershell/module/{Modulname}/{Cmdlet-Name}/. Für das Cmdlet Get-AzureRMStorageAccount im Modul AzureRM.Storage lautet die URL beispielsweise folgendermaßen: https://docs.microsoft.com/powershell/module/azurerm.storage/get-azurermstorageaccount.
  • Konsistente Benutzerumgebung: Die Formatierung für Module, Cmdlets und Beispiele ist nun in der gesamten PowerShell-Dokumentation gleich.
  • Einfache Beiträge: PowerShell-Benutzer können Codebeispiele hinzufügen oder unsere Referenzdokumentation bearbeiten, indem sie direkt auf der Dokumentationsseite auf die Schaltfläche „Bearbeiten“ klicken.
  • Unterstützung für Versionsverwaltung für frühere Versionen von PowerShell: Verwenden Sie zum Filtern nach einer bestimmten Azure PowerShell-Version die Versionsauswahl auf der Seite.

PowerShell-Versionsverwaltung

Wir haben zwar die Versionsverwaltung für ein bestimmtes Modul erwähnt, einige Module werden jedoch als eine Gruppe anderer Module ausgeliefert, bei der jedes Modul ein eigenes separates Schema für die Versionsverwaltung besitzt. Kunden laden Azure PowerShell beispielsweise über PowerShellGet herunter. In der Vergangenheit mussten Kunden manuell ermitteln, welche Versionen der Dokumentation für ihre Installation gilt. Beispiel: Wenn Sie Azure PowerShell 3.7 installiert haben, mussten Sie jedes einzelne Modul kennen, das von AzureRM 3.7 mit AzureRM.Automation 2.7 und AzureRM.CognitiveServices v0.5.0 ausgeliefert wird, und nach der entsprechenden Dokumentation suchen.

In unserer neuen Umgebung müssen Sie nur eine Version auswählen, und die richtigen Module werden basierend auf Ihrer Installation gefiltert.

PowerShell version selection

Verbessertes Inhaltsverzeichnis

Zusätzlich zur Cmdlet-Referenz haben wir eine Inhaltsübersicht, Installationsschritte, erste Schritte und Beispiele hinzugefügt. In der Azure-Referenz wurden Cmdlets ebenfalls nach Azure-Dienst zusammengefasst.

Table of contents showing overview, samples, reference

Einfaches Filtern bei der Eingabe über das Inhaltsverzeichnis

Sie können das linke Inhaltsverzeichnis bei der Eingabe einfach nach übereinstimmenden Cmdlets oder Diensten mit diesem Namen filtern.

Results filter as you type

Verbesserungen an der Cmdlet-Seite

Optimierte Farbgebung und Formatierung

PowerShell-Cmdlets sind jetzt zur besseren Lesbarkeit farbig dargestellt und übersichtlich formatiert.

Colorized PowerShell syntax

Verbesserungen der Parameter

Da Parameter zuvor basierend darauf gruppiert wurden, ob sie erforderlich oder optional sind, erschien die Parameterliste unsortiert. Stattdessen wurden Abschnittsüberschriften hinzugefügt, um erforderliche und optionale Parameter zu gruppieren, und die Farbgebung und der Stil für Parameternamen wurden verbessert.

Grouping required and optional parameters

Intelligenteres Verhalten beim Kopieren und Einfügen

Einige Codebeispiele für PowerShell-Cmdlets besitzen das Präfix PS C:\>. Wenn Sie im Codebeispiel auf die Schaltfläche „Kopieren“ klicken, wird nun das Präfix PS C:\> entfernt wie im Editor-Screenshot unten gezeigt.

Copy button removing text

Senden Sie Feedback

Wir hoffen, dass Sie eine wesentliche Verbesserung in diesem Release feststellen. Die Version ist noch nicht fertig. Sie können uns also weiterhin Feedback über UserVoice für die Dokumentation senden.