Share via

Code opnemen in documentatie

  • Artikel

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.

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:

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

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:

Example showing highlighted code

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:

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