Notes
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Cet article fournit des conseils de style spécifiques au contenu PowerShell-Docs. Il s’appuie sur les informations décrites dans la Vue d’ensemble.
Mise en forme des éléments de syntaxe de commande
Utilisez les règles suivantes pour mettre en forme les éléments du langage PowerShell lorsque les éléments sont utilisés dans une phrase.
Utilisez toujours le nom complet pour les applets de commande et les paramètres dans le cas Pascal approprié
Utilisez uniquement un alias lorsque vous illustrez spécifiquement l’alias
Les mots clés et opérateurs PowerShell doivent être tous en minuscules
Les éléments suivants doivent être mis en forme à l’aide de texte en gras :
Noms de types
Noms de classes
Noms de propriété
Noms de paramètres
- Par défaut, utilisez le paramètre sans préfixe de trait d’union.
- Utilisez le nom du paramètre avec le trait d’union si vous illustrez la syntaxe. Encapsulez le paramètre dans les backticks.
Par exemple:
The parameter's name is **Name**, but it's typed as `-Name` when used on the command line as a parameter.
Les éléments suivants doivent être mis en forme à l’aide de backticks (
`) :Valeurs de propriété et de paramètre
Noms de types qui utilisent le style entre crochets : par exemple :
[System.Io.FileInfo]Faire référence aux personnages par leur nom. Par exemple : Utilisez le caractère astérisque (
*) comme caractère générique.Mots clés et opérateurs de langage
Noms de cmdlets, de fonctions et de scripts
Les alias de commande et de paramètre
Noms de méthode - Par exemple : la méthode
ToString()retourne une représentation sous forme de chaîne de l’objetVariables
Commandes natives
Chemins d’accès aux fichiers et aux répertoires
Exemples de syntaxe de commande inline - Consultez Markdown pour obtenir des exemples de code
Cet exemple montre quelques exemples de backticks :
The following code uses `Get-ChildItem` to list the contents of `C:\Windows` and assigns the output to the `$files` variable. ```powershell $files = Get-ChildItem C:\Windows ```Cet exemple montre la syntaxe de commande inline :
To start the spooler service on a remote computer named DC01, you type: `sc.exe \\DC01 start spooler`.L’inclusion de l’extension de fichier garantit que la commande correcte est exécutée en fonction de la priorité des commandes de PowerShell.
Markdown pour les exemples de code
Markdown prend en charge deux styles de code différents :
- Le code inline, marqué par un seul caractère accent grave (
`). Utilisé dans un paragraphe plutôt que comme bloc autonome. - Les blocs de code, blocs de plusieurs lignes délimités par des chaînes constituées de trois accents graves (
```). Les blocs de code peuvent avoir une étiquette de langage suivant les backticks. L’étiquette de langage active la mise en surbrillance de la syntaxe pour le contenu du bloc de code.
Tous les blocs de code doivent être contenus dans une clôture de code. N’utilisez jamais la mise en retrait pour les blocs de code. Markdown autorise ce modèle, mais il peut être problématique et doit être évité.
Un bloc de code est une ou plusieurs lignes de code entourées d’une limite de code de trois caractères accent grave (```).
Les délimiteurs de code doivent se trouver sur leur propre ligne avant et après l’exemple de code. Le marqueur ouvrant peut avoir une étiquette de langue facultative. L’étiquette de langue active la mise en surbrillance de la syntaxe sur la page web rendue.
Pour obtenir la liste complète des balises de langue prises en charge, consultez blocs de code encadrés dans le guide des contributeurs centralisé.
La publication ajoute également un bouton Copier qui permet de copier le contenu du bloc de code dans le Presse-papiers. Cela vous permet de coller le code dans un script pour tester l’exemple de code. Toutefois, tous les exemples ne sont pas destinés à être exécutés comme écrits. Certains blocs de code sont des illustrations de base des concepts PowerShell.
Il existe trois types de blocs de code utilisés dans notre documentation :
- Blocs de syntaxe
- Exemples illustrant
- Exemples exécutables
Blocs de code de syntaxe
Les blocs de code de syntaxe sont utilisés pour décrire la structure syntaxique d’une commande. N’utilisez pas de balise de langue sur la clôture de code. Cet exemple illustre tous les paramètres possibles de l’applet de commande Get-Command.
```
Get-Command [-Verb <String[]>] [-Noun <String[]>] [-Module <String[]>]
[-FullyQualifiedModule <ModuleSpecification[]>] [-TotalCount <Int32>] [-Syntax]
[-ShowCommandInfo] [[-ArgumentList] <Object[]>] [-All] [-ListImported]
[-ParameterName <String[]>] [-ParameterType <PSTypeName[]>] [<CommonParameters>]
```
Cet exemple décrit l’instruction for en termes généralisés :
```
for (<init>; <condition>; <repeat>)
{<statement list>}
```
Exemples illustrant
Des exemples illustrant sont utilisés pour expliquer un concept PowerShell. Vous devez éviter d’utiliser des invites PowerShell dans des exemples autant que possible. Toutefois, les exemples illustrant ne sont pas destinés à être copiés et collés pour l’exécution. Elles sont les plus couramment utilisées pour des exemples simples qui sont faciles à comprendre. Vous pouvez inclure l’invite PowerShell et l’exemple de sortie.
Voici un exemple simple illustrant les opérateurs de comparaison PowerShell. Dans ce cas, nous n'avons pas l'intention que le lecteur copie et exécute cet exemple. Notez que cet exemple utilise PS> comme chaîne d’invite simplifiée.
```powershell
PS> 2 -eq 2
True
PS> 2 -eq 3
False
PS> 1,2,3 -eq 2
2
PS> "abc" -eq "abc"
True
PS> "abc" -eq "abc", "def"
False
PS> "abc", "def" -eq "abc"
abc
```
Exemples exécutables
Les exemples complexes ou les exemples destinés à être copiés et exécutés doivent utiliser le balisage de style bloc suivant :
```powershell
<Your PowerShell code goes here>
```
La sortie affichée par les commandes PowerShell doit être placée dans un bloc de code Sortie pour empêcher la mise en surbrillance de la syntaxe. Par exemple:
```powershell
Get-Command -Module Microsoft.PowerShell.Security
```
```Output
CommandType Name Version Source
----------- ---- ------- ------
Cmdlet ConvertFrom-SecureString 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet ConvertTo-SecureString 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-Acl 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-Credential 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-PfxCertificate 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet New-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Protect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Set-Acl 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Set-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Set-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Test-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Unprotect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security
```
L’étiquette de code Output n’est pas une langue officielle prise en charge par le système de mise en surbrillance de la syntaxe.
Toutefois, ce label est utile, car notre système de publication ajoute le label Sortie au cadre de boîte de code sur la page web. La zone de code Output ne présente pas de coloration syntaxique.
Règles de style de codage
Éviter la continuation de ligne dans les exemples de code
Évitez d’utiliser des caractères de continuation de ligne (`) dans des exemples de code PowerShell. Les caractères de backtick sont difficiles à voir et peuvent poser problème en présence d’espaces supplémentaires à la fin de la ligne.
- Utilisez la projection PowerShell pour réduire la longueur de ligne des cmdlets comportant plusieurs paramètres.
- Tirez parti des possibilités naturelles de saut de ligne de PowerShell, comme après les caractères barre verticale (
|), les accolades ouvrantes ({), les parenthèses (() et les crochets ([).
Éviter d’utiliser des invites PowerShell dans des exemples
L’utilisation de la chaîne d’invite est déconseillée et doit être limitée aux scénarios destinés à illustrer l’utilisation de la ligne de commande. Pour la plupart de ces exemples, la chaîne d’invite doit être PS>. Cette invite est indépendante des indicateurs spécifiques au système d’exploitation.
Les invites sont requises dans les exemples illustrant des commandes qui modifient l’invite ou lorsque le chemin affiché est significatif pour le scénario. L’exemple suivant montre comment l’invite change lorsque le fournisseur de registre est utilisé.
PS C:\> cd HKCU:\System\
PS HKCU:\System\> dir
Hive: HKEY_CURRENT_USER\System
Name Property
---- --------
CurrentControlSet
GameConfigStore GameDVR_Enabled : 1
GameDVR_FSEBehaviorMode : 2
Win32_AutoGameModeDefaultProfile : {2, 0, 1, 0...}
Win32_GameModeRelatedProcesses : {1, 0, 1, 0...}
GameDVR_HonorUserFSEBehaviorMode : 0
GameDVR_DXGIHonorFSEWindowsCompatible : 0
N’utilisez pas d’alias dans des exemples
Utilisez le nom complet de toutes les applets de commande et paramètres, sauf si vous documentez spécifiquement l’alias. Les noms des cmdlets et des paramètres doivent être des noms utilisant la casse Pascal correcte.
Utilisation de paramètres dans des exemples
Évitez d’utiliser des paramètres positionnels. Pour réduire le risque de confusion, vous devez inclure le nom du paramètre dans un exemple, même si le paramètre est positionnel.
Mise en forme des articles de référence de cmdlet
Les articles de référence sur les cmdlets ont une structure spécifique.
platyPS définit cette structure. PlatyPS génère l’aide des cmdlets pour les modules PowerShell en Markdown. Après avoir modifié les fichiers Markdown, PlatyPS peut créer les fichiers d’aide MAML utilisés par l’applet de commande Get-Help.
PlatyPS a un schéma qui attend une structure spécifique pour la référence de cmdlet. Le document de schéma platyPS décrit cette structure. Les violations de schéma provoquent des erreurs de build qui doivent être corrigées avant de pouvoir accepter votre contribution.
- Ne supprimez aucune des structures d’en-tête ATX. PlatyPS attend un ensemble spécifique d’en-têtes dans un ordre spécifique.
- Les en-têtes H2 INPUTS et OUTPUTS doivent être de type H3. Si l’applet de commande ne prend pas d’entrée ou retourne une valeur, utilisez la valeur
Nonepour le H3. - Les étendues de code inline peuvent être utilisées dans n’importe quel paragraphe.
- Les blocs de code délimités ne sont autorisés que dans la section EXAMPLES.
Dans le schéma PlatyPS, EXAMPLES est un en-tête H2. Chaque exemple est un en-tête H3. Dans un exemple, le schéma ne permet pas aux blocs de code d'être séparés par des paragraphes. Le schéma autorise uniquement la structure suivante :
### Example X - Title sentence
0 or more paragraphs
1 or more code blocks
0 or more paragraphs.
Numérotez chaque exemple et ajoutez un titre court.
Par exemple:
### Example 1: Get cmdlets, functions, and aliases
This command gets the PowerShell cmdlets, functions, and aliases that are installed on the
computer.
```powershell
Get-Command
```
### Example 2: Get commands in the current session
```powershell
Get-Command -ListImported
```
Mise en forme des fichiers About_
About_* fichiers sont écrits dans Markdown, mais sont expédiés en tant que fichiers texte brut. Nous utilisons Pandoc pour convertir markdown en texte brut. Les fichiers About_* sont formatés pour la meilleure compatibilité avec toutes les versions de PowerShell et avec les outils de publication.
Instructions de mise en forme de base :
Limiter les lignes de paragraphe à 80 caractères
Limiter les blocs de code à 76 caractères
Limiter les guillemets de bloc et les alertes à 78 caractères
Lorsque vous utilisez ces méta-caractères spéciaux
\,$et<:Dans un en-tête, ils doivent être placés dans une séquence d’échappement précédée d’un caractère
\ou dans des morceaux de code entre accents graves (`)Dans un paragraphe, ces caractères doivent être placés dans des étendues de code. Par exemple:
### The purpose of the \$foo variable The `$foo` variable is used to store ...
Tableaux Markdown
- Pour les articles
About_*, les tableaux doivent tenir dans 76 caractères.- Si le contenu ne rentre pas dans une limite de 76 caractères, utilisez plutôt des listes à puces.
- Utiliser des caractères d’ouverture et de fermeture
|sur chaque ligne
- Pour les articles
Étapes suivantes
Collaborer avec nous sur GitHub
La source de ce contenu se trouve sur GitHub, où vous pouvez également créer et examiner les problèmes et les demandes de tirage. Pour plus d’informations, consultez notre guide du contributeur.
