Guide de style de la documentation Azure PowerShell

2025-07-01

Cet article se concentre sur le contenu conceptuel et référentiel d'Azure PowerShell disponible dans les référentiels GitHub suivants :

Version

Contrairement à la plupart des documentations Microsoft Learn, le contenu Azure PowerShell du référentiel azure-docs-powershell est maintenu pour plusieurs versions prises en charge. Pour plus d’informations sur les versions prises en charge, consultez cycle de vie du support d’Azure PowerShell.

Si un article fait référence à des cmdlets d'un module de prévisualisation, ce module doit être explicitement installé, sauf si le module AzPreview est déjà installé. En effet, seuls les modules généralement disponibles (GA) sont inclus dans le module Az PowerShell.

Important

N'utilisez pas de commandes du module AzureRM PowerShell dans les articles. AzureRM est déconseillé.

Conditions préalables

Placez toujours les prérequis des services Azure en premier, suivis des instructions relatives à Azure PowerShell et Azure Cloud Shell. Par exemple, « Vous devez disposer des autorisations Microsoft.Authorization/roleAssignments/write pour accomplir les instructions de ce tutoriel » doit venir en premier.

Si toutes les commandes ne sont pas compatibles avec Cloud Shell, demandez à l'utilisateur d'installer le module Az PowerShell localement. Incluez le texte suivant dans une section Prérequis H2.

- 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.

Formatage des éléments de syntaxe dans un paragraphe

Suivez le guide de style PowerShell-Docs et la liste de contrôle de l’éditeur pour mettre en forme les éléments de syntaxe de commande dans la documentation Azure PowerShell.

Ne faites pas de lien vers la documentation des cmdlets lorsque vous mentionnez des noms de cmdlets dans un paragraphe. Au lieu de cela, entourez le nom du cmdlet avec des backticks, qui est un style pour le code inline (``). Ajoutez une section de références vers le bas de la page. Listez les noms des cmdlets dans la section des références et créez un lien vers l'article de référence qui leur est associé. Par exemple:

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)

Remarque

Ne mettez pas en forme le texte à l'intérieur des crochets d'un lien hypertexte. Pour plus d’informations sur la création de liens vers du contenu Azure PowerShell, consultez Création de liens vers d’autres documents.

Ordre des paramètres

Les paramètres d'une cmdlet de PowerShell Azure doivent être présentés selon l'ordre spécifié dans l'aide de la cmdlet. Une cmdlet peut fournir les paramètres requis de plusieurs façons. Lorsque c'est le cas, suivez les paramètres définis pour l'utilisation que vous démontrez. Connect-AzAccount est un exemple de cmdlet avec plusieurs façons de l'invoquer.

Variables

Évitez de réutiliser des variables dans plusieurs blocs de code.

Le lecteur peut effectuer les étapes de l'article dans différentes sessions. L'utilisation de variables dans plusieurs blocs de code peut entraîner des erreurs si elles ne sont pas définies correctement. Si vous devez utiliser des variables dans plusieurs étapes, indiquez clairement que les variables sont réutilisées dans les étapes suivantes.

Utiliser des mots de passe aléatoires pour les nouvelles ressources

Si vous créez une ressource associée à un mot de passe, n’utilisez pas un mot de passe codé en dur. L'intégration des mots de passe dans le contrôle de code source, même à titre d'exemple, est un risque de sécurité.

Si les ressources Azure de votre article nécessitent un mot de passe en texte brut, utilisez Read-Host pour permettre aux utilisateurs de définir leur mot de passe. Le paramètre MaskInput empêche l’enregistrement du mot de passe dans l’historique de PowerShell.

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

Éviter les conflits d’attribution de noms

Certaines ressources Azure, comme Azure Container Registry et Key Vault, ont des ressources liées à des noms de domaine. Ces ressources doivent avoir un nom unique à l'échelle mondiale. Pour cette raison, vous devez utiliser une valeur aléatoire comme partie du nom si l’unicité est requise. Si vous ne le faites pas, les scripts ne parviennent pas à créer les ressources requises lorsque plusieurs personnes les exécutent. Le caractère aléatoire n’empêche pas les conflits, mais peut les atténuer.

Utilisez Get-Random pour ajouter un nombre aléatoire à un nom, par exemple :

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

Extraits de code interactifs

Quand utiliser des extraits de code interactifs

Si Cloud Shell prend en charge chaque commande Azure PowerShell dans votre article, étiquetez vos blocs de code avec azurepowershell-interactive pour ajouter le bouton Open Cloud Shell aux extraits de code :

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

Quand ne pas utiliser d’extraits de code interactifs

N’utilisez pas azurepowershell-interactive si votre article inclut n’importe quelle commande Azure PowerShell qui ne fonctionne pas dans Cloud Shell. Utilisez uniquement azurepowershell. Par exemple, la cmdlet Install-AzAksCliTool n’est pas prise en charge dans Cloud Shell :

Install-AzAksCliTool

Si vous combinez des commandes fonctionnelles Cloud Shell avec des commandes qui ne fonctionnent pas dans Cloud Shell, vous risquez de frustrer les clients quand seules certaines commandes fonctionnent. Au lieu de cela, gardez la balise de langage azurepowershell pour tous les blocs de code afin d’éviter toute confusion.

Étant donné que les utilisateurs sont déjà authentifiés lors de la connexion à Cloud Shell, n’utilisez pas la balise azurepowershell-interactive pour les blocs de code contenant uniquement Connect-AzAccount. Utilisez plutôt la balise de langage azurepowershell.

Mettez à jour AzureRM avec le module Az PowerShell.

Consultez la section Migrer Azure PowerShell d'AzureRM vers Az pour savoir comment mettre à jour les commandes qui utilisent le module AzureRM PowerShell vers le module Az PowerShell.

Partager via