Jak dołączyć kod do dokumentacji

Istnieje kilka sposobów innych niż zrzuty ekranu do uwzględnienia kodu w artykule opublikowanym w witrynie Microsoft Learn:

• Poszczególne elementy (wyrazy) w wierszu.

  Oto przykład stylu code.

  Użyj formatu kodu podczas odwoływania się do nazwanych parametrów i zmiennych w pobliskim bloku kodu w tekście. Format kodu może być również używany w przypadku właściwości, metod, klas i słów kluczowych języka. Aby uzyskać więcej informacji, zobacz sekcję Elementy kodu w dalszej części tego artykułu.

• Bloki kodu w pliku Markdown artykułu.

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

  Użyj wbudowanych bloków kodu, gdy wyświetlenie kodu poprzez odwołanie do pliku z kodem jest niepraktyczne. Aby uzyskać więcej informacji, zobacz sekcję Bloki kodu w dalszej części tego artykułu.

• Bloki kodu poprzez odniesienie do pliku z kodem w lokalnym repozytorium.

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

  Aby uzyskać więcej informacji, zobacz sekcję Odwołania do fragmentu kodu w repozytorium w dalszej części tego artykułu.

• Bloki kodu poprzez odniesienie do pliku z kodem w innym repozytorium.

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

  Aby uzyskać więcej informacji, zobacz sekcję Odwołania do fragmentu kodu spoza repozytorium w dalszej części tego artykułu.

• Bloki kodu, które umożliwiają użytkownikowi wykonanie kodu w przeglądarce.

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

  Aby uzyskać więcej informacji, zobacz sekcję Fragmenty kodu interaktywnego w dalszej części tego artykułu.

Oprócz wyjaśnienia zapisu w języku Markdown dla każdego z tych sposobów dołączenia kodu artykuł zawiera pewne ogólne wytyczne dla wszystkich bloków kodu.

Elementy kodu

„Elementem kodu” może być słowo kluczowe języka programowania, nazwa klasy lub właściwości itd. Nie zawsze jest oczywiste co można zaliczyć do kodu. Na przykład nazwy pakietów NuGet powinny być traktowane jako kod. W razie wątpliwości, zobacz artykuł Wskazówki dotyczące formatowania tekstu.

Styl kodu wbudowanego

Aby uwzględnić element kodu w tekście artykułu, umieść go za pomocą backticks ('), aby wskazać styl kodu. Styl kodu wbudowanego nie powinien korzystać z formatu z potrójnym grawisem.

Markdown	Renderowane
Domyślnie platforma Entity Framework interpretuje właściwość o nazwie "Id" lub "ClassnameID" jako klucz podstawowy.	Domyślnie platforma Entity Framework interpretuje właściwość o nazwie Id lub ClassnameID jako klucz podstawowy.

Podczas lokalizowania artykułu (tłumaczenia go na inne języki) tekst wstawiony jako kod pozostanie nieprzetłumaczony. Jeśli chcesz zapobiec lokalizacji bez używania stylu kodu, zobacz sekcję Nielokalizowane ciągi.

Styl pogrubiony

Niektóre starsze przewodniki po stylu stosują pogrubienie dla kodu wbudowanego. Pogrubienie jest opcją w przypadku, gdy styl kodu pogarsza czytelność. Na przykład tabela Markdown zawierająca głównie elementy kodu może wyglądać na zbyt zagęszczoną w przypadku zastosowania wszędzie stylu kodu. Jeśli zdecydujesz się używać stylu pogrubionego, użyj składni ciągów nielokalizowanych, aby upewnić się, że kod nie zostanie zlokalizowany.

Łącza

Link do dokumentacji referencyjnej może być w niektórych kontekstach bardziej użyteczny niż format kodu. Jeśli używasz linku, nie stosuj formatu kodu do tekstu linku. Użycie stylu właściwego dla kodu w odniesieniu do linku może ukryć fakt, że tekst jest linkiem.

Jeśli używasz linku i odwołujesz się do tego samego elementu w dalszej części tego samego kontekstu, użyj formatu kodu dla kolejnych wystąpień zamiast linków. Na przykład:

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

Renderowane:

Pierwsze odwołanie do System.CommandLine tego tekstu jest linkiem. Kolejne odwołania mogą System.CommandLine być w stylu kodu.

Symbole zastępcze

Jeśli chcesz, aby użytkownik zamienił sekcję wyświetlanego kodu na własne wartości, użyj tekstu zastępczego oznaczonego nawiasami kątowymi. Na przykład:

az group delete -n <ResourceGroupName>

Można zauważyć, że nawiasy muszą zostać usunięte podczas zastępowania wartości rzeczywistych. Przewodnik stylu pisania firmy Microsoft wywołuje kursywę, którą można sformatować w kodzie wbudowanym w nawias kątowy:

<ResourceGroupName> to grupa zasobów, w której...

Nawiasy klamrowe { } są odradzane do użycia jako symbole zastępcze składniowe. Mogą być mylone z tą samą notacją używaną w zamian tekst, ciągi formatu, interpolację ciągów, szablony tekstu i podobne konstrukcje programowania.

Nazwy symboli zastępczych można rozdzielić łącznikami ("przypadek kebabu"), podkreśleniami lub w ogóle nie rozdzielać (przypadek Pascala). Przypadek Kebab może generować błędy składni i podkreślenia mogą powodować konflikt z podkreśleniami. Wszystkie limity mogą powodować konflikt z nazwanymi stałymi w wielu językach, ale może również zwrócić uwagę na nazwę symbolu zastępczego.

<Resource-Group-Name> lub <ResourceGroupName>

Bloki kodu

Składnia dołączania kodu w dokumencie zależy od miejsca, w którym znajduje się kod:

• W pliku Markdown artykułu
• W pliku z kodem w tym samym repozytorium
• W pliku z kodem w innym repozytorium

Poniżej przedstawiono wskazówki dotyczące wszystkich trzech typów bloków kodu:

• Zrzuty ekranu
• Automatyzowanie walidacji kodu
• Wyróżnianie kluczowych wierszy kodu
• Unikaj poziomych pasków przewijania
• Wyraźnie zidentyfikuj nieprawidłowy kod

Zrzuty ekranu

Wszystkie metody wymienione w poprzedniej sekcji dają w rezultacie użyteczne bloki kodu:

• Można kopiować i wklejać ich zawartość.
• Są one indeksowane przez wyszukiwarki.
• Są one dostępne dla czytników zawartości ekranu.

To tylko kilka powodów, dla których zrzuty ekranu środowiska IDE nie są zalecane jako metoda dołączania kodu w artykule. Używaj zrzutów ekranu środowiska IDE w przypadku kodu tylko wtedy, gdy chcesz pokazać coś dotyczącego samego środowiska IDE, na przykład funkcję IntelliSense. Nie używaj zrzutów ekranu tylko do pokazywania kolorowania i wyróżniania.

Weryfikowanie kodu

W niektórych repozytoriach wdrożono procesy, które automatycznie kompilują każdy przykładowy kod w celu sprawdzenia, czy nie występują w nim błędy. Tak jest w przypadku repozytorium .NET. Aby uzyskać więcej informacji, zobacz artykuł Dodawanie treści w repozytorium .NET.

Jeśli dołączasz bloki kodu z innego repozytorium, zadbaj wraz z właścicielami kodu o strategię konserwacji kodu, aby dołączony kod nie uległ uszkodzeniu lub nie zdezaktualizował się w momencie udostępnienia nowych wersji bibliotek, z których korzysta.

Wyróżnianie

W celu zilustrowania kontekstu fragmenty kodu zazwyczaj obejmują więcej kodu niż jest to konieczne. Wyróżnienie kluczowych wierszy, które są najbardziej istotne we fragmencie kodu, zwiększa czytelność — jak w poniższym przykładzie:

Nie można wyróżnić kodu umieszczonego w pliku Markdown artykułu. Działa to tylko w przypadku fragmentów kodu zawartych w odniesieniu do pliku z kodem.

Poziome paski przewijania

Należy łamać długie wiersze, co pozwala uniknąć pojawiania się poziomych pasków przewijania. Paski przewijania w blokach kodu utrudniają czytanie kodu. Są one szczególnie kłopotliwe w przypadku dłuższych bloków kodu, ponieważ może okazać się niemożliwe jednoczesne wyświetlanie paska przewijania i wiersza, który chcesz odczytać.

Dobrym rozwiązaniem w celu zminimalizowania użycia poziomych pasków przewijania w blokach kodu jest podział wierszy kodu zawierających więcej niż 85 znaków. Należy jednak pamiętać, że obecność lub brak paska przewijania nie jest jedynym kryterium czytelności. Jeśli podział wiersza przed 85. znakiem wpływa negatywnie na czytelność lub wygodę kopiowania i wklejania, używaj ponad 85 znaków.

Wyraźnie zidentyfikuj nieprawidłowy kod

W niektórych scenariuszach warto wskazać wzorce kodowania, których należy unikać, na przykład:

• Kod, który spowoduje błąd kompilatora w przypadku próby.
• Kod, który będzie kompilowany poprawnie, ale nie jest zalecany.

W przypadku następujących scenariuszy:

• Wyjaśnij błąd zarówno w komentarzach kodu, jak i tekście artykułu.

  Czytelnicy często pomijają tekst artykułu i patrzą tylko na kod, więc nie wystarczy wyjaśnić błąd tylko w tekście artykułu. Nie wystarczy również wyjaśnić błąd tylko w komentarzach kodu, ponieważ komentarze kodu nie są zlokalizowane.

• Rozważ komentarz kodu, jeśli spowoduje to błąd kompilatora.

  Kod z komentarzem nie zakłóca systemu ciągłej integracji, jeśli repozytorium artykułu ma taki kod lub implementuje go w przyszłości.

Aby zapoznać się z przykładem prezentowania kodu, który nie jest zalecany, zobacz Przykład użycia elementu Rune: zmiana wielkości liter. W tym przykładzie porada, aby uniknąć, jest nawet wbudowana w sam kod, ponieważ nazwa metody języka C# to ConvertToUpperBadExample.

Wbudowane bloki kodu

Używaj wbudowanych bloków kodu tylko wtedy, gdy wyświetlenie kodu poprzez odwołanie do pliku z kodem jest niepraktyczne. Kod wbudowany jest na ogół trudniejszy do testowania i aktualizacji niż plik z kodem, który stanowi część całego projektu. Kod wbudowany może też pomijać kontekst, który mógłby pomóc deweloperowi zrozumieć i wykorzystać kod. Kwestie te dotyczą głównie języków programowania. Wbudowanych bloków kodu można także używać w przypadku danych wyjściowych i wejściowych (takich jak JSON), języków zapytań (takich jak SQL) i języków skryptów (takich jak PowerShell).

Istnieją dwa sposoby wskazywania sekcji tekstu w pliku artykułu jest blokiem kodu: przez ogrodzenie go w potrójnych backticksach ('') lub przez wcięcie. Preferowane jest umieszczenie go między znakami, ponieważ umożliwia to określenie języka. Unikaj używania wcięć, ponieważ bardzo łatwo można popełnić błąd, a inny autor może mieć trudności ze zrozumieniem Twojego zamiaru w przypadku konieczności edytowania artykułu.

Wskaźniki języka są umieszczane bezpośrednio po otwierającym znaku potrójnego grawisu, jak w poniższym przykładzie:

Znacznik języka Markdown:

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

Renderowane:

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

Napiwek

Język Markdown w usłudze GitHub Flavored obsługuje rozdzielanie bloków kodu z tyldami (~), a także z backticksami ('). Symbol używany do otwierania i zamykania bloku kodu musi być spójny w tym samym bloku kodu.

Informacje o wartościach, które można użyć jako wskaźnik języka, można znaleźć w artykule Nazwy i aliasy języków.

Jeśli używasz wyrazu języka lub środowiska po potrójnym backticksie ('''), który nie jest obsługiwany, ten wyraz pojawia się na pasku tytułu sekcji kodu na renderowanej stronie. Jeśli to możliwe, używaj wskaźnika języka lub środowiska we wbudowanych blokach kodu.

Uwaga

Jeśli skopiujesz i wklejasz kod z dokumentu programu Word, upewnij się, że nie ma on "cudzysłowów curly", które nie są prawidłowe w kodzie. Jeśli są one obecne, zamień je z powrotem na cudzysłowy proste (' i "). Alternatywnie, polegaj na pakiecie Learn Authoring Pack, funkcji zamiany cudzysłowów inteligentnych.

Odwołania do fragmentu kodu w repozytorium

Preferowanym sposobem umieszczania fragmentów kodu dla języków programowania w dokumentacji jest odwołanie do pliku z kodem. Ta metoda umożliwia wyróżnianie wierszy kodu i udostępnienie szerszego kontekstu fragmentu kodu w witrynie GitHub na potrzeby deweloperów. Kod można dołączyć przy użyciu formatu dwukropka (:::) ręcznie lub w programie Visual Studio Code za pomocą pakietu Learn Authoring Pack.

1. W programie Visual Studio Code naciśnij klawisze Alt+M lub Option+M, a następnie wybierz fragment kodu.
2. Po wybraniu fragmentu kodu zostanie wyświetlony monit o pełne wyszukiwanie, wyszukiwanie zakresowe lub odwołanie między repozytoriami. Aby wykonać wyszukiwanie lokalne, wybierz pełne wyszukiwanie.
3. Wprowadź wyszukiwany termin, aby odnaleźć plik. Po odnalezieniu pliku wybierz go.
4. Następnie wybierz opcję, aby określić, które wiersze kodu mają być uwzględnione we fragmencie kodu. Dostępne są następujące opcje: ID, Range i None.
5. W zależności od wyboru w kroku 4 w razie potrzeby podaj wartość.

Wyświetlanie całego pliku z kodem:

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

Wyświetlanie części pliku z kodem poprzez określenie numerów wierszy:

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

Wyświetlanie części pliku z kodem poprzez określenie nazwy fragmentu kodu:

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

W poniższych sekcjach opisano te przykłady:

• Użycie ścieżki względnej do pliku z kodem
• Włączenie tylko wybranych numerów wierszy
• Odwołanie do nazwy fragmentu kodu
• Wyróżnianie wybranych wierszy

Aby uzyskać więcej informacji, zobacz sekcję Odwołanie do składni fragmentu kodu w dalszej części tego artykułu.

Ścieżka do pliku z kodem

Przykład:

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

Przykład pochodzi z repozytorium dokumentów ASP.NET, plik artykułu: aspnetcore/data/ef-mvc/crud.md. Odwołanie do pliku z kodem występuje w formie względnej ścieżki do pliku aspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs w tym samym repozytorium.

Numery wybranych wierszy

Przykład:

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

W tym przykładzie wyświetlane są tylko wiersze od 2 do 24 i wiersz 26 w pliku z kodem StudentController.cs.

Jak wyjaśniono w następnej sekcji, preferowane są nazwane fragmenty kodu zamiast zakodowanych numerów wierszy.

Nazwany fragment kodu

Przykład:

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

Używaj tylko liter i podkreśleń na potrzeby nazwy.

W przykładzie pokazana jest sekcja snippet_Create pliku z kodem. Plik z kodem dla tego przykładu zawiera tagi fragmentów kodu w komentarzach kodu w języku C#:

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

Nazwane fragmenty kodu można zagnieżdżać, jak pokazano w poniższym przykładzie:

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

Po renderowaniu Line fragmentu Method kodu tagi nie są uwzględniane w renderowanych danych wyjściowych.

Jeśli to tylko możliwe, odwołuj się do nazwanej sekcji zamiast do numerów wierszy. Odwołania do numerów wierszy są elementem wrażliwym, ponieważ pliki z kodem podlegają nieuchronnym modyfikacjom, które powodują zmianę numerów wierszy. Użytkownik nie zawsze jest informowany o takich zmianach. W rezultacie w otwartym artykule zostaną wyświetlone niewłaściwe wiersze i nie będzie dostępna żadna wskazówka, że coś się zmieniło.

Wyróżnianie wybranych wierszy

Przykład:

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

W przykładzie wyróżniono linie 2 i 5, licząc od początku wyświetlanego fragmentu kodu. Numery wierszy przeznaczonych do wyróżnienia nie są liczone od początku pliku z kodem. Innymi słowy, wyróżnione są wiersze 3 i 6 pliku z kodem.

Odwołania do fragmentu kodu spoza repozytorium

Jeśli plik z kodem, do którego ma nastąpić odwołanie, znajduje się w innym repozytorium, skonfiguruj repozytorium kodu jako repozytorium zależne. W trakcie konfigurowania określana jest jego nazwa. Ta nazwa funkcjonuje następnie jako nazwa folderu na potrzeby odwołania do kodu.

Na przykład repozytorium dokumentów to Azure/azure-docs, a repozytorium kodu to Azure/azure-functions-durable-extension.

W folderze głównym repozytorium azure-docs w pliku . openpublishing.publish.config.json dodaj następującą sekcję:

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

Od tej pory, gdy odwołasz się do nazwy samples-durable-functions w taki sposób, jakby był to folder w repozytorium azure-docs, w rzeczywistości odwołasz się do folderu głównego w repozytorium azure-functions-durable-extension.

Kod można dołączyć przy użyciu formatu dwukropka (:::) ręcznie lub w programie Visual Studio Code za pomocą pakietu Learn Authoring Pack.

1. W programie Visual Studio Code naciśnij klawisze Alt+M lub Option+M, a następnie wybierz fragment kodu.
2. Po wybraniu fragmentu kodu zostanie wyświetlony monit o pełne wyszukiwanie, wyszukiwanie zakresowe lub odwołanie między repozytoriami. Aby przeprowadzić wyszukiwanie w wielu repozytoriach, wybierz pozycję Cross-Repository Reference (Odwołanie między repozytoriami).
3. Możliwy będzie wybór między repozytoriami, które znajdują się w pliku .openpublishing.publish.config.json. Wybierz repozytorium.
4. Wprowadź wyszukiwany termin, aby odnaleźć plik. Po odnalezieniu pliku wybierz go.
5. Następnie wybierz opcję, aby określić, które wiersze kodu mają być uwzględnione we fragmencie kodu. Dostępne są następujące opcje: ID, Range i None.
6. Podaj wartość w zależności od wyboru dokonanego w kroku 5.

Odwołanie do fragmentu kodu będzie wyglądać następująco:

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

W repozytorium azure-functions-durable-extension ten plik z kodem znajduje się w folderze samples/csx/shared. Jak zaznaczono wcześniej, numery wierszy do wyróżniania są określane względem początku fragmentu kodu, a nie względem początku pliku.

Uwaga

Nazwa przypisana do repozytorium zależnego jest względna względem katalogu głównego repozytorium głównego, ale tylda (~) odnosi się do katalogu głównego zestawu dokumentów. Katalog główny zestawu dokumentów jest określany przez build_source_folder element w pliku .openpublishing.publish.config.json. Ścieżka do fragmentu kodu w powyższym przykładzie działa w repozytorium azure-docs, ponieważ parametr build_source_folder odnosi się do katalogu głównego repozytorium (.). Gdyby parametr build_source_folder miał wartość articles, ścieżka zaczynałaby się od ciągu ~/../samples-durable-functions, a nie ~/samples-durable-functions.

Fragmenty kodu w notesie Jupyter

Możesz odwołać się do komórki w notesie Jupyter jako fragment kodu. Aby odwołać się do komórki:

1. Dodaj metadane komórek do notesu dla komórek, do których chcesz się odwołać.
2. Skonfiguruj dostęp do repozytorium.
3. Użyj składni fragmentu kodu notesu Jupyter w pliku markdown.

Dodawanie metadanych do notesu

1. Nadaj komórce nazwę, dodając metadane komórek w notesie Jupyter.

   • W programie Jupyter można edytować metadane komórek, włączając najpierw pasek narzędzi komórki: Wyświetl > pasek narzędzi > Komórki Edytuj metadane.
   • Po włączeniu paska narzędzi komórki wybierz pozycję Edytuj metadane w komórce, którą chcesz nazwać.
   • Możesz też edytować metadane bezpośrednio w strukturze JSON notesu.

2. W metadanych komórki dodaj atrybut "name":

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

   Na przykład:

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

   Napiwek

   Możesz dodać inne metadane, które chcesz ułatwić śledzenie lokalizacji używanej komórki. Na przykład:

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

Konfigurowanie dostępu do repozytorium

Jeśli plik notesu, do którego chcesz się odwołać, znajduje się w innym repozytorium, skonfiguruj repozytorium kodu jako repozytorium zależne.

Dokumentacja składni fragmentów kodu notesu Jupyter

Gdy notes zawiera wymagane metadane, odwołaj się do niego w pliku markdown. Użyj dodanego <cell-name-value> do notesu i <path> skonfigurowanego jako repozytorium zależne.

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

Na przykład:

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

Ważne

Ta składnia jest blokowym rozszerzeniem Markdown. Musi być używana w osobnym wierszu.

Użyj dowolnego z obsługiwanych języków dla identyfikatora <language> .

Fragmenty kodu interaktywnego

Wbudowane bloki kodu interaktywnego

Fragmenty kodu wykonywalne w oknie przeglądarki można utworzyć w następujących językach:

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

Po włączeniu trybu interakcyjnego pola wygenerowanego kodu mają przycisk Spróbuj lub Uruchom. Na przykład:

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

jest renderowany w następujący sposób:

New-AzResourceGroup -Name myResourceGroup -Location westeurope

And

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

renderuje jako:

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

Aby włączyć tę funkcję dla określonego bloku kodu, użyj specjalnego identyfikatora języka. Dostępne opcje:

• azurepowershell-interactive — włącza program Azure PowerShell Cloud Shell, jak w poprzednim przykładzie
• azurecli-interactive — włącza program Azure Cloud Shell
• csharp-interactive— włącza program C# REPL

W przypadku programów Azure Cloud Shell i Azure PowerShell Cloud Shell użytkownicy mogą uruchamiać polecenia tylko przy użyciu własnego konta Azure.

Fragmenty kodu dołączone przez odwołanie

Dla fragmentów kodu dołączonych przez odwołanie można włączyć tryb interakcyjny. Aby włączyć tę funkcję dla określonego bloku kodu, użyj atrybutu interactive. Dostępne wartości atrybutów to:

• cloudshell-powershell — włącza program Azure PowerShell Cloud Shell, jak w poprzednim przykładzie
• cloudshell-bash — włącza program Azure Cloud Shell
• try-dotnet — włącza narzędzie Try .NET
• try-dotnet-class — włącza narzędzie Try .NET ze szkieletem klas
• try-dotnet-method — włącza narzędzie Try .NET ze szkieletem metod

Oto kilka przykładów:

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

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

W przypadku usług Azure Cloud Shell i Azure PowerShell Cloud Shell użytkownicy mogą uruchamiać polecenia tylko w ramach własnego konta Azure.

W przypadku środowiska .NET Interactive zawartość bloku kodu zależy od wyboru jednego z trzech środowisk tworzenia szkieletów:

• Brak szkieletu (try-dotnet): blok kodu powinien reprezentować pełny tekst programu. Prawidłowy będzie na przykład plik Program.cs wygenerowany przez dotnet new console. Jest to najbardziej przydatne do wyświetlania całego małego programu, w tym potrzebnych dyrektyw using. Instrukcje najwyższego poziomu nie są obecnie obsługiwane.
• Tworzenie szkieletu metody (try-dotnet-method): blok kodu powinien reprezentować zawartość Main metody w aplikacji konsolowej. Można założyć, że dyrektywy using zostaną dodane przez szablon dotnet new console. To ustawienie jest najbardziej przydatne w przypadku krótkich fragmentów, które przedstawiają jedną funkcję.
• Tworzenie szkieletów klas (try-dotnet-class): blok kodu powinien reprezentować klasę Main z metodą jako punktem wejścia programu. Ta opcja może służyć do pokazywania sposobu interakcji elementów członkowskich klasy.

Odwołanie do składni fragmentu kodu

Składnia:

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

Ważne

Ta składnia jest blokowym rozszerzeniem Markdown. Musi być używana w osobnym wierszu.

• <language> (opcjonalnie)

  • Język fragmentu kodu. Aby uzyskać więcej informacji, zobacz sekcję Obsługiwane języki w dalszej części tego artykułu.

• <path> (obowiązkowa)

  • Ścieżka względna w systemie plików wskazująca plik fragmentu kodu, do którego ma zostać utworzone odwołanie.

• <attribute> i <attribute-value> (opcjonalne)

  • Służy razem do określania sposobu pobierania kodu z pliku i sposobu jego wyświetlania:
    • range: 1,3-5 Zakres wierszy. Ten przykład obejmuje wiersze, 1, 3, 4 i 5.
    • id: Create identyfikator fragmentu kodu, który należy wstawić z pliku kodu. Ta wartość nie może współistnieć z zakresem.
    • highlight: 2-4,6 Zakres i/lub liczby wierszy, które muszą zostać wyróżnione w wygenerowanych fragmentach kodu. Numer jest określany względem wyświetlanych wierszy (określonych przez zakres lub identyfikator), a nie względem pliku.
    • interactive: cloudshell-powershell, cloudshell-bash, try-dotnettry-dotnet-class, try-dotnet-method Wartość ciągu określa, jakie rodzaje interakcji są włączone.
    • Aby uzyskać szczegółowe informacje na temat reprezentacji nazwy tagu plikach źródłowych fragmentu kodu według języka, zobacz wytyczne rozwiązania DocFX.

Obsługiwane języki

Pakiet Learn Authoring Pack zawiera funkcję umożliwiającą uzupełnianie instrukcji i walidację dostępnych identyfikatorów języka dla bloków ogrodzenia kodu.

Bloki kodu z ogranicznikami

Nazwisko	Prawidłowe aliasy
Interfejs wiersza polecenia platformy .NET Core	dotnetcli
1C	1c
ABNF	abnf
Dzienniki dostępu	accesslog
Ada	ada
Asembler ARM	armasm, arm
Asembler 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, , nawkgawk
Axapta	axapta
AzCopy	azcopy
Interfejs wiersza polecenia platformy Azure	azurecli
Interfejs wiersza polecenia platformy Azure (interaktywny)	azurecli-interactive
Azure PowerShell	azurepowershell
Azure PowerShell (interaktywny)	azurepowershell-interactive
Bash	bash, , shzsh
Podstawowy	basic
BNF	bnf
C	c
C#	csharp, cs
C# (interaktywny)	csharp-interactive
C++	cpp, c, , cc, 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, , coffee, , csoniced
Crmsh	crmsh, , crmpcmk
Crystal	crystal, cr
Cypher (Neo4j)	cypher
D	d
DAX Power BI	dax
Plik strefy DNS	dns, , zonebind
DOS	dos, , batcmd
Dart	dart
Delphi	delphi, dpr, , dfm, pascalpas, freepascal, , lprlazaruslfm
Diff	diff, patch
Django	django, jinja
Dockerfile	dockerfile, docker
dsconfig	dsconfig
DTS (drzewo urządzenia)	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
Kod HTML	html, xhtml
HTTP	http, https
Haml	haml
Kierownice	handlebars, , hbs, , html.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
Liść	leaf
Lasso	lasso, , lslassoscript
Mniejsze	less
LDIF	ldif
Lisp	lisp
LiveCode Server	livecodeserver
LiveScript	livescript, ls
Lua	lua
Makefile	makefile, , mkmak
Markdown	markdown, , md, , mkdownmkd
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 (interaktywny)	msgraph-interactive
N1QL	n1ql
NSIS	nsis
Nginx	nginx, nginxconf
Nimrod	nimrod, nim
Nix	nix
OCaml	ocaml, ml
Objective C	objectivec, , mm, , objcobj-c
OpenGL Shading Language	glsl
OpenSCAD	openscad, scad
Oracle Rules Language	ruleslanguage
Oxygene	oxygene
PF	pf, pf.conf
PHP	php, , php3, php4, , php5php6
Parser3	parser3
Perl	perl, , plpm
Niewyróżniony zwykły tekst	plaintext
Pony	pony
PostgreSQL i PL/pgSQL	pgsql, , postgrespostgresql
PowerShell	powershell, ps
PowerShell (interaktywny)	powershell-interactive
Przetwarzanie	processing
Prolog	prolog
Właściwości	properties
Bufory protokołu	protobuf
Puppet	puppet, pp
Python	python, , pygyp
Wyniki profilera języka Python	profile
Q#	qsharp
PYTANIA I ODPOWIEDZI	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
Pliki specyfikacji RPM	rpm-specfile, , rpm, spec, , rpm-specspecfile
Ruby	ruby, , rb, gemspec, podspec, , thorirb
Rust	rust, rs
SAS	SAS, sas
SCSS	scss
SQL	sql
STEP Part 21	p21, , stepstp
Scala	scala
Schemat	scheme
Scilab	scilab, sci
Shape Expressions	shexc
Powłoka	shell, console
Smali	smali
Smalltalk	smalltalk, st
Solidity	solidity, sol
Stan	stan
Stata	stata
Tekst strukturalny	iecst, , scl, , stlstructured-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
Kod XML	xml, xhtml, , rss, xjbatom, , xsd, , xslplist
YAML	yml, yaml
Zephir	zephir, zep

Napiwek

Funkcja Learn Authoring Pack , Dev Lang Completion używa pierwszego prawidłowego aliasu, gdy dostępnych jest wiele aliasów.

Następne kroki

Aby uzyskać informacje na temat formatowania tekstu dla typów zawartości innych niż kod, zobacz Wskazówki dotyczące formatowania tekstu.