Udostępnij za pośrednictwem


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.

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:

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

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:

Example showing highlighted code

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:

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.