Inclure du code dans la documentation

Il existe plusieurs façons autres que les captures d’écran d’inclure du code dans un article publié sur Microsoft Learn :

• Éléments individuels (mots) dans une ligne.

  Voici un exemple de style code.

  Utilisez le format de code quand vous faites référence à des variables et des paramètres nommés dans un bloc de code proche dans votre texte. Le format de code peut également être utilisé pour les propriétés, les méthodes, les classes et les mots clés de langage. Pour plus d’informations, consultez Éléments de code plus loin dans cet article.

• Blocs de code dans le fichier Markdown de l’article.

      ```csharp
      public static void Log(string message)
      {
          _logger.LogInformation(message);
      }
      ```
  

  Utilisez des blocs de code inline quand il est peu pratique d’afficher le code par référence à un fichier de code. Pour plus d’informations, consultez Blocs de code plus loin dans cet article.

• Blocs de code par référence à un fichier de code dans le dépôt local.

  :::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::
  

  Pour plus d’informations, consultez Références à des extraits de code au sein du référentiel plus loin dans cet article.

• Blocs de code par référence à un fichier de code dans un autre dépôt.

  :::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::
  

  Pour plus d’informations, consultez Références à des extraits de code en dehors du référentiel plus loin dans cet article.

• Blocs de code qui permettent à l’utilisateur d’exécuter du code dans le navigateur.

  :::code source="PowerShell.ps1" interactive="cloudshell-powershell":::
  

  Pour plus d’informations, consultez Extraits de code interactif plus loin dans cet article.

Non seulement l’article décrit le Markdown pour chacune de ces manières d’inclure du code, mais il offre également une aide générale pour tous les blocs de code.

Éléments de code

Un « élément de code » est un mot clé d’un langage de programmation, un nom de classe, un nom de propriété, etc. Il n’est pas toujours évident de savoir ce qui peut être considéré comme du code. Par exemple, les noms de package NuGet doivent être traités comme du code. En cas de doute, consultez la page Instructions de mise en forme du texte.

Style code inline

Pour inclure un élément de code dans le texte de l’article, encadrez-le avec des accents graves (`) pour indiquer le style de code. Le style code inline ne doit pas utiliser le format des trois accents graves.

Markdown	Rendu
Par défaut, Entity Framework interprète une propriété nommée Id ou ClassnameID comme étant la clé primaire.	Par défaut, Entity Framework interprète une propriété nommée Id ou ClassnameID comme étant la clé primaire.

Lorsqu’un article est localisé (traduit dans d’autres langues), le texte mis en forme comme du code reste inchangé. Si vous souhaitez empêcher la localisation sans utiliser le style code, consultez Chaînes non localisées.

Style gras

D’anciens guides de style permettent de spécifier du code inline en gras. Le style gras est possible lorsque le style code est si gênant qu’il ferait perdre en lisibilité. Par exemple, un tableau Markdown comportant principalement des éléments de code risque de paraître trop chargé avec du style code partout. Si vous choisissez d’utiliser le style gras, utilisez la syntaxe des chaînes non localisées pour que le code ne soit pas localisé.

Liens

Un lien vers la documentation de référence peut être plus utile que le format de code dans certains contextes. Si vous utilisez un lien, n’appliquez pas de format de code au texte du lien. Il risquerait masquer le fait que le texte est un lien.

Si vous utilisez un lien et que vous faites référence au même élément ultérieurement dans le même contexte, définissez les instances suivantes en tant que format de code plutôt que liens. Par exemple :

The first reference to <xref:System.CommandLine> in this text is a link.
Subsequent references to `System.CommandLine` can be in code style.

Rendu

La première référence à System.CommandLine dans ce texte est un lien. Les références suivantes à System.CommandLine peuvent être dans le style de code.

Espaces réservés

Si vous souhaitez que l’utilisateur remplace une section du code affiché par ses propres valeurs, utilisez un texte d’espace réservé délimité par des crochets pointus. Par exemple :

az group delete -n <ResourceGroupName>

Vous pouvez indiquer que les crochets doivent être supprimés lors du remplacement par des valeurs réelles. Le Guide de style d’écriture de Microsoft appelle l’italique, que vous pouvez mettre en forme dans le code inclus entre crochets pointus :

<ResourceGroupName> est le groupe de ressources où...

Les accolades {} sont déconseillées pour une utilisation en tant qu’espaces réservés syntaxiques. Elles peuvent être confondues avec la même notation que celle utilisée dans le texte remplaçable, les chaînes de format, l’interpolation de chaîne, les modèles de texte et les constructions de programmation similaires.

Les noms des espaces réservés peuvent être séparés par des traits d’union (« kebab case »), avec des traits de soulignement ou non séparés du tout (Pascal case). Le kebab case peut générer des erreurs de syntaxe et les traits de soulignement peuvent être en conflit avec le soulignement. Le tout en majuscules peut entrer en conflit avec des constantes nommées dans de nombreux langages, bien que cela puisse également attirer l’attention sur le nom de l’espace réservé.

<Resource-Group-Name> ou <ResourceGroupName>

Blocs de code

La syntaxe pour inclure du code dans un document dépend de l’endroit où se trouve le code :

• Dans le fichier Markdown de l’article
• Dans un fichier de code du même référentiel
• Dans un fichier de code d’un autre référentiel

Voici les instructions qui s’appliquent aux trois types de blocs de code :

• Captures d’écran
• Automatiser la validation du code
• Mettre en surbrillance les principales lignes de code
• Éviter les barres de défilement horizontales
• Identifier clairement le code incorrect

Captures d'écran

Toutes les méthodes listées dans la section précédente produisent des blocs de code utilisables :

• Vous pouvez effectuer des opérations de copier-coller à partir de ces derniers.
• Ils sont indexés par les moteurs de recherche.
• Ils sont accessibles aux lecteurs d’écran.

Ce ne sont là que quelques raisons pour lesquelles les captures d’écran IDE ne sont pas recommandées comme méthode d’inclusion de code dans un article. Utilisez des captures d’écran IDE pour le code uniquement si vous affichez des informations sur l’IDE lui-même, comme IntelliSense. N’utilisez pas de captures d’écran uniquement pour montrer la coloration et la mise en surbrillance.

Validation du code

Certains référentiels ont implémenté des processus qui compilent automatiquement tous les exemples de code pour rechercher les erreurs. C’est le cas du dépôt .NET. Pour plus d’informations, consultez Contribution dans le référentiel .NET.

Si vous incluez des blocs de code à partir d’un autre dépôt, collaborez avec les propriétaires sur une stratégie de maintenance du code afin que votre code inclus ne plante pas ou n’expire pas au fur et à mesure que sont fournies de nouvelles versions des bibliothèques utilisées par le code.

Mettre en surbrillance

Les extraits de code comportent généralement plus de code qu’il n’en faut, afin d’indiquer le contexte. La lisibilité s’en trouve améliorée si les lignes principales sur lesquelles porte l’extrait de code sont mises en surbrillance, comme dans cet exemple :

Vous ne pouvez pas mettre en surbrillance du code intégré au fichier Markdown de l’article. Cela ne fonctionne que pour les extraits de code fournis par référence à un fichier de code.

Barres de défilement horizontales

Scindez les longues lignes afin d’éviter d’avoir des barres de défilement horizontales. Les barres de défilement rendent les blocs de code difficiles à lire. Ils sont particulièrement problématiques sur les blocs de code très longs pour lesquels il serait impossible de voir en même temps la barre de défilement et la ligne que l’on souhaite lire.

Une bonne pratique pour minimiser les barres de défilement horizontales sur les blocs de code consiste à scinder les lignes de code de plus de 85 caractères. Toutefois, gardez à l’esprit que la présence ou l’absence d’une barre de défilement n’est pas le seul critère de lisibilité. Si la scission d’une ligne avant 85 caractères nuit à la lisibilité ou à la commodité du copier-coller, n’hésitez pas à aller au-delà des 85 caractères.

Identifier clairement le code incorrect

Dans certains scénarios, il est utile de souligner les modèles de codage qui doivent être évités, par exemple :

• Code qui provoque une erreur du compilateur s’il est utilisé.
• Code qui se compile correctement mais n’est pas recommandé.

Pour les scénarios suivants :

• Expliquez l’erreur à la fois dans les commentaires de code et dans le texte de l’article.

  Comme les lecteurs ignorent souvent le texte de l’article et n’examinent que le code, il n’est pas suffisant d’expliquer l’erreur uniquement dans le texte de l’article. Il n’est pas non plus suffisant d’expliquer l’erreur uniquement dans les commentaires de code, car ces derniers ne sont pas localisés.

• Pensez à commenter le code si cela provoque une erreur du compilateur.

  Le code commenté n’interrompt pas le système d’intégration continue si le référentiel de l’article en a un maintenant ou en implémentera un à l’avenir.

Pour obtenir un exemple illustrant comment présenter du code qui n’est pas recommandé, consultez Exemple d’utilisation de rune : modification de la casse des lettres. Dans cet exemple, le conseil d’éviter cela est même intégré au code lui-même, car le nom de la méthode C# est ConvertToUpperBadExample.

Blocs de code inline

Utilisez des blocs de code inline uniquement quand il est peu pratique d’afficher le code par référence à un fichier de code. Le code inline est généralement plus difficile à tester et à maintenir à jour qu’un fichier de code qui fait partie d’un projet complet. En outre, le code inline peut omettre le contexte qui pourrait aider le développeur à comprendre et à utiliser le code. Ces considérations s’appliquent principalement aux langages de programmation. Les blocs de code inline peuvent également être utilisés pour les sorties et les entrées (telles que JSON), les langages de requête (tels que SQL) et les langages de script (tels que PowerShell).

Il y a deux façons d’indiquer qu’une section de texte d’un fichier de l’article est un bloc de code : en la délimitant par trois accents graves (```) ou en la mettant en retrait. La délimitation est recommandée, car elle permet de spécifier le langage. Évitez d’utiliser la mise en retrait, car il est trop facile de se tromper et il peut être difficile pour un autre rédacteur de comprendre votre intention quand il doit modifier votre article.

Les indicateurs de langage sont placés immédiatement après les accents graves du début, comme dans l’exemple suivant :

Markdown

    ```json
    {
        "aggregator": {
            "batchSize": 1000,
            "flushTimeout": "00:00:30"
        }
    }
    ```

Rendu

{
    "aggregator": {
        "batchSize": 1000,
        "flushTimeout": "00:00:30"
    }
}

Conseil

GitHub Flavored Markdown prend en charge la délimitation de blocs de code avec des tildes (~) et des accents graves (`). Le symbole utilisé pour ouvrir et fermer le bloc de code doit être constant dans le même bloc de code.

Pour plus d’informations sur les valeurs possibles des indicateurs de langage, consultez la page Alias et noms de langage.

Si vous utilisez un mot de langage ou d’environnement après les trois accents graves (```) qui n’est pas pris en charge, ce mot apparaît dans la barre de titre de la section de code sur la page affichée. Dans la mesure du possible, utilisez un indicateur de langage ou d’environnement dans vos blocs de code inline.

Remarque

Si vous copiez et collez du code à partir d’un document Word, assurez-vous qu’il n’a pas de « guillemets courbes », qui ne sont pas valides dans le code. Si c’est le cas, remplacez-les par des guillemets normaux (' et "). Vous pouvez également utiliser la fonctionnalité de remplacement des guillemets anglais de Learn Authoring Pack.

Références à des extraits de code au sein du référentiel

La meilleure façon d’inclure des extraits de code pour les langages de programmation dans la documentation est de faire référence à un fichier de code. Cette méthode vous donne la possibilité de mettre en évidence des lignes de code et de rendre le contexte plus vaste de l’extrait de code disponible sur GitHub pour les développeurs. Vous pouvez inclure du code à l’aide du format triple deux-points (:::) manuellement ou dans Visual Studio Code à l’aide de Learn Authoring Pack.

1. Dans Visual Studio Code, cliquez sur Alt + M ou sur Option + M et sélectionnez Snippet (Extrait).
2. Une fois Snippet sélectionné, vous êtes invité à choisir entre Full Search (Recherche complète), Scoped Search (Recherche délimitée) et Cross-Repository Reference (Référence interdépôts). Pour effectuer une recherche locale, sélectionnez Full Search (Recherche complète).
3. Entrez un terme de recherche pour rechercher le fichier. Une fois le fichier trouvé, sélectionnez-le.
4. Ensuite, sélectionnez une option pour déterminer la ou les lignes de code à inclure dans l’extrait. Les options sont les suivantes : ID, Plage et Aucun.
5. En fonction de votre sélection à l’étape 4, indiquez une valeur si nécessaire.

Afficher la totalité du fichier de code :

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs":::

Afficher une partie du fichier de code en spécifiant les numéros de ligne :

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

Afficher une partie du fichier de code en spécifiant le nom de l’extrait :

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::

Les sections suivantes expliquent ces exemples :

• Utiliser un chemin d’accès relatif au fichier de code
• Inclure uniquement les numéros de ligne sélectionnés
• Faire référence à un extrait de code nommé
• Mettre en surbrillance les lignes sélectionnées

Pour plus d’informations, consultez Informations de référence sur la syntaxe des extraits plus loin dans cet article.

Chemin d’accès au fichier de code

Exemple :

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

L’exemple est issu du référentiel de documents ASP.NET, le fichier de l’article aspnetcore/data/ef-mvc/crud.md. La référence au fichier de code est un chemin d’accès relatif à aspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs dans le même référentiel.

Numéros de ligne sélectionnés

Exemple :

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

Cet exemple affiche uniquement les lignes 2-24 et 26 du fichier de code StudentController.cs.

Préférez les extraits de code nommés aux numéros de ligne codés en dur, comme l’explique la section suivante.

Extrait de code nommé

Exemple :

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::

Utilisez uniquement des lettres et des traits de soulignement dans le nom.

L’exemple affiche la section snippet_Create du fichier de code. Dans cet exemple, le code C# du fichier de code contient des balises d’extrait de code dans les commentaires :

// code excluded from the snippet
// <snippet_Create>
// code included in the snippet
// </snippet_Create>
// code excluded from the snippet

Les extraits de code nommés peuvent être imbriqués, comme illustré dans l’exemple suivant :

// <Method>
public static void SomeMethod()
{
    // <Line>
    // Single line of code.
    // </Line>
}
// </Method>

Lorsque l’extrait de code Method est rendu, les balises Line ne sont pas incluses dans la sortie restituée.

Dans la mesure du possible, faites référence à une section nommée au lieu de spécifier les numéros de ligne. Les références aux numéros de ligne sont fragiles, car les fichiers de code évoluent inévitablement, ce qui modifie les numéros de ligne. Ces modifications ne font pas forcément l’objet de notifications. Votre article finit par ne plus afficher les bonnes lignes, sans que vous en ayez connaissance.

Mise en surbrillance des lignes sélectionnées

Exemple :

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26" highlight="2,5":::

L’exemple met en surbrillance les lignes 2 et 5, à partir du début de l’extrait de code affiché. Les numéros de ligne à mettre en surbrillance ne sont pas comptés à partir du début du fichier de code. En d’autres termes, les lignes 3 et 6 du fichier de code sont mises en surbrillance.

Références à des extraits de code en dehors du référentiel

Si vous souhaitez faire référence à un fichier de code qui se trouve dans un autre dépôt, configurez le dépôt de code en tant que dépôt dépendant. Ce faisant, vous lui donnerez un nom. Ce nom fonctionnera alors comme un nom de dossier pour les références au code.

Supposons que le référentiel de documents soit Azure/azure-docs, et le référentiel de code Azure/azure-fonctions-durable-extension.

Dans le dossier racine de azure-docs, ajoutez la section suivante dans . openpublishing.publish.config.json :

    {
      "path_to_root": "samples-durable-functions",
      "url": "https://github.com/Azure/azure-functions-durable-extension",
      "branch": "main",
      "branch_mapping": {}
    },

Maintenant, quand vous faites référence à samples-durable-functions comme s’il s’agissait d’un dossier dans azure-docs, vous faites en réalité référence au dossier racine du dépôt azure-functions-durable-extension.

Vous pouvez inclure du code à l’aide du format triple deux-points (:::) manuellement ou dans Visual Studio Code à l’aide de Learn Authoring Pack.

1. Dans Visual Studio Code, cliquez sur Alt + M ou sur Option + M et sélectionnez Snippet (Extrait).
2. Une fois Snippet sélectionné, vous êtes invité à choisir entre Full Search (Recherche complète), Scoped Search (Recherche délimitée) et Cross-Repository Reference (Référence interdépôts). Pour effectuer une recherche dans plusieurs dépôts, sélectionnez Cross-Repository Reference.
3. Une sélection de dépôts figurant dans .openpublishing.publish.config.json s’affiche. Sélectionnez un dépôt.
4. Entrez un terme de recherche pour rechercher le fichier. Une fois le fichier trouvé, sélectionnez-le.
5. Ensuite, sélectionnez une option pour déterminer la ou les lignes de code à inclure dans l’extrait. Les options sont les suivantes : ID, Plage et Aucun.
6. En fonction de votre sélection à l’étape 5, indiquez une valeur.

Votre référence à l’extrait se présente ainsi :

:::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::

Dans le référentiel azure-functions-durable-extension, ce fichier de code se trouve dans le dossier samples/csx/shared. Comme indiqué précédemment, les numéros de ligne pour la mise en surbrillance sont relatifs au début de l’extrait de code et non au début du fichier.

Remarque

Le nom que vous attribuez au référentiel dépendant est relatif à la racine du référentiel principal, mais le tilde (~) fait référence à la racine du docset. La racine docset est déterminée par build_source_folder dans .openpublishing.publish.config.json. Le chemin de l’extrait de code dans l’exemple précédent fonctionne dans le dépôt azure-docs, car build_source_folder fait référence à la racine du dépôt (.). Si build_source_folder avait pour valeur articles, le chemin commencerait par ~/../samples-durable-functions au lieu de ~/samples-durable-functions.

Extraits de code dans un notebook Jupyter

Vous pouvez faire référence à une cellule d’un notebook Jupyter comme extrait de code. Pour faire référence à la cellule :

1. Ajoutez des métadonnées de cellule au notebook pour les cellules auxquelles vous souhaitez faire référence.
2. Configurez l’accès au dépôt.
3. Utilisez la syntaxe de l’extrait de code du notebook Jupyter dans votre fichier markdown.

Ajouter des métadonnées au notebook

1. Nommez la cellule en ajoutant des métadonnées de cellule dans le notebook Jupyter.

   • Dans Jupyter, vous pouvez modifier les métadonnées de cellule en activant d’abord la barre d’outils de cellule : Affichage > Barre d’outils de cellule > Modifier les métadonnées.
   • Une fois la barre d’outils de cellule activée, sélectionnez Edit Metadata dans la cellule que vous souhaitez nommer.
   • Ou vous pouvez modifier les métadonnées directement dans la structure JSON du notebook.

2. Dans les métadonnées de cellule, ajoutez un attribut « name » :

   "metadata": {"name": "<name>"},
   

   Par exemple :

   "metadata": {"name": "workspace"},
   

   Conseil

   Vous pouvez ajouter toutes les autres métadonnées que vous voulez pour vous permettre de suivre où la cellule est utilisée. Par exemple :

       "metadata": {
         "name": "workspace",
         "msdoc": "how-to-track-experiments.md"
       },
   

Configurer l’accès au dépôt

Si vous souhaitez faire référence à un fichier de notebook qui se trouve dans un autre dépôt, configurez le dépôt de code en tant que dépôt dépendant.

Référence de la syntaxe de l’extrait de code du notebook Jupyter

Une fois que votre notebook contient les métadonnées requises, référencez-le dans votre fichier markdown. Utilisez la <cell-name-value> que vous avez ajoutée au notebook et le <path> que vous avez défini comme dépôt dépendant.

[!notebook-<language>[] (<path>/<notebook-name.ipynb>?name=<cell-name-value>)]

Par exemple :

[!notebook-python[] (~/MachineLearningNotebooks/train-on-local.ipynb?name=workspace)]

Important

Cette syntaxe est une extension de bloc Markdown. Elle doit être utilisée seule, sur sa propre ligne.

Utilisez l’un des langages pris en charge pour l’identificateur <language>.

Extraits de code interactif

Blocs de code interactifs inline

Pour les langages suivants, les extraits de code peuvent être exécutables dans la fenêtre du navigateur :

• Azure Cloud Shell
• Azure PowerShell Cloud Shell
• C# REPL

Lorsque le mode interactif est activé, les zones de code qui s’affichent ont un bouton Essayer ou Exécuter. Par exemple :

    ```azurepowershell-interactive
    New-AzResourceGroup -Name myResourceGroup -Location westeurope
    ```

s’affiche ainsi :

New-AzResourceGroup -Name myResourceGroup -Location westeurope

And

    ```csharp-interactive
    var aFriend = "Maria";
    Console.WriteLine($"Hello {aFriend}");
    ```

devient :

    var aFriend = "Maria";
    Console.WriteLine($"Hello {aFriend}");

Si vous voulez activer cette fonctionnalité pour un bloc de code donné, utilisez un identificateur de langage spécial. Les options disponibles sont les suivantes :

• azurepowershell-interactive : active Azure PowerShell Cloud Shell, comme dans l’exemple précédent
• azurecli-interactive : active Azure Cloud Shell
• csharp-interactive :active C# REPL

Avec Azure Cloud Shell et PowerShell Cloud Shell, les utilisateurs ne peuvent exécuter des commandes que sur leur propre compte Azure.

Extraits de code inclus par référence

Il est possible d’activer le mode interactif pour les extraits de code inclus par référence. Pour activer cette fonctionnalité pour un bloc de code donné, utilisez l’attribut interactive. Les valeurs d’attribut disponibles sont les suivantes :

• cloudshell-powershell : active Azure PowerShell Cloud Shell, comme dans l’exemple précédent
• cloudshell-bash : active Azure Cloud Shell
• try-dotnet : active Try .NET
• try-dotnet-class : active Try .NET avec génération de modèles automatique de classe
• try-dotnet-method : active Try .NET avec génération de modèles automatique de méthode

Voici quelques exemples :

:::code source="PowerShell.ps1" interactive="cloudshell-powershell":::

:::code source="Bash.sh" interactive="cloudshell-bash":::

Avec Azure Cloud Shell et PowerShell Cloud Shell, les utilisateurs ne peuvent exécuter des commandes que sur leur propre compte Azure.

Pour l’expérience .NET Interactive, le contenu de votre bloc de code dépend de l’expérience de génération de modèles automatique choisie sur les trois :

• Aucune génération de modèles automatique (try-dotnet) : le bloc de code doit représenter un texte de programme complet. Par exemple, le fichier Program.cs généré par dotnet new console sera valide. Il est plus utile d’afficher un petit programme entier, comprenant les directives using nécessaires. Les instructions de niveau supérieur ne sont pas prises en charge pour le moment.
• Génération de modèles automatique de méthodes (try-dotnet-method) : le bloc de code doit représenter le contenu d’une méthode Main dans une application de console. Vous pouvez présumer des directives using ajoutées à partir du modèle dotnet new console. Ce paramètre est plus utile pour les courts extraits qui décrivent une fonctionnalité.
• Génération de modèles automatique de classes (try-dotnet-class) : le bloc de code doit représenter une classe avec une méthode Main comme point d'entrée du programme. Ils peuvent être utilisés pour déterminer le mode d’interaction des membres d’une classe entre eux.

Informations de référence sur la syntaxe des extraits

Syntaxe :

:::code language="<language>" source="<path>" <attribute>="<attribute-value>":::

Important

Cette syntaxe est une extension de bloc Markdown. Elle doit être utilisée seule, sur sa propre ligne.

• <language> (facultatif)

  • Langage de l’extrait de code. Pour plus d’informations, consultez la section Langages pris en charge plus loin dans cet article.

• <path> (obligatoire)

  • Chemin relatif dans le système de fichiers qui indique le fichier de l’extrait de code à référencer.

• <attribute> et <attribute-value> (facultatif)

  • Utilisés ensemble pour spécifier la manière dont le code doit être récupéré du fichier et dont il doit être affiché :
    • range : 1,3-5 plage de lignes. Cet exemple inclut les lignes 1, 3, 4 et 5.
    • id : Create l’ID de l’extrait à insérer à partir du fichier de code. Cette valeur ne peut pas coexister avec la plage.
    • highlight : 2-4,6 Plage et/ou nombres de lignes à mettre en surbrillance dans l’extrait de code généré. La numérotation est relative aux lignes affichées (comme spécifié par la plage ou l’ID), pas au fichier.
    • interactive: cloudshell-powershell, cloudshell-bash, try-dotnet, try-dotnet-class, try-dotnet-method Valeur de chaîne qui détermine les types d’interactivité activés.
    • Pour plus d’informations sur la représentation des noms d’étiquette dans les fichiers sources d’extraits de code par langage, consultez les Instructions pour DocFX.

Langues prises en charge

L’extension Learn Authoring Pack comprend une fonctionnalité qui permet d’effectuer la saisie semi-automatique des instructions et de valider les identificateurs de langue disponibles pour les blocs de limites de code.

Blocs de code délimités

Nom	Alias valides
CLI .NET Core	dotnetcli
1C	1c
ABNF	abnf
Accéder aux journaux	accesslog
Ada	ada
Assembleur ARM	armasm, arm
Assembleur AVR	avrasm
ActionScript	actionscript, as
Alan	alan, i
AngelScript	angelscript, asc
ANTLR	antlr
Apache	apache, apacheconf
AppleScript	applescript, osascript
Arcade	arcade
AsciiDoc	asciidoc, adoc
AspectJ	aspectj
ASPX	aspx
ASP.NET (C#)	aspx-csharp
ASP.NET (VB)	aspx-vb
AutoHotkey	autohotkey
AutoIt	autoit
Awk	awk, mawk, nawk, gawk
Axapta	axapta
AzCopy	azcopy
Azure CLI	azurecli
Azure CLI (Interactive)	azurecli-interactive
Azure PowerShell	azurepowershell
Azure Powershell (Interactive)	azurepowershell-interactive
Bash	bash, sh, zsh
De base	basic
BNF	bnf
C	c
C#	csharp, cs
C# (Interactive)	csharp-interactive
C++	cpp, c, cc, h, c++, h++, hpp
C++/CX	cppcx
C++/WinRT	cppwinrt
C/AL	cal
Script d’objet cache	cos, cls
CMake	cmake, cmake.in
Coq	coq
CSP	csp
CSS	css
Cap'n Proto	capnproto, capnp
Clojure	clojure, clj
CoffeeScript	coffeescript, coffee, cson, iced
Crmsh	crmsh, crm, pcmk
Crystal	crystal, cr
Cypher (Neo4j)	cypher
D	d
DAX Power BI	dax
Fichier de zone DNS	dns, zone, bind
DOS	dos, bat, cmd
Dart	dart
Delphi	delphi, dpr, dfm, pas, pascal, freepascal, lazarus, lpr, lfm
Diff	diff, patch
Django	django, jinja
Dockerfile	dockerfile, docker
dsconfig	dsconfig
DTS (arborescence des appareils)	dts
Dust	dust, dst
Dylan	dylan
EBNF	ebnf
Elixir	elixir
Elm	elm
Erlang	erlang, erl
Excel	excel, xls, xlsx
Extempore	extempore, xtlang, xtm
F#	fsharp, fs
FIX	fix
Fortran	fortran, f90, f95
G-Code	gcode, nc
Gams	gams, gms
GAUSS	gauss, gss
GDScript	godot, gdscript
Gherkin	gherkin
GN for Ninja	gn, gni
Go	go, golang
Golo	golo, gololang
Gradle	gradle
GraphQL	graphql
Groovy	groovy
HTML	html, xhtml
HTTP	http, https
Haml	haml
Guidon	handlebars, hbs, html.hbs, html.handlebars
Haskell	haskell, hs
Haxe	haxe, hx
Hy	hy, hylang
Ini	ini
Inform7	inform7, i7
IRPF90	irpf90
JSON	json
Java	java, jsp
JavaScript	javascript, js, jsx
Kotlin	kotlin, kt
Kusto	kusto
Feuille	leaf
Lasso	lasso, ls, lassoscript
Inférieur	less
LDIF	ldif
Lisp	lisp
LiveCode Server	livecodeserver
LiveScript	livescript, ls
Lua	lua
Makefile	makefile, mk, mak
Markdown	markdown, md, mkdown, mkd
Mathematica	mathematica, mma, wl
Matlab	matlab
Maxima	maxima
Maya Embedded Language	mel
Mercury	mercury
mIRC Scripting Language	mirc, mrc
Mizar	mizar
Format MOF (Managed Object Format)	mof
Mojolicious	mojolicious
Monkey	monkey
Moonscript	moonscript, moon
MS Graph (Interactive)	msgraph-interactive
N1QL	n1ql
NSIS	nsis
Nginx	nginx, nginxconf
Nimrod	nimrod, nim
Nix	nix
OCaml	ocaml, ml
Objective C	objectivec, mm, objc, obj-c
OpenGL Shading Language	glsl
OpenSCAD	openscad, scad
Oracle Rules Language	ruleslanguage
Oxygene	oxygene
PF	pf, pf.conf
PHP	php, php3, php4, php5, php6
Parser3	parser3
Perl	perl, pl, pm
Plaintext no highlight	plaintext
Pony	pony
PostgreSQL & PL/pgSQL	pgsql, postgres, postgresql
PowerShell	powershell, ps
PowerShell (Interactive)	powershell-interactive
Traitement	processing
Prolog	prolog
Propriétés	properties
Mémoires tampon de protocole	protobuf
Puppet	puppet, pp
Python	python, py, gyp
Résultats de profileur Python	profile
Q#	qsharp
Q	k, kdb
QML	qml
R	r
Razor CSHTML	cshtml, razor, razor-cshtml
ReasonML	reasonml, re
RenderMan RIB	rib
RenderMan RSL	rsl
Roboconf	graph, instances
Robot Framework	robot, rf
Fichiers de spécifications RPM	rpm-specfile, rpm, spec, rpm-spec, specfile
Ruby	ruby, rb, gemspec, podspec, thor, irb
Rust	rust, rs
SAS	SAS, sas
SCSS	scss
SQL	sql
STEP Part 21	p21, step, stp
Scala	scala
Schéma	scheme
Scilab	scilab, sci
Shape Expressions	shexc
Shell	shell, console
Smali	smali
Smalltalk	smalltalk, st
Solidity	solidity, sol
Stan	stan
Stata	stata
Texte structuré	iecst, scl, stl, structured-text
Stylus	stylus, styl
SubUnit	subunit
Supercollider	supercollider, sc
Swift	swift
Tcl	tcl, tk
Terraform (HCL)	terraform, tf, hcl
Test Anything Protocol	tap
TeX	tex
Thrift	thrift
TOML	toml
TP	tp
Twig	twig, craftcms
TypeScript	typescript, ts
VB.NET	vbnet, vb
VBScript	vbscript, vbs
VHDL	vhdl
Vala	vala
Verilog	verilog, v
Vim Script	vim
Visual Basic	vb
Visual Basic pour Applications	vba
X++	xpp
Langage assembleur x86	x86asm
XL	xl, tao
XQuery	xquery, xpath, xq
XAML	xaml
XML	xml, xhtml, rss, atom, xjb, xsd, xsl, plist
YAML	yml, yaml
Zephir	zephir, zep

Conseil

La fonctionnalité de complétion des langages de développement de Learn Authoring Pack utilise le premier alias valide quand plusieurs en sont disponibles.

Étapes suivantes

Pour plus d’informations sur la mise en forme du texte pour les types de contenu autres que le code, consultez instructions de mise en forme du texte.