Gewusst wie: Einbinden von Code in der Dokumentation

  • Artikel

Es gibt außer Screenshots noch andere Methoden zum Einbinden von Code in einem Artikel, der in der Microsoft Learn veröffentlicht wird:

  • Einzelne Elemente (Wörter) innerhalb einer Zeile

    Es folgt ein Beispiel für das code-Format.

    Verwenden Sie Codeformat, wenn Sie auf benannte Parameter und Variablen in einem in der Nähe befindlichen Codeblock im Text verweisen. Codeformat kann auch für Eigenschaften, Methoden, Klassen und Sprachschlüsselwörter verwendet werden. Weitere Informationen finden Sie unter Codeelemente weiter unten in diesem Artikel.

  • Codeblöcke in der Markdowndatei des Artikels

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

    Verwenden Sie Inlinecodeblöcke, wenn es nicht praktikabel ist, Code durch einen Verweis auf eine Codedatei anzuzeigen. Weitere Informationen finden Sie unter Codeblöcke weiter unten in diesem Artikel.

  • Codeblöcke durch einen Verweis auf eine Codedatei im lokalen Repository

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

    Weitere Informationen finden Sie unter Verweise auf Ausschnitte in Repositorys weiter unten in diesem Artikel.

  • Codeblöcke durch einen Verweis auf eine Codedatei in einem anderen Repository

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

    Weitere Informationen finden Sie unter Verweise auf Ausschnitte außerhalb des Repositorys weiter unten in diesem Artikel.

  • Codeblöcke, mit denen der Benutzer Code im Browser ausführen kann

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

    Weitere Informationen finden Sie unter Interaktive Codeausschnitte weiter unten in diesem Artikel.

Neben einer Erläuterung des Markdown für jede dieser Methoden zum Einbinden von Code enthält der Artikel einige allgemeine Hinweise für alle Codeblöcke.

Codeelemente

Als „Codeelement“ wird in der Programmiersprache z.B. ein Schlüsselwort, Klassenname oder Eigenschaftsname bezeichnet. Es ist nicht immer offensichtlich, was als Code gilt. Beispielsweise sollten NuGet-Paketnamen als Code behandelt werden. Im Zweifelsfall schauen Sie in den Textformatierungsrichtlinien nach.

Inlinecodeformat

Um ein Codeelement in den Artikeltext einzubinden, umgeben Sie es mit Graviszeichen (`), um das Codeformat anzugeben. Beim Inlinecodeformat sollte nicht das Format mit Dreifach-Graviszeichen verwendet werden.

Markdown Gerendert
Standardmäßig interpretiert das Entity Framework eine Eigenschaft mit dem Namen „Id“ oder „ClassnameID“ als Primärschlüssel. Standardmäßig interpretiert Entity Framework Core eine Eigenschaft mit dem Namen Id oder ClassnameID als Primärschlüssel.

Wenn ein Artikel lokalisiert (in andere Sprachen übersetzt) wird, bleibt der als Code formatierte Text unübersetzt. Wenn Sie die Lokalisierung ohne Codeformat verhindern möchten, finden Sie Informationen dazu unter Nicht lokalisierte Zeichenfolgen.

Fettformatierung

Einige ältere Styleguides geben vor, dass Inlinecode fett zu formatieren ist. Fett ist eine Option, wenn das Codeformat so störend ist, dass die Lesbarkeit beeinträchtigt wird. Beispielsweise könnte eine Markdowntabelle, in der sich größtenteils Codeelemente befinden, durch die Codeformatierung etwas überfrachtet aussehen. Wenn Sie Fettformatierung verwenden möchten, nutzen Sie die Syntax für nicht lokalisierte Zeichenfolgen, um sicherzustellen, dass der Code nicht lokalisiert wird.

In einigen Kontexten ist ein Link zu einer Referenzdokumentation möglicherweise hilfreicher als Codeformat. Wenn Sie einen Link verwenden, wenden Sie kein Codeformat auf den Linktext an. Einen Link als Code zu formatieren, kann dazu führen, dass man den Text nicht als Link erkennt.

Wenn Sie einen Link verwenden und später im gleichen Kontext auf dasselbe Element verweisen, verwenden Sie für die nachfolgenden Instanzen Codeformat und keine Links. Beispiel:

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

Gerendert:

Der erste Verweis auf System.CommandLine in diesen Text ist ein Link. Nachfolgende Verweise auf System.CommandLine können im Codeformat enthalten sein.

Platzhalter

Wenn Sie möchten, dass der Benutzer einen Abschnitt des angezeigten Codes durch eigene Werte ersetzt, verwenden Sie Platzhaltertext, der durch spitze Klammern gekennzeichnet ist. Beispiel:

az group delete -n <ResourceGroupName>

Die Klammern müssen entfernt werden, wenn Sie echte Werte einsetzen. Der Microsoft-Leitfaden zum Schreibstil verlangt eine kursive Formatierung, die Sie erzielen, indem Sie Inlinecode in spitze Klammern einschließen:

<ResourceGroupName> ist die Ressourcengruppe, in der...

Die Verwendung von geschweiften Klammern { } als syntaktische Platzhalter wird nicht empfohlen. Sie können mit ersetzbarem Text, Formatzeichenfolgen, Zeichenfolgeninterpolation, Textvorlagen und ähnlichen Programmierkonstrukten verwechselt werden, die die gleiche Notation verwenden.

Platzhalternamen können durch Bindestriche („Kebabschreibweise“), durch Unterstriche oder gar nicht (Pascal-Schreibweise) getrennt werden. Bei der Kebabschreibweise treten möglicherweise Syntaxfehler auf, und sie kann zu Konflikten mit Unterstreichungen führen. Eine Schreibweise nur in Großbuchstaben kann in vielen Sprachen zu Konflikten mit benannten Konstanten führen, sie können aber auch dazu verwendet werden, den Platzhalternamen hervorzuheben.

<Resource-Group-Name> oder <ResourceGroupName>

Codeblöcke

Die Syntax für das Einbinden von Code in einem Dokument hängt davon ab, wo sich der Code befindet:

Die folgenden Richtlinien gelten für alle drei Arten von Codeblöcken:

Screenshots

Alle im vorherigen Abschnitt aufgeführten Methoden führen zu verwendbaren Codeblöcken:

  • Sie können daraus kopieren und einfügen.
  • Sie werden von Suchmaschinen indiziert.
  • Sprachausgaben können darauf zugreifen.

Dies sind nur einige der Gründe, warum IDE-Screenshots nicht als Methode zum Einbinden von Code in einen Artikel empfohlen werden. Verwenden Sie IDE-Screenshots nur dann für Code, wenn Sie etwas über die IDE selbst, z. B. IntelliSense, zeigen. Verwenden Sie Screenshots nicht, um lediglich Farbgebung und Hervorhebung anzuzeigen.

Codeüberprüfung

In einigen Repositorys wird der gesamte Beispielcode durch implementierte Prozesse automatisch kompiliert, um ihn auf Fehler zu prüfen. Dies ist beim .NET-Repository der Fall. Weitere Informationen finden Sie im .NET-Repository unter Contributing (Beitrag).

Wenn Sie Codeblöcke aus einem anderen Repository einbinden, erarbeiten Sie zusammen mit den Besitzern eine Wartungsstrategie für den Code, damit Ihr eingebundener Code nicht unterbrochen wird oder veraltet, sobald neue Versionen der vom Code verwendeten Bibliotheken geliefert werden.

Markieren

Ausschnitte enthalten in der Regel mehr Code als nötig, um den Kontext darzustellen. Die Lesbarkeit wird erleichtert, wenn Sie die wichtigen Zeilen im Codeausschnitt hervorheben, wie z.B. in diesem Beispiel:

Example showing highlighted code

Sie können den Code nicht hervorheben, wenn Sie ihn in der Markdowndatei des Artikels einbinden. Dies funktioniert nur für Codeausschnitte, die durch Verweis auf eine Codedatei eingebunden werden.

Horizontale Scrollleisten

Fügen Sie Umbrüche in langen Zeilen ein, um horizontale Scrollleisten zu vermeiden. Die Verwendung von Scrollleisten bei Codeblöcken erschwert das Lesen des Codes. Sie sind besonders problematisch bei längeren Codeblöcken, bei denen es nicht möglich ist, die Scrollleiste und die zu lesende Zeile gleichzeitig anzuzeigen.

Eine gute Vorgehensweise zur Minimierung horizontaler Scrollleisten in Codeblöcken ist es, in Codezeilen mit mehr als 85 Zeichen einen Umbruch einzufügen. Denken Sie jedoch daran, dass das Vorhandensein oder Fehlen einer Scrollleiste nicht das einzige Kriterium für Lesbarkeit ist. Wenn der Umbruch von Zeilen vor dem 85. Zeichen zu schlechterer Lesbarkeit oder Schwierigkeiten beim Kopieren und Einfügen führt, können Sie auch mehr als 85 Zeichen in der Zeile belassen.

Deutliches Kennzeichnen von fehlerhaftem Code

In einigen Szenarien ist es hilfreich, auf Codierungsmuster hinzuweisen, die vermieden werden sollten, z. B.:

  • Code, der bei einem Kompilierungsversuch einen Compilerfehler verursacht.
  • Code, der ordnungsgemäß kompiliert wird, aber nicht empfohlen wird.

Für diese Szenarien gilt:

  • Erläutern Sie den Fehler sowohl in Codekommentaren als auch im Artikeltext.

    Leser überspringen häufig den Artikeltext und sehen sich nur Code an, daher genügt es nicht, den Fehler nur im Artikeltext zu erklären. Es reicht auch nicht aus, den Fehler nur in Codekommentaren zu erklären, da Codekommentare nicht lokalisiert werden.

  • Kommentieren Sie den Code aus, wenn dieser zu einem Compilerfehler führen würde.

    Auskommentierter Code führt nicht zu einer Unterbrechung des Continuous Integration-Systems (CI), wenn das Repository des Artikels ein solches jetzt oder in Zukunft implementiert.

Ein Beispiel für die Darstellung von Code, der nicht empfohlen wird, finden Sie unter Beispiel für die Verwendung von Rune: Änderung der Groß-/Kleinschreibung. In diesem Beispiel ist die Empfehlung, solchen Code zu vermeiden, sogar in den Code selbst integriert, da der C#-Methodenname ConvertToUpperBadExample lautet.

Inlinecodeblöcke

Verwenden Sie Inlinecodeblöcke nur, wenn es nicht praktikabel ist, Code durch einen Verweis auf eine Codedatei anzuzeigen. Inlinecode ist im Allgemeinen schwieriger zu testen und auf dem neuesten Stand zu halten als eine Codedatei, die Teil eines vollständigen Projekts ist. Außerdem wird beim Inlinecode möglicherweise Kontext ausgelassen, der dem Entwickler dabei helfen könnte, den Code zu verstehen und zu verwenden. Diese Überlegungen gelten vor allem für Programmiersprachen. Inlinecodeblöcke können auch für Ausgaben und Eingaben (z. B. JSON), Abfragesprachen (z. B. SQL) und Skriptsprachen (z. B. PowerShell) verwendet werden.

Es gibt zwei Möglichkeiten, einen Textabschnitt in einer Artikeldatei als Codeblock anzuzeigen: durch Fencing (Umklammern) dieses Abschnitts mit Dreifach-Graviszeichen (```) oder durch Einrücken. Fencing wird bevorzugt, weil Sie dadurch die Sprache festlegen können. Vermeiden Sie das Einrücken, da hierbei zu leicht Fehler gemacht werden und es für einen anderen Autor schwierig sein kann, Ihre Absicht zu verstehen, wenn der Artikel bearbeitet werden muss.

Die Sprachindikatoren werden unmittelbar nach den sich öffnenden Dreifach-Graviszeichen platziert, wie im folgenden Beispiel zu sehen:

Markdown:

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

Gerendert:

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

Tipp

GitHub Flavored Markdown unterstützt die Trennung von Codeblöcken durch Tilden (~) und Graviszeichen (`). Das Symbol zum Öffnen und Schließen des Codeblocks muss innerhalb desselben Codeblocks konsistent sein.

Informationen zu den Werten, die Sie als Sprachindikatoren verwenden können, finden Sie unter Sprachnamen und Aliase.

Wenn Sie nach den Dreifach-Graviszeichen (```) ein nicht unterstütztes Sprach- oder Umgebungswort verwenden, wird dieses Wort in der Titelleiste des Codeabschnitts auf der gerenderten Seite angezeigt. Verwenden Sie nach Möglichkeit einen Sprach- oder Umgebungsindikator in den Inlinecodeblöcken.

Hinweis

Wenn Sie Code aus einem Word-Dokument kopieren und einfügen, vergewissern Sie sich, dass er keine „geschweiften Anführungszeichen“ enthält, die in Code nicht gültig sind. Wenn das der Fall ist, ändern Sie diese wieder in normale Anführungszeichen (' und "). Alternativ können Sie auch die Funktion für den Austausch typografischer Anführungszeichen im Learn Authoring Pack nutzen.

Verweise auf Ausschnitte in Repositorys

Die bevorzugte Methode, Codeausschnitte für Programmiersprachen in Dokumente einzubinden, ist der Verweis auf eine Codedatei. Diese Methode bietet Ihnen die Möglichkeit, Codezeilen hervorzuheben, und stellt den Entwicklern den größeren Kontext des Codeausschnitts auf GitHub zur Verwendung bereit. Sie können Code mithilfe des Formats mit drei Doppelpunkten (:::) entweder manuell oder in Visual Studio Code mit Unterstützung durch das Learn Authoring Pack einbinden.

  1. Drücken Sie in Visual Studio Code ALT+M oder WAHLTASTE+M, und klicken Sie auf „Codeausschnitt“.
  2. Nachdem Sie auf „Codeausschnitt“ geklickt haben, werden Sie dazu aufgefordert, zwischen „Full Search“ (Vollständige Suche), „Scoped Search“ (Bereichsbezogene Suche) oder „Cross-Repository Reference“ (Repositoryübergreifender Verweis) auszuwählen. Wählen Sie „Full Search“ (Vollständige Suche) aus, wenn Sie lokal suchen möchten.
  3. Geben Sie einen Suchbegriff ein, um nach der Datei zu suchen. Wählen Sie die Datei aus, wenn sie gefunden wurde.
  4. Wählen Sie dann eine Option aus, um festzulegen, welche Codezeile(n) im Codeausschnitt enthalten sein sollen. Die Optionen sind: ID, Bereich und Keine.
  5. Geben Sie je nach Auswahl in Schritt 4 einen Wert an.

Die gesamte Codedatei wird angezeigt:

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

Ein Teil einer Codedatei wird durch Angabe von Zeilennummern angezeigt:

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

Ein Teil einer Codedatei wird durch Angabe eines Ausschnittnamens angezeigt:

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

In den folgenden Abschnitten werden diese Beispiele erläutert:

Weitere Informationen finden Sie unter Verweissyntax für Codeausschnitte weiter unten in diesem Artikel.

Pfad zur Codedatei

Beispiel:

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

Das Beispiel stammt aus der Artikeldatei aspnetcore/data/ef-mvc/crud.md des ASP.NET-Dokumentenrepositorys. Auf die Codedatei wird über einen relativen Pfad zu aspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs im selben Repository verwiesen.

Ausgewählte Zeilennummern

Beispiel:

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

In diesem Beispiel werden nur die Zeilen 2–24 und 26 der Codedatei StudentController.cs angezeigt.

Bevorzugen Sie benannte Codeausschnitte gegenüber hartcodierten Zeilennummern, wie im nächsten Abschnitt erläutert.

Benannter Codeausschnitt

Beispiel:

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

Verwenden Sie für den Namen nur Buchstaben und Unterstriche.

Das Beispiel zeigt den Abschnitt snippet_Create der Codedatei. Die Codedatei für dieses Beispiel enthält Codeausschnitttags in Kommentaren im C#-Code:

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

Benannte Codeausschnitte können geschachtelt werden, wie im folgenden Beispiel gezeigt:

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

Wenn der Method-Codeausschnitt gerendert wird, sind die Line-Tags nicht in der gerenderten Ausgabe enthalten.

Wenn möglich, sollten Sie immer auf einen benannten Abschnitt verweisen anstatt Zeilennummern anzugeben. Zeilennummernverweise sind fehleranfällig, weil sich Codedateien zwangsläufig in einer Weise ändern, die die Zeilennummern verändern. Über solche Änderungen werden Sie nicht unbedingt informiert. In Ihrem Artikel werden dann die falschen Zeilen angezeigt, und Sie haben keine Ahnung, dass sich überhaupt etwas geändert hat.

Hervorheben ausgewählter Zeilen

Beispiel:

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

Im Beispiel werden die Zeilen 2 und 5 hervorgehoben, gezählt vom Anfang des angezeigten Ausschnitts. Bei hervorzuhebenden Zeilennummern wird mit dem Zählen nicht am Anfang der Codedatei begonnen. Die Zeilen 3 und 6 der Codedatei werden also hervorgehoben.

Verweise auf Ausschnitte außerhalb des Repositorys

Wenn sich die Codedatei, auf die verwiesen werden soll, in einem anderen Repository befindet, richten Sie das Coderepository als abhängiges Repository ein. Geben Sie in diesem Fall einen Namen dafür an. Dieser Name verhält sich dann wie ein Ordnername für Codeverweise.

Zum Beispiel lautet das Dokumentenrepository Azure/azure-docs und das Coderepository Azure/azure-functions-durable-extension.

Fügen Sie im Stammordner von azure-docs den folgenden Abschnitt in .openpublishing.publish.config.json hinzu:

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

Wenn Sie nun auf samples-durable-functions verweisen, als wäre es ein Ordner in azure-docs, verweisen Sie tatsächlich jedoch auf den Stammordner im Repository azure-functions-durable-extension.

Sie können Code mithilfe des Formats mit drei Doppelpunkten (:::) entweder manuell oder in Visual Studio Code mit Unterstützung durch das Learn Authoring Pack einbinden.

  1. Drücken Sie in Visual Studio Code ALT+M oder WAHLTASTE+M, und klicken Sie auf „Codeausschnitt“.
  2. Nachdem Sie auf „Codeausschnitt“ geklickt haben, werden Sie dazu aufgefordert, zwischen „Full Search“ (Vollständige Suche), „Scoped Search“ (Bereichsbezogene Suche) oder „Cross-Repository Reference“ (Repositoryübergreifender Verweis) auszuwählen. Wählen Sie „Cross-Repository Reference“ (Repositoryübergreifender Verweis) aus, um repositoryübergreifend zu suchen.
  3. Daraufhin wird eine Auswahl der Repositorys angezeigt, die sich in .openpublishing.publish.config.json befinden. Wählen Sie ein Repository aus.
  4. Geben Sie einen Suchbegriff ein, um nach der Datei zu suchen. Wählen Sie die Datei aus, wenn sie gefunden wurde.
  5. Wählen Sie dann eine Option aus, um festzulegen, welche Codezeile(n) im Codeausschnitt enthalten sein sollen. Die Optionen sind: ID, Bereich und Keine.
  6. Geben Sie je nach Auswahl in Schritt 5 einen Wert an.

Ihr Codeausschnittverweis sieht folgendermaßen aus:

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

Im Repository azure-functions-durable-extension befindet sich diese Codedatei im Ordner samples/csx/shared. Wie oben erwähnt, sind die Zeilennummern für die Hervorhebung relativ zum Anfang des Codeausschnitts und nicht zum Anfang der Datei.

Hinweis

Der Name, den Sie dem abhängigen Repository zuweisen, ist relativ zum Stamm des Hauptrepositorys, aber die Tilde (~) verweist auf den Stamm des Docsets. Der Docset-Stamm wird von build_source_folder in .openpublishing.publish.config.json festgelegt. Der Pfad zum Codeausschnitt im vorherigen Beispiel wird im Repository „azure-docs“ verwendet, da build_source_folder auf den Repositorystamm (.) verweist. Wenn für build_source_folder der Wert articles angegeben wäre, würde der Pfad mit ~/../samples-durable-functions anstelle von ~/samples-durable-functions beginnen.

Codeausschnitte in einem Jupyter-Notebook

Sie können auf eine Zelle in einem Jupyter-Notebook als Codeausschnitt verweisen. So verweisen Sie auf die Zelle:

  1. Fügen Sie dem Notebook Zellenmetadaten hinzu, auf die Sie verweisen möchten.
  2. Richten Sie den Zugriff auf das Repository ein.
  3. Verwenden Sie die Syntax für den Jupyter-Notebook-Ausschnitt in Ihrer Markdowndatei.

Hinzufügen von Metadaten zur Notebook-Instanz

  1. Benennen Sie die Zelle, indem Sie Zellenmetadaten im Jupyter-Notebook hinzufügen.

    • In Jupyter können Sie Zellmetadaten bearbeiten, indem Sie zuerst die Zellensymbolleiste aktivieren: Ansicht > Zellensymbolleiste > Metadaten bearbeiten.
    • Nachdem die Zellensymbolleiste aktiviert ist, wählen Sie Metadaten bearbeiten in der Zelle aus, die Sie benennen möchten.
    • Alternativ können Sie die Metadaten direkt in der JSON-Struktur des Notebooks bearbeiten.

  2. Fügen Sie in den Zellenmetadaten ein „name“-Attribut hinzu:

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

    Beispiel:

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

    Tipp

    Sie können weitere Metadaten hinzufügen, die Ihnen helfen können, nachzuverfolgen, wo die Zelle verwendet wird. Beispiel:

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

Einrichten des Repositoryzugriffs

Wenn sich die die Notebook-Datei, auf die verwiesen werden soll, in einem anderen Repository befindet, richten Sie das Coderepository als abhängiges Repository ein.

Referenz zur Syntax für den Jupyter-Notebook-Ausschnitt

Wenn Ihr Notebook die erforderlichen Metadaten enthält, verweisen Sie in Ihrer Markdowndatei darauf. Verwenden Sie den <cell-name-value>, den Sie dem Notebook hinzugefügt haben, sowie den <path> (Pfad), den Sie als Ihr abhängiges Repository eingerichtet haben.

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

Beispiel:

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

Wichtig

Diese Syntax ist ein Blockmarkdown-Erweiterung. Sie muss in einer eigenen Zeile verwendet werden.

Verwenden Sie für den <language>-Bezeichner eine der unterstützten Programmiersprachen.

Interaktive Codeausschnitte

Interaktive Inlinecodeblöcke

Für die folgenden Sprachen können Codeausschnitte im Browserfenster ausführbar gemacht werden:

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

Wenn der interaktive Modus aktiviert ist, verfügen die gerenderten Codeboxen über die Schaltflächen Try It (Testen) und Run (Ausführen). Beispiel:

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

wird wie folgt gerendert:

New-AzResourceGroup -Name myResourceGroup -Location westeurope

Und

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

rendert als:

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

Um dieses Feature für einen bestimmten Codeblock zu aktivieren, verwenden Sie eine spezielle Sprachen-ID. Verfügbare Optionen:

  • azurepowershell-interactive: Aktiviert wie im vorherigen Beispiel PowerShell für Azure Cloud Shell
  • azurecli-interactive: Aktiviert Azure Cloud Shell
  • csharp-interactive: Aktiviert C#-REPL

Für Azure Cloud Shell und PowerShell Cloud Shell können Benutzer Befehle nur für ihr eigenes Azure-Konto ausführen.

Durch einen Verweis eingebundene Codeausschnitte

Sie können den interaktiven Modus für Codeausschnitte aktivieren, die per Verweis eingebunden werden. Verwenden Sie das Attribut interactive, um dieses Feature für einen bestimmten Codeblock zu aktivieren. Folgende Attributwerte sind verfügbar:

  • cloudshell-powershell: Aktiviert wie im vorherigen Beispiel PowerShell für Azure Cloud Shell
  • cloudshell-bash: Aktiviert Azure Cloud Shell
  • try-dotnet: Aktiviert Try .NET
  • try-dotnet-class: Aktiviert Try .NET mit Klassengerüsten
  • try-dotnet-method: Aktiviert Try .NET mit Methodengerüsten

Im Folgenden finden Sie einige Beispiele:

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

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

Für Azure Cloud Shell und PowerShell Cloud Shell können Benutzer Befehle nur für ihr eigenes Azure-Konto ausführen.

Für die .NET Interactive-Erfahrung hängt der Inhalt Ihres Codeblocks davon ab, welche der drei Gerüstumgebungen Sie auswählen:

  • Kein Gerüstbau (try-dotnet): Der Codeblock sollte einen vollständigen Programmtext darstellen. Die Datei Program.cs, die von dotnet new console generiert wird, wäre z. B. gültig. Diese sind am nützlichsten, um ein ganzes kleines Programm anzuzeigen, einschließlich der erforderlichen using-Direktiven. Anweisungen auf oberster Ebene werden derzeit nicht unterstützt.
  • Methodengerüstbau (try-dotnet-method): Der Codeblock sollte den Inhalt einer Main-Methode in einer Konsolenanwendung darstellen. Sie können die von der dotnet new console-Vorlage hinzugefügten using-Direktiven annehmen. Diese Einstellung ist am nützlichsten für kurze Codeausschnitte, die ein Feature veranschaulichen.
  • Klassengerüstbau (try-dotnet-class): Der Codeblock sollte eine Klasse mit einer Main-Methode als Programmeinstiegspunkt darstellen. Diese können verwendet werden, um zu zeigen, wie die Member einer Klasse interagieren.

Verweissyntax für Codeausschnitte

Syntax:

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

Wichtig

Diese Syntax ist ein Blockmarkdown-Erweiterung. Sie muss in einer eigenen Zeile verwendet werden.

  • <language> (optional)

    • Sprache des Codeausschnitts. Weitere Informationen finden Sie im Abschnitt Unterstützte Sprachen weiter unten in diesem Artikel.

  • <path> (erforderlich)

    • Der relative Pfad im Dateisystem, der die Codeausschnittdatei angibt, auf die verwiesen werden soll.

  • <attribute> und <attribute-value> (optional)

    • Zusammen verwendet, um anzugeben, wie der Code aus der Datei abgerufen und wie er angezeigt werden soll:
      • range: 1,3-5 Ein Bereich von Zeilen. Dieses Beispiel umfasst die Zeilen 1, 3, 4 und 5.
      • id: Create Die ID des Codeausschnitts, der aus der Codedatei eingefügt werden soll. Dieser Wert kann nicht gleichzeitig mit einem Bereich vorhanden sein.
      • highlight: 2-4,6 Der Bereich und/oder die Zeilennummern, die im generierten Codeausschnitt hervorgehoben werden sollen. Die Nummerierung ist relativ zu den angezeigten Zeilen (gemäß Bereich oder ID) und nicht zur Datei.
      • interactive: cloudshell-powershell, cloudshell-bash, try-dotnet, try-dotnet-class, try-dotnet-method: Der Zeichenfolgenwert legt fest, welche Arten von Interaktivität aktiviert sind.
      • Weitere Informationen zur Darstellung von Tagnamen in Codeausschnitten von Quelldateien nach Programmiersprache finden Sie in den DocFX-Richtlinien.

Unterstützte Sprachen

Das Learn Authoring Pack enthält eine Funktion, die Anweisungsvervollständigung und eine Überprüfung der verfügbaren Sprachen-IDs für Codefence-Blöcke bietet.

Umgrenzte Codeblöcke

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

Tipp

Wenn mehrere Aliase verfügbar sind, verwendet die Funktion zur Vervollständigung von Entwicklungssprachen im Learn Authoring Pack den ersten gültigen Alias.

Nächste Schritte

Informationen zur Textformatierung für andere Inhaltstypen als Code finden Sie in den Textformatierungsrichtlinien.