Code opnemen in documentatie

Er zijn verschillende manieren om code op te nemen in een artikel dat is gepubliceerd op Microsoft Learn:

• Afzonderlijke elementen (woorden) binnen een regel.

  Hier volgt een voorbeeld van code-stijl.

  Gebruik code-indeling als u verwijst naar benoemde parameters en variabelen in een nabijgelegen codeblok in uw tekst. Code-indeling kan ook worden gebruikt voor eigenschappen, methoden, klassen en taaltrefwoorden. Zie Code-elementen verderop in dit artikel voor meer informatie.

• Codeblokken in het Markdown-bestand van het artikel.

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

  Gebruik codeblokken in regels wanneer het niet praktisch is om code weer te geven door verwijzing naar een codebestand. Zie Codeblokken verderop in dit artikel voor meer informatie.

• Codeblokken met verwijzing naar een codebestand in de lokale opslagplaats.

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

  Zie Verwijzingen naar codefragmenten in de opslagplaats verderop in dit artikel voor meer informatie.

• Codeblokken met verwijzing naar een codebestand in een andere opslagplaats.

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

  Zie Verwijzingen naar codefragmenten buiten de opslagplaats verderop in dit artikel voor meer informatie.

• Codeblokken waarmee de gebruiker code kan uitvoeren in de browser.

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

  Zie Interactieve codefragmenten verderop in dit artikel voor meer informatie.

We leggen de Markdown uit voor elk van deze manieren op code op te nemen. Daarnaast biedt het artikel ook enkele algemene richtlijnen voor alle codeblokken.

Code-elementen

Een code-element is een trefwoord, naam van een klasse, naam van een eigenschap, enzovoort in een programmeertaal. Het is niet altijd duidelijk wat kan worden aangeduid als 'code'. NuGet-pakketnamen moeten bijvoorbeeld worden behandeld als code. Als u twijfelt, raadpleegt u deze richtlijnen voor het opmaken van tekst.

Codestijl in regels

Als u een code-element in artikeltekst wilt opnemen, moet u dit omsluiten met backticks (') om de codestijl aan te geven. Voor codestijl in regels mag geen gebruik worden gemaakt van tekenreeksen met drievoudige accent graves.

Markdown	Weergave
Het Entity Framework interpreteert standaard een eigenschap met de naam 'Id' of 'ClassnameID' als de primaire sleutel.	In Entity Framework worden eigenschappen met de naam Id of ClassnameID automatisch als primaire sleutel gezien.

Wanneer een artikel is gelokaliseerd (vertaald in andere talen), wordt tekst met codeopmaak onvertaald gelaten. Zie Niet-gelokaliseerde tekenreeksen als u lokalisatie wilt voorkomen zonder codestijl te gebruiken.

Vet

Sommige oudere stijlrichtlijnen vereisen dat u inlinecode vetgedrukt maakt. Vette tekst is een optie wanneer codestijl te opvallend is en ten koste gaat van de leesbaarheid. Een Markdown-tabel met voornamelijk code-elementen ziet er mogelijk te rommelig uit als overal de codestijl wordt gebruikt. Als u ervoor kiest om de stijl vet te gebruiken, gebruikt u syntaxis voor niet-gelokaliseerde tekenreeksen zodat de code niet wordt gelokaliseerd.

Koppelingen

Een koppeling naar de referentiedocumentatie is mogelijk handiger dan de indeling van de code in sommige contexten. Als u een koppeling gebruikt, past u geen code-indeling toe op de tekst van de koppeling. Wanneer u codeopmaak gebruikt voor een koppeling, is het mogelijk niet meer duidelijk dat de tekst een koppeling is.

Als u een koppeling gebruikt en later in dezelfde context naar hetzelfde element verwijst, gebruikt u code-indeling voor de volgende exemplaren in plaats van koppelingen. Voorbeeld:

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

Weergave:

De eerste verwijzing naar System.CommandLine in deze tekst is een koppeling. Volgende verwijzingen System.CommandLine kunnen in codestijl zijn.

Tijdelijke aanduidingen

Als u wilt dat de gebruiker een sectie met weergegeven code vervangt door hun eigen waarden, gebruikt u tijdelijke aanduidingen voor tekst die is gemarkeerd door punthaken. Voorbeeld:

az group delete -n <ResourceGroupName>

U kunt er rekening mee houden dat de vierkante haken moeten worden verwijderd bij het vervangen van echte waarden. De Microsoft-schrijfstijlgids roept cursief aan, die u kunt opmaken in inlinecode tussen haakjes:

<ResourceGroupName> is de resourcegroep waar...

Accolades { } worden afgeraden voor gebruik als syntactische tijdelijke aanduidingen. Ze kunnen worden verward met dezelfde notatie die wordt gebruikt in vervangbare tekst, opmaaktekenreeksen, tekenreeksinterpolatie, tekstsjablonen en vergelijkbare programmeerconstructies.

Namen van tijdelijke aanduidingen kunnen worden gescheiden door afbreekstreepjes ('statuscase'), met onderstrepingstekens of helemaal niet gescheiden (Pascal-hoofdletter). De syntaxis van De Case van De Case kan een conflict veroorzaken met onderstreepte onderstrepingen. Hoofdletters kunnen conflicteren met benoemde constanten in veel talen, maar het kan ook de aandacht vestigen op de naam van de tijdelijke aanduiding.

<Resource-Group-Name> of <ResourceGroupName>

Codeblokken

De syntaxis voor het opnemen van code in een document is afhankelijk van waar de code zich bevindt:

• In het Markdown-bestand van het artikel
• In een codebestand in dezelfde opslagplaats
• In een codebestand in een andere opslagplaats

Hieronder volgen richtlijnen die van toepassing zijn op alle drie de soorten codeblokken:

• Screenshots
• Codevalidatie automatiseren
• Belangrijke coderegels markeren
• Horizontale schuifbalken vermijden
• Onjuiste code duidelijk identificeren

Schermopnamen

Alle methoden die in de voorgaande sectie worden vermeld, resulteren in bruikbare codeblokken:

• U kunt deze kopiëren en plakken.
• Ze worden geïndexeerd door zoekmachines.
• Ze zijn toegankelijk voor schermlezers.

Dit zijn slechts enkele redenen waarom IDE-schermopnamen niet worden aanbevolen als methode voor het opnemen van code in een artikel. Gebruik IDE-schermopnamen alleen voor code als u iets over de IDE zelf weergeeft, zoals IntelliSense. Gebruik geen schermopnamen om alleen kleuren en markering weer te geven.

Codevalidatie

Sommige opslagplaatsen bevatten geïmplementeerde processen die automatisch alle voorbeeldcode compileren om deze te controleren op fouten. Dit is het geval in de .NET-opslagplaats. Voor meer informatie leest u Contributing (Bijdragen) in de .NET-opslagplaats.

Als u codeblokken uit een andere opslagplaats gebruikt, werkt u met de eigenaren aan een onderhoudsstrategie voor de code, zodat de opgenomen code niet wordt onderbroken of verouderd raakt als nieuwe versies van de bibliotheken die de code gebruikt, worden verzonden.

Markeren

Fragmenten bevatten doorgaans meer code dan nodig is om context te verschaffen. U kunt de leesbaarheid verbeteren door de belangrijkste regels code uit het fragment te markeren, zoals in dit voorbeeld:

U kunt geen code markeren wanneer u de code opneemt in het Markdown-bestand van het artikel. Markering werkt alleen voor codefragmenten die zijn opgenomen door verwijzing naar een codebestand.

Horizontale schuifbalken

Splits lange regels om horizontale schuifbalken te vermijden. Door schuifbalken bij codeblokken is de code lastiger te lezen. Dit geldt vooral voor langere codeblokken, waarbij het wellicht niet mogelijk is om de schuifbalk en de regel code die u wilt lezen, tegelijkertijd te bekijken.

Splits coderegels van meer dan 85 tekens om horizontale schuifbalken in codeblokken te minimaliseren. De aanwezigheid of het ontbreken van een schuifbalk is echter niet het enige criterium voor de leesbaarheid. Als het onderbreken van een regel vóór 85 tekens de leesbaarheid of het kopiëren en plakken nadelig beïnvloedt, kunt u meer dan 85 tekens gebruiken.

Onjuiste code duidelijk identificeren

In sommige scenario's is het handig om codepatronen aan te wijzen die moeten worden vermeden, bijvoorbeeld:

• Code die een compilerfout veroorzaakt als dit wordt geprobeerd.
• Code die correct wordt gecompileerd, maar wordt niet aanbevolen.

Voor deze scenario's:

• Leg de fout zowel in codeopmerkingen als artikeltekst uit.

  Lezers slaan vaak artikeltekst over en kijken alleen naar code, dus het is niet genoeg om de fout alleen in artikeltekst uit te leggen. Het is ook niet voldoende om de fout alleen in codeopmerkingen uit te leggen, omdat codeopmerkingen niet zijn gelokaliseerd.

• Overweeg de code als commentaar te geven als deze een compilerfout zou veroorzaken.

  Code met commentaar verstoort het CI-systeem (continue integratie) niet als de opslagplaats van het artikel er nu een heeft of er in de toekomst een implementeert.

Zie voorbeeld van Rune-gebruik voor een voorbeeld van het presenteren van code die niet wordt aanbevolen: hoofdlettergebruik wijzigen. In dit voorbeeld wordt het advies om te voorkomen dat deze zelfs in de code zelf is ingebouwd, omdat de naam van de C#-methode is ConvertToUpperBadExample.

Codeblokken in regels

Gebruik codeblokken in regels alleen wanneer het niet praktisch is om code weer te geven door verwijzing naar een codebestand. Code in regels is doorgaans moeilijker om te testen en bij te houden dan een codebestand dat deel uitmaakt van een volledig project. Bovendien kan code in regels de context weglaten aan de hand waarvan een ontwikkelaar de code kan begrijpen en gebruiken. Deze overwegingen zijn met name van toepassing op programmeertalen. Codeblokken in regels kunnen ook worden gebruikt voor uitvoer en invoer (zoals JSON), querytalen (zoals SQL) en scripttalen (zoals Power shell).

Er zijn twee manieren om een sectie met tekst in een artikelbestand aan te geven, is een codeblok: door het af te schermen in drie backticks (''') of door het te laten inspringen. De eerste optie heeft de voorkeur, omdat u hiermee de taal kunt opgeven. Vermijd het gebruik van inspringing. Dit kan eenvoudig verkeerd worden geïnterpreteerd en het is moeilijk voor een andere schrijver om te begrijpen wat u bedoelde als hij uw artikel moet wijzigen.

Taalindicatoren worden direct na de eerste drie accents graves geplaatst, zoals in het volgende voorbeeld:

Markdown:

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

Weergave:

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

Tip

GitHub Flavored Markdown biedt ondersteuning voor het scheiden van codeblokken met tildes (~) en met backticks ('). Het symbool dat wordt gebruikt om het codeblok te openen en te sluiten, moet consistent zijn binnen hetzelfde codeblok.

Voor meer informatie over de waarden die u kunt opgeven als taalindicatoren gaat u naar Language names and aliases (Taalnamen en -aliassen).

Als u een taal of omgevingswoord gebruikt na de drievoudige backticks ('''') die niet worden ondersteund, wordt dat woord weergegeven op de titelbalk van de codesectie op de weergegeven pagina. Gebruik waar mogelijk een taal- of omgevingsindicator in de codeblokken in regels.

Notitie

Als u code uit een Word-document kopieert en plakt, moet u ervoor zorgen dat het geen 'gekrulde aanhalingstekens' bevat die niet geldig zijn in code. Als dit het geval is, kunt u de aanhalingstekens omzetten in normale aanhalingstekens (' en "). U kunt ook gebruikmaken van de vervangingsfunctie voor slimme aanhalingstekens in Learn Authoring Pack.

Verwijzingen naar codefragmenten in de opslagplaats

De beste manier om codefragmenten voor programmeertalen op te nemen in artikelen is met een verwijzing naar een codebestand. Hierdoor kunt u regels met code markeren en wordt de bredere context van het fragment beschikbaar op GitHub, zodat ontwikkelaars dit kunnen gebruiken. U kunt code opnemen met behulp van de driedubbele dubbele puntindeling (:::) handmatig of in Visual Studio Code met behulp van het Learn Authoring Pack.

1. Klik in Visual Studio Code op Alt + M of optie + M en selecteer Fragment.
2. Wanneer het fragment is geselecteerd, wordt u gevraagd om een Volledige zoekopdracht, een Zoekopdracht met bereik of een Verwijzing naar meerdere opslagplaatsen. Als u lokaal wilt zoeken, selecteert u Volledige zoekopdracht.
3. Voer een zoekterm in om het bestand te zoeken. Wanneer u het bestand hebt gevonden, selecteert u het.
4. Selecteer vervolgens een optie om te bepalen welke regel(s) code er in het fragment moeten worden opgenomen. De opties zijn: ID, Bereik en Geen.
5. Geef, op basis van uw selectie uit stap 4, indien nodig een waarde op.

Volledig codebestand weergeven:

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

Deel van een codebestand weergeven door regels op te geven:

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

Deel van een codebestand weergeven door de naam van een fragment op te geven:

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

In de volgende gedeelten worden deze voorbeelden uitgelegd:

• Een relatief pad naar het codebestand gebruiken
• Alleen bepaalde regelnummers opnemen
• Verwijzen naar een fragment met naam
• Bepaalde regels markeren

Zie Naslaginformatie over fragmentsyntaxis verderop in dit artikel voor meer informatie.

Pad naar het codebestand

Voorbeeld:

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

Dit voorbeeld komt uit de ASP.NET-docs-opslagplaats, uit het artikelbestand aspnetcore/data/ef-mvc/crud.md. Er wordt naar het codebestand verwezen met een relatief pad naar aspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs in dezelfde opslagplaats.

Bepaalde regelnummers

Voorbeeld:

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

In dit voorbeeld worden alleen regels 2-24 en 26 van het codebestand StudentController.cs weergegeven.

U kunt beter fragmenten met een naam gebruiken dan regelnummers. We leggen hieronder uit waarom.

Fragment met naam

Voorbeeld:

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

Gebruik alleen letters en onderstrepingstekens voor de naam.

In het voorbeeld wordt het gedeelte snippet_Create van het codebestand weergegeven. Het codebestand voor dit voorbeeld bevat fragmenttags in opmerkingen in de C#-code:

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

Benoemde codefragmenten kunnen worden genest, zoals wordt weergegeven in het volgende voorbeeld:

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

Wanneer het Method codefragment wordt weergegeven, worden de Line tags niet opgenomen in de weergegeven uitvoer.

Wanneer mogelijk kunt u beter naar een gedeelte met naam verwijzen dan regelnummers op te geven. Verwijzingen naar regelnummers zijn foutgevoelig omdat codebestanden altijd veranderen, waarbij ook de regelnummers kunnen wijzigen. U ontvangt niet per se een melding van zulke wijzigingen. In uw artikel zullen dan de verkeerde regels worden weergegeven zonder dat u weet dat er iets is veranderd.

Bepaalde regels markeren

Voorbeeld:

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

In het voorbeeld zijn regel 2 en 5 gemarkeerd, waarbij wordt geteld vanaf het begin van het weergegeven fragment. Voor het markeren van regels wordt niet geteld vanaf het begin van het codebestand. Met andere woorden: regel 3 en 6 van het codebestand zijn gemarkeerd.

Verwijzingen naar codefragmenten buiten de opslagplaats

Als het codebestand waarnaar u wilt verwijzen zich in een andere opslagplaats bevindt, moet u de codeopslagplaats instellen als een afhankelijke opslagplaats. In dat geval geeft u er een naam voor op. De naam fungeert vervolgens als mapnaam voor codeverwijzingen.

Neem het volgende voorbeeld: de docs-opslagplaats is Azure/azure-docs en de codeopslagplaats is Azure/azure-functions-durable-extension.

In de hoofdmap van azure-docs voegt u het volgende gedeelte toe in .openpublishing.publish.config.json:

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

Als u nu verwijst naar samples-durable-functions alsof deze een map is in azure-docs, verwijst u eigenlijk naar de hoofdmap in de opslagplaats azure-functions-durable-extension.

U kunt code opnemen met behulp van de driedubbele dubbele puntindeling (:::) handmatig of in Visual Studio Code met behulp van het Learn Authoring Pack.

1. Klik in Visual Studio Code op Alt + M of optie + M en selecteer Fragment.
2. Wanneer het fragment is geselecteerd, wordt u gevraagd om een Volledige zoekopdracht, een Zoekopdracht met bereik of een Verwijzing naar meerdere opslagplaatsen. Als u wilt zoeken in meerdere opslagplaatsen, selecteert u Verwijzing naar meerdere opslagplaatsen.
3. U krijgt een selectie van opslagplaatsen die zich in .openpublishing.publish.config.json bevinden. Selecteer een opslagplaats.
4. Voer een zoekterm in om het bestand te zoeken. Wanneer u het bestand hebt gevonden, selecteert u het.
5. Selecteer vervolgens een optie om te bepalen welke regel(s) code er in het fragment moeten worden opgenomen. De opties zijn: ID, Bereik en Geen.
6. Geef op basis van uw selectie uit stap 5 een waarde op.

Uw fragmentverwijzing ziet er als volgt uit:

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

In de opslagplaats azure-functions-durable-extension bevindt dat codebestand zich in de map samples/csx/shared. Zoals eerder opgemerkt staan regelnummers voor markeringen relatief aan het begin van het fragment in plaats van aan het begin van het bestand.

Notitie

De naam die u aan de afhankelijke opslagplaats toewijst, is relatief ten opzichte van de hoofdmap van de hoofdopslagplaats, maar de tilde (~) verwijst naar de hoofdmap van de docset. De docset-hoofdmap wordt bepaald door build_source_folder in .openpublishing.publish.config.json. Het pad naar het fragment in het vorige voorbeeld werkt in de azure-docs repo omdat build_source_folder naar de repohoofdmap (.) verwijst. Als build_source_folder articles was, zou het pad beginnen met ~/../samples-durable-functions in plaats van ~/samples-durable-functions.

Fragmenten in een Jupyter-notebook

U kunt verwijzen naar een cel in een Jupyter-notebook als codefragment. Als u naar de cel wilt verwijzen:

1. Voeg celmetagegevens toe aan het notitieblok voor de cellen waarnaar u wilt verwijzen.
2. Toegang tot de opslagplaats instellen.
3. Gebruik de syntaxis van het Jupyter-notebookfragment in uw Markdown-bestand.

Metagegevens toevoegen aan notitieblok

1. Geef de cel een naam door celmetagegevens toe te voegen in het Jupyter-notebook.

   • In Jupyter kunt u metagegevens van cellen bewerken door eerst de celwerkbalk in te schakelen: > Metagegevens van celwerkbalk > weergeven.
   • Zodra de celwerkbalk is ingeschakeld, selecteert u Metagegevens bewerken in de cel die u een naam wilt geven.
   • U kunt ook metagegevens rechtstreeks in de JSON-structuur van het notitieblok bewerken.

2. Voeg in de metagegevens van de cel een kenmerk 'name' toe:

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

   Voorbeeld:

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

   Tip

   U kunt alle andere metagegevens toevoegen die u wilt gebruiken om bij te houden waar de cel wordt gebruikt. Voorbeeld:

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

Toegang tot opslagplaats instellen

Als het notebookbestand waarnaar u wilt verwijzen zich in een andere opslagplaats bevindt, stelt u de codeopslagplaats in als een afhankelijke opslagplaats.

Naslaginformatie over jupyter-notebookfragmentsyntaxis

Zodra uw notitieblok de vereiste metagegevens bevat, kunt u ernaar verwijzen in uw Markdown-bestand. Gebruik het <cell-name-value> notitieblok dat u hebt toegevoegd en de opslagplaats die <path> u hebt ingesteld als afhankelijke opslagplaats.

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

Voorbeeld:

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

Belangrijk

Deze syntaxis is een Markdown-blokextensie. Deze moet op zijn eigen regel worden gebruikt.

Gebruik een van de ondersteunde talen voor de <language> id.

Interactieve codefragmenten

Interactieve codeblokken in regels

U kunt codefragmenten uitvoerbaar maken in het browservenster voor de volgende talen:

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

Wanneer de interactieve modus is ingeschakeld, bevatten de weergegeven codevakken de knop Proberen of Uitvoeren. Voorbeeld:

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

wordt weergegeven als:

New-AzResourceGroup -Name myResourceGroup -Location westeurope

And

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

wordt weergegeven als:

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

Als u deze functie voor een bepaald codeblok wilt inschakelen, gebruikt u een speciale taal-id. De beschikbare opties zijn:

• azurepowershell-interactive - Hiermee schakelt u Azure PowerShell Cloud Shell in, zoals in het vorige voorbeeld
• azurecli-interactive - Schakelt de Azure Cloud Shell in
• csharp-interactive-Schakelt de C# REPL in

Voor Azure Cloud Shell en PowerShell Cloud Shell kunnen gebruikers opdrachten uitvoeren voor enkel hun eigen Azure-account.

Codefragmenten die met verwijzing zijn opgenomen

U kunt de interactieve modus inschakelen voor codefragmenten die met verwijzing zijn opgenomen. Als u deze functie voor een bepaald codeblok wilt inschakelen, gebruikt u het kenmerk interactive. De beschikbare kenmerkwaarden zijn:

• cloudshell-powershell - Hiermee schakelt u Azure PowerShell Cloud Shell in, zoals in het vorige voorbeeld
• cloudshell-bash - Schakelt de Azure Cloud Shell in
• try-dotnet - Hiermee schakelt u .NET proberen in
• try-dotnet-class - Hiermee schakelt u .NET proberen met klasse-scaffolding in
• try-dotnet-method - Hiermee schakelt u .NET proberen met methode-scaffolding in

Hieronder volgen een aantal voorbeelden:

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

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

Voor Azure Cloud Shell en PowerShell Cloud Shell kunnen gebruikers alleen opdrachten uitvoeren voor hun eigen Azure-account.

Voor de interactieve ervaring van .NET is de inhoud van uw codeblok afhankelijk van welke van de drie steigers u heeft gekozen:

• Geen scaffolding (try-dotnet): Het codeblok moet een volledige programmatekst vertegenwoordigen. Bijvoorbeeld het Program.cs-bestand dat door dotnet new console is gegenereerd. Deze optie is vooral handig om een heel klein programma weer te geven, met inbegrip van de benodigde using-instructies. Instructies op het hoogste niveau worden op dit moment niet ondersteund.
• Methode-scaffolding (try-dotnet-method): Het codeblok moet de inhoud van een Main methode in een consoletoepassing vertegenwoordigen. U kunt de using-instructies gebruiken die zijn toegevoegd door de sjabloon dotnet new console. Deze optie is het meest geschikt voor korte fragmenten die één functie demonstreren.
• Klasse-scaffolding (try-dotnet-class): Het codeblok moet een klasse vertegenwoordigen met een Main methode als het programmainvoerpunt. Deze optie kan worden gebruikt om weer te geven hoe leden van een klasse met elkaar communiceren.

Naslaginformatie over fragmentsyntaxis

Syntaxis:

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

Belangrijk

Deze syntaxis is een Markdown-blokextensie. Deze moet op zijn eigen regel worden gebruikt.

• <language>( optioneel)

  • Taal van het codefragment. Zie de sectie Ondersteunde talen verderop in dit artikel voor meer informatie.

• <path>(verplichte)

  • Relatief pad naar het bestandssysteem dat het codefragmentbestand aangeeft waarnaar moet worden verwezen.

• <attribute>en <attribute-value>(optioneel)

  • Wordt samen gebruikt om op te geven hoe de code uit het bestand moet worden opgehaald en hoe deze moet worden weergegeven:
    • range: 1,3-5 Een bereik met regels. Dit voorbeeld bevat regels 1, 3, 4 en 5.
    • id: Create De id van het fragment dat moet worden ingevoegd vanuit het codebestand. Deze waarde kan niet naast het bereik bestaan.
    • highlight: 2-4,6 Bereik en/of getallen van regels die moeten worden gemarkeerd in het gegenereerde codefragment. De nummering is relatief ten opzichte van de weergegeven regels (zoals opgegeven met een bereik of id), niet voor het bestand.
    • interactive: cloudshell-powershell, cloudshell-bash, try-dotnet, try-dotnet-class, try-dotnet-method De waarde van de tekenreeks bepaalt welke soorten interactiviteit zijn ingeschakeld.
    • Zie de DocFX-richtlijnen voor details over weergave van tagnamen in bronbestanden van codefragmenten per taal.

Ondersteunde talen

Het Learn Authoring Pack bevat een functie voor het voltooien van de instructie en validatie van de beschikbare taal-id's voor code-omheiningsblokken.

Omheinde codeblokken

Naam	Geldige aliassen
.NET Core CLI	dotnetcli
1C	1c
ABNF	abnf
Toegangslogboeken	accesslog
Ada	ada
ARM assembler	armasm, arm
AVR assembler	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, , , mawknawkgawk
Axapta	axapta
AzCopy	azcopy
Azure-CLI	azurecli
Azure CLI (Interactive)	azurecli-interactive
Azure Powershell	azurepowershell
Azure Powershell (Interactive)	azurepowershell-interactive
Bash	bash, , shzsh
Basis	basic
BNF	bnf
E	c
C#	csharp, cs
C# (Interactive)	csharp-interactive
C++	cpp, , ccc, h, , c++, , h++hpp
C++/CX	cppcx
C++/WinRT	cppwinrt
C/AL	cal
Cache Object Script	cos, cls
CMake	cmake, cmake.in
Coq	coq
CSP	csp
CSS	css
Cap'n Proto	capnproto, capnp
Clojure	clojure, clj
CoffeeScript	coffeescript, , , coffeecsoniced
Crmsh	crmsh, , crmpcmk
Crystal	crystal, cr
Cypher (Neo4j)	cypher
D	d
DAX Power BI	dax
DNS Zone file	dns, , zonebind
DOS	dos, , batcmd
Dart	dart
Delphi	delphi, , dfmdpr, pas, , pascal, freepascal, lprlazaruslfm
Diff	diff, patch
Django	django, jinja
Dockerfile	dockerfile, docker
dsconfig	dsconfig
DTS (Device Tree)	dts
Dust	dust, dst
Dylan	dylan
EBNF	ebnf
Elixir	elixir
Elm	elm
Erlang	erlang, erl
Excel	excel, , xlsxlsx
Extempore	extempore, , xtlangxtm
F#	fsharp, fs
FIX	fix
Fortran	fortran, , f90f95
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
Sturen	handlebars, , , hbshtml.hbshtml.handlebars
Haskell	haskell, hs
Haxe	haxe, hx
Hy	hy, hylang
Ini	ini
Inform7	inform7, i7
IRPF90	irpf90
JSON	json
Java	java, jsp
JavaScript	javascript, , jsjsx
Kotlin	kotlin, kt
Kusto	kusto
Bladknooppunt	leaf
Lasso	lasso, , lslassoscript
Kleiner	less
LDIF	ldif
Lisp	lisp
LiveCode Server	livecodeserver
LiveScript	livescript, ls
Lua	lua
Makefile	makefile, , mkmak
Markdown	markdown, , , mdmkdownmkd
Mathematica	mathematica, , mmawl
Matlab	matlab
Maxima	maxima
Maya Embedded Language	mel
Mercury	mercury
mIRC Scripting Language	mirc, mrc
Mizar	mizar
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, , , mmobjcobj-c
OpenGL Shading Language	glsl
OpenSCAD	openscad, scad
Oracle Rules Language	ruleslanguage
Oxygene	oxygene
PF	pf, pf.conf
PHP	phpphp4, php3, php5php6
Parser3	parser3
Perl	perl, , plpm
Plaintext no highlight	plaintext
Pony	pony
PostgreSQL & PL/pgSQL	pgsql, , postgrespostgresql
PowerShell	powershell, ps
PowerShell (Interactive)	powershell-interactive
Verwerken	processing
Prolog	prolog
Eigenschappen	properties
Protocol Buffers	protobuf
Puppet	puppet, pp
Python	python, , pygyp
Python profiler results	profile
Q#	qsharp
K	k, kdb
QML	qml
R	r
Razor CSHTML	cshtml, , razorrazor-cshtml
ReasonML	reasonml, re
RenderMan RIB	rib
RenderMan RSL	rsl
Roboconf	graph, instances
Robot Framework	robot, rf
RPM spec files	rpm-specfilespec, rpm, rpm-specspecfile
Ruby	ruby, , rbgemspec, podspec, , , thorirb
Rust	rust, rs
SAS	SAS, sas
SCSS	scss
SQL	sql
STEP Part 21	p21, , stepstp
Scala	scala
Schema	scheme
Scilab	scilab, sci
Shape Expressions	shexc
Shell	shell, console
Smali	smali
Smalltalk	smalltalk, st
Solidity	solidity, sol
Stan	stan
Stata	stata
Structured Text	iecst, , , sclstlstructured-text
Stylus	stylus, styl
SubUnit	subunit
Supercollider	supercollider, sc
Swift	swift
Tcl	tcl, tk
Terraform (HCL)	terraform, , tfhcl
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 for Applications	vba
X++	xpp
x86 Assembly	x86asm
XL	xl, tao
XQuery	xquery, , xpathxq
XAML	xaml
XML	xml, , xhtmlrss, atom, , xjb, , xsdxslplist
YAML	yml, yaml
Zephir	zephir, zep

Tip

De functie Learn Authoring Pack, Dev Lang Completion, gebruikt de eerste geldige alias wanneer er meerdere aliassen beschikbaar zijn.

Volgende stappen

Zie Richtlijnen voor het opmaken van tekstvoor meer informatie over de tekstopmaak voor andere inhoudstypen dan code.