Zahrnutie kódu do dokumentácie
Existuje niekoľko spôsobov, ako pridať kód do článku publikovaného na lokalite Microsoft Learn aj inými spôsobmi:
Jednotlivé prvky (slová) v rámci riadka.
Tu je príklad štýlu
code
.Formát kódu použite, keď odkazujete na pomenované parametre a premenné v blízkom bloku kódu v texte. Formát kódu možno použiť aj pre vlastnosti, metódy, triedy a kľúčové slová jazyka. Ďalšie informácie nájdete v časti Prvky kódu ďalej v tomto článku.
Bloky kódu v súbore Markdown článku.
```csharp public static void Log(string message) { _logger.LogInformation(message); } ```
Použite bloky vloženého kódu, keď je nepraktické zobraziť kód odkazom na súbor s kódom. Ďalšie informácie nájdete v časti Bloky kódu ďalej v tomto článku.
Bloky kódu odkazom na súbor s kódom v lokálnom odkladacom priestore.
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::
Ďalšie informácie nájdete v časti Odkazy na úryvky v odkladacom priestore ďalej v tomto článku.
Bloky kódu odkazom na súbor s kódom v inom odkladacom priestore.
:::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::
Ďalšie informácie nájdete v časti Odkazy na úryvky mimo odkladacieho priestoru ďalej v tomto článku.
Bloky kódu, ktoré umožňujú používateľovi spustiť kód v prehliadači.
:::code source="PowerShell.ps1" interactive="cloudshell-powershell":::
Ďalšie informácie nájdete v časti Interaktívne úryvky kódu ďalej v tomto článku.
Okrem vysvetľovania jazyka Markdown pre každý z týchto spôsobov zadávania kódu nájdete v článku aj niektoré všeobecné pokyny pre všetky bloky kódu.
Prvok kódu je kľúčové slovo programovacieho jazyka, názov triedy, názov vlastnosti a podobne. Nie je vždy zrejmé, čo sa kvalifikuje ako kód. Za kód by sa napríklad mali považovať názvy balíkov NuGet. Ak máte pochybnosti, pozrite si tému Pokyny na formátovanie textu.
Ak chcete do textu článku zahrnúť prvok kódu, obklopte ho opačnými apostrofmi ('), ktoré označujú štýl kódu. Štýl vloženého kódu by nemal používať formát trojitých opačných apostrofov.
Markdown | Vykreslené |
---|---|
Entity Framework predvolene interpretuje ako primárny kľúč vlastnosť s názvom ID alebo ClassnameID. | Entity Framework predvolene interpretuje ako primárny kľúč vlastnosť s názvom Id alebo ClassnameID . |
Keď je článok lokalizovaný (preložený do iných jazykov), text v štýle kódu ostáva nepreložený. Ak chcete zabrániť lokalizácii bez použitia štýlu kódu, pozrite si tému Nelokalizované reťazce.
Niektoré staršie príručky štýlov špecifikujú tučné písmo pre vložený kód. Tučné písmo sa používa vtedy, keď je štýl kódu taký nenápadný, že to znižuje jeho čitateľnosť. Tabuľka Markdown s väčšinou prvkov kódu môže napríklad vyzerať príliš preplnene, ak v nej všade prevláda štýl kódu. Ak sa rozhodnete použiť tučný štýl a chcete sa uistiť, že kód nie je lokalizovaný, použite syntax nelokalizovaných reťazcov.
Prepojenie na referenčnú dokumentáciu môže byť v niektorých kontextoch užitočnejšie ako formát kódu. Ak použijete prepojenie, nepoužite na text prepojenia formát kódu. Štýl prepojenia ako kódu môže zakryť ten fakt, že text je prepojením.
Ak použijete prepojenie s odkazom na rovnaký prvok neskôr v rovnakom kontexte, následné výskyty naformátujte namiesto prepojení ako kód. Napríklad:
The first reference to <xref:System.CommandLine> in this text is a link.
Subsequent references to `System.CommandLine` can be in code style.
Vykreslené:
Prvý odkaz na System.CommandLine v tomto texte je prepojenie.
Nasledujúce odkazy System.CommandLine
môžu byť v štýle kódu.
Ak chcete, aby používateľ nahradil časť zobrazeného kódu vlastnými hodnotami, použite text zástupného objektu vyznačený lomenými zátvorkami. Napríklad:
az group delete -n <ResourceGroupName>
Môžete si všimnúť, že zátvorky musia byť pri nahrádzaní skutočných hodnôt odstránené. Sprievodca štýlom písania od spoločnosti Microsoft vyžaduje kurzívu, ktorú môžete formátovať v lomenej zátvorke vnoreného kódu:
<ResourceGroupName>
je skupina zdrojov, kde...
Zložené zátvorky { } sa neodporúčajú používať ako syntaktické zástupné symboly. Možno ich zamieňať s rovnakým zápisom, ktorý sa používa v nahraditeľnom texte, reťazcoch formátu, interpolácii reťazca, šablónach textu a podobných programovacích konštrukciách.
Názvy zástupných symbolov môžu byť oddelené spojovníkmi ("prípad kebab"), podčiarknutím alebo vôbec nie oddelené (prípad Pascal). Prípad kebab môže generovať syntaktické chyby a znaky podčiarknutia môžu byť v rozpore so podčiarknutím. Všetky kryty môžu byť v konflikte s pomenovanými konštantami v mnohých jazykoch, ale môžu tiež upriamiť pozornosť na názov zástupného objektu.
<Resource-Group-Name>
alebo<ResourceGroupName>
Syntax na zahrnutie kódu do dokumentu závisí od toho, kde sa kód nachádza:
- V súbore Markdown článku
- V súbore s kódom v tom istom odkladacom priestore
- V súbore s kódom v inom odkladacom priestore
Pozrite si pokyny, ktoré sa vzťahujú na všetky tri typy blokov kódu:
- Screenshoty
- Automatizácia overenia kódu
- Zvýraznenie kľúčových riadkov kódu
- Vyhnite sa vodorovným posúvačom
- Jednoznačne identifikujte zlý kód
Pomocou každej z metód uvedených v predchádzajúcej časti získate použiteľné bloky kódu:
- Môžete ich kopírovať a prilepovať.
- Sú indexované vyhľadávacími nástrojmi.
- Sú prístupné pre čítačky obrazovky.
Toto je len niekoľko z dôvodov, prečo sa snímky obrazovky IDE neodporúčajú ako spôsob zahrnutia kódu do článku. Snímky obrazovky IDE používajte na kód iba vtedy, ak zobrazujete niečo, čoho sa IDE týka, ako napríklad IntelliSense. Nepoužívajte snímky obrazovky len na farebné označovanie a zvýrazňovanie.
Niektoré odkladacie priestory implementovali procesy, ktoré automaticky zhromažďujú všetky vzorové kódy, aby skontrolovali chyby. Platí to aj pre odkladací priestor .NET. Ďalšie informácie nájdete v téme Prispievanie v odkladacom priestore .NET.
Ak zahŕňate bloky kódu z iného odkladacieho priestoru, pracujte s vlastníkmi na stratégii údržby kódu, aby sa zahrnutý kód neprerušil alebo nezastaral, keďže sa dodávajú nové verzie knižníc, ktoré používa kód.
Úryvky zvyčajne obsahujú viac kódu, než je potrebné, aby sa poskytol kontext. Keď kľúčové riadky, na ktoré sa zameriavate v úryvku, zvýrazníte, zlepší sa čitateľnosť, ako je to aj v tomto príklade:
Kód nemôžete zvýrazniť, keď ho zahrniete do súboru Markdown článku. Funguje len v prípade úryvkov kódu zahrnutých v odkaze na súbor s kódom.
Rozdeľte dlhé riadky, aby ste sa vyhli vodorovným posúvačom. Posúvače na blokoch kódu sťažujú čitateľnosť kódu. Problém vzniká najmä pri dlhších blokoch kódu, kde pravdepodobne nie je možné v rovnakom čase zobraziť posúvač a riadok, ktorý chcete prečítať.
Osvedčenou praxou pri minimalizovaní vodorovných posúvačov na blokoch kódu je rozdelenie riadkov kódu dlhších ako 85 znakov. Majte však na pamäti, že prítomnosť alebo neprítomnosť posúvača nie je jediným kritériom čitateľnosti. Ak rozdelenie riadka pred 85. znakom poškodí čitateľnosť alebo možnosť kopírovania a prilepenia, neváhajte a zahrňte viac ako 85 znakov.
V niektorých scenároch je užitočné poukázať na kódovacie vzory, ktorým by sa malo vyhnúť, napríklad:
- Kód, ktorý spôsobí chybu kompilátora pri pokuse.
- Kód, ktorý sa bude kompilovať správne, ale neodporúča sa.
Pre tieto scenáre:
Vysvetlite chybu v komentároch kódu aj v texte článku.
Čitatelia často preskakujú text článku a pozerajú sa len na kód, takže nestačí vysvetliť chybu iba v texte článku. Takisto nestačí vysvetliť chybu iba v komentároch s kódom, pretože komentáre kódu nie sú lokalizované.
Zvážte komentovanie kódu v prípade, že by spôsobil chybu kompilátora.
Komentovaný kód nepreruší nepretržitú integráciu systému CI, ak ho odkladací priestor článku už má alebo ho v budúcnosti implementuje.
Príklad toho, ako prezentovať kód, ktorý sa neodporúča, nájdete v príklade použitia spustenia: zmena písmenového písmena. V tomto príklade by sa mala rada vyhnúť tomu, aby bola dokonca vstavaná do samotného kódu, keďže názov metódy C# je ConvertToUpperBadExample
.
Bloky vloženého kódu použite iba vtedy, keď je nepraktické zobraziť kód odkazom na súbor s kódom. Vložený kód je vo všeobecnosti zložitejší na testovanie a priebežné aktualizovanie v porovnaní so súborom s kódom, ktorý je súčasťou celého projektu. Vo vloženom kóde sa môže vynechať kontext, ktorý by mohol pomôcť vývojárovi s pochopením a použitím tohto kódu. Tieto dôležité informácie sa vzťahujú najmä na programovacie jazyky. Bloky vloženého kódu možno použiť aj v prípade výstupov a vstupov (napríklad JSON), jazykov dotazov (napríklad SQL) a skriptovacích jazykov (napríklad PowerShell).
Existujú dva spôsoby označenia, že časť textu v súbore článku je blok kódu: obhradením pomocou trojitých opačných apostrofov ('') alebo odsadením. Uprednostňuje sa obkolesenie, pretože umožňuje zadať jazyk. Vyhnite sa používaniu odsadenia, pretože môže pomýliť a pre iného autora bude ťažké pochopiť váš zámer, keď bude musieť váš článok upraviť.
Jazykové ukazovatele sa umiestňujú okamžite po úvodných trojitých opačných apostrofoch, ako je to uvedené v tomto príklade:
Markdown:
```json
{
"aggregator": {
"batchSize": 1000,
"flushTimeout": "00:00:30"
}
}
```
Vykreslené:
{
"aggregator": {
"batchSize": 1000,
"flushTimeout": "00:00:30"
}
}
Tip
GitHub Flavored Markdown podporuje bloky kódu s oddeľovačmi pomocou pomôcok (~), ako aj opačné apostrofy ('). Symbol používaný na otvorenie a zatvorenie bloku kódu musí byť konzistentný v rámci toho istého bloku kódu.
Informácie o hodnotách, ktoré môžete použiť ako jazykové ukazovatele, nájdete v téme Názvy a aliasy jazykov.
Ak použijete po trojitých opačných apostrofoch ('''), ktoré nie sú podporované, toto slovo sa zobrazí v záhlaví časti kódu na vykreslenej strane. Vždy, keď je to možné, použite v blokoch vloženého kódu indikátor jazyka alebo prostredia.
Poznámka
Ak skopírujete a prilepíte kód z wordového dokumentu, uistite sa, že neobsahuje žiadne "vlnité úvodzovky", ktoré nie sú platným znakom v kóde. Ak obsahuje, zmeňte ich späť na „priame úvodzovky“ ('
a "
). Prípadne sa môžete spoľahnúť na balík na tvorbu informácií alebo na inteligentnú funkciu nahrádzania úvodzoviek.
Preferovaný spôsob zahrnutia úryvkov kódu pre programovacie jazyky na lokalite Docs je pomocou odkazu na súbor s kódom. Táto metóda vám umožňuje zvýrazniť riadky kódu a rozširuje kontext úryvku, ktorý je k dispozícii na použitie pre vývojárov v GitHube. Kód môžete zahrnúť pomocou formátu trojbodky (:::) manuálne alebo v programe Visual Studio Code s pomocou Balíka na vytváranie informácií.
- V kóde Visual Studia kliknite na kombináciu klávesov Alt + M alebo Option + M a vyberte položku Úryvok kódu.
- Po výbere možnosti Úryvok kódu sa zobrazí výzva na úplné vyhľadávanie, vyhľadávanie v rámci rozsahu alebo odkaz na krížové prehľadávanie odkladacieho priestoru. Ak chcete vyhľadávať lokálne, vyberte položku Úplné vyhľadávanie.
- Ak chcete vyhľadať súbor, zadajte hľadaný výraz. Po vyhľadaní súbor vyberte.
- Potom vyberte možnosť, pomocou ktorej určíte, ktoré riadky kódu sa majú zahrnúť do úryvku. Možnosti sú: ID, Rozsah a Žiaden.
- Na základe vášho výberu v kroku 4 zadajte hodnotu (ak sa vyžaduje).
Zobrazenie celého súboru s kódom:
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs":::
Zobrazenie časti súboru s kódom podľa konkrétnych čísel riadkov:
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::
Zobrazenie časti súboru s kódom podľa konkrétneho názvu úryvku:
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::
V nasledujúcich častiach sú vysvetlené tieto príklady:
- Použitie relatívnej cesty k súboru s kódom
- Zahrnutie iba vybratých čísel riadkov
- Odkaz na pomenovaný úryvok
- Zvýraznenie vybratých riadkov
Ďalšie informácie nájdete v časti Odkaz na syntax úryvku ďalej v tomto článku.
Príklad:
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::
Príklad pochádza z odkladacieho priestoru dokumentov ASP.NET, zo súboru s článkom aspnetcore/data/ef-mvc/crud.md. Na súbor s kódom odkazuje relatívna cesta k umiestneniu aspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs v tom istom odkladacom priestore.
Príklad:
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::
V tomto príklade sa zobrazujú iba riadky 2 – 24 a 26 súboru s kódom StudentController.cs.
Prednostne používajte namiesto naprogramovaných čísel riadkov pomenované úryvky, ako je vysvetlené v ďalšej časti.
Príklad:
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::
V názve používajte iba písmená a znaky podčiarknutia.
V príklade sa zobrazí časť snippet_Create
súboru s kódom. Súbor s kódom pre tento príklad obsahuje značky úryvku v komentároch v kóde jazyka C#:
// code excluded from the snippet
// <snippet_Create>
// code included in the snippet
// </snippet_Create>
// code excluded from the snippet
Pomenované úryvky kódu možno vnoriť, ako je to znázornené v nasledujúcom príklade:
// <Method>
public static void SomeMethod()
{
// <Line>
// Single line of code.
// </Line>
}
// </Method>
Po vykreslení Method
Line
úryvku kódu nie sú značky zahrnuté vo vykreslenom výstupe.
Vždy, keď je to možné, odkazujte na pomenovanú časť namiesto zadávania čísel riadkov. Odkazy na čísla riadkov sú neisté, pretože súbory s kódom sa menia a tieto zmeny ovplyvňujú aj číslovanie riadkov. Na túto zmenu nemusíte byť upozornení. Vo vašom článku sa následne môžu zobrazovať nesprávne riadky a vy netušíte, že došlo ku zmene.
Príklad:
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26" highlight="2,5":::
V príklade sú zvýraznené riadky 2 a 5 počítajúc od začiatku zobrazeného úryvku. Čísla riadkov, ktoré sa majú zvýrazniť, sa nerátajú od začiatku súboru s kódom. Inými slovami, riadky 3 a 6 v súbore s kódom sú zvýraznené.
Ak je súbor s kódom, na ktorý chcete odkazovať, v inom odkladacom priestore, nastavte odkladací priestor kódu ako závislý odkladací priestor. Keď to urobíte, zadajte preň názov. Tento názov potom funguje ako názov priečinka na účely odkazov na kód.
Odkladací priestor Docs je napríklad Azure/azure-docs a odkladací priestor kódu je Azure/azure-functions-durable-extension.
V koreňovom priečinku odkladacieho priestoru azure-docs pridajte nasledujúcu časť v súbore .openpublishing.publish.config.json:
{
"path_to_root": "samples-durable-functions",
"url": "https://github.com/Azure/azure-functions-durable-extension",
"branch": "main",
"branch_mapping": {}
},
Teraz, keď odkazujete na odkladací priestor samples-durable-functions, akoby išlo o priečinok v odkladacom priestore azure-docs, v skutočnosti odkazujete na koreňový priečinok v odkladacom priestore azure-functions-durable-extension.
Kód môžete zahrnúť pomocou formátu trojbodky (:::) manuálne alebo v programe Visual Studio Code s pomocou Balíka na vytváranie informácií.
- V kóde Visual Studia kliknite na kombináciu klávesov Alt + M alebo Option + M a vyberte položku Úryvok kódu.
- Po výbere možnosti Úryvok kódu sa zobrazí výzva na úplné vyhľadávanie, vyhľadávanie v rámci rozsahu alebo odkaz na krížové prehľadávanie odkladacieho priestoru. Ak chcete vyhľadávať v rámci odkladacích priestorov, vyberte odkaz na krížové prehľadávanie odkladacieho priestoru.
- Získate na výber odkladacie priestory, ktoré sú v umiestnení .openpublishing.publish.config.json. Vyberte odkladací priestor.
- Ak chcete vyhľadať súbor, zadajte hľadaný výraz. Po vyhľadaní súbor vyberte.
- Potom vyberte možnosť, pomocou ktorej určíte, ktoré riadky kódu sa majú zahrnúť do úryvku. Možnosti sú: ID, Rozsah a Žiaden.
- Na základe vášho výberu v kroku 5 zadajte hodnotu.
Odkaz na úryvok bude vyzerať takto:
:::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::
V odkladacom priestore azure-functions-durable-extension sa tento kód súboru nachádza v priečinku samples/csx/shared. Ako sme uviedli už skôr, čísla riadkov na zvýraznenie sú relatívne vzhľadom na začiatok úryvku, nie na začiatok súboru.
Poznámka
Názov, ktorý priradíte závislému odkladaciemu priestoru, je relatívny vzhľadom na koreň hlavného odkladacieho priestoru, ale vlnovka (~
) odkazuje na koreň súboru dokumentácie. Koreň množiny dokumentov je určený v .openpublishing.publish.config.json
.build_source_folder
Cesta k úryvku v predchádzajúcom príklade funguje v odkladacom priestore azure-docs, pretože build_source_folder
odkazuje na koreň odkladacieho priestoru (.
). Keby build_source_folder
bol articles
, začiatok cesty by obsahoval ~/../samples-durable-functions
namiesto ~/samples-durable-functions
.
Na bunku môžete odkazovať v notebooku Jupyter ako na úryvok kódu. Ak chcete odkazovať na bunku:
- Pridajte metaúdaje bunky do poznámkového bloku pre bunky, na ktoré chcete odkazovať.
- Nastavte prístup do odkladacieho priestoru.
- V súbore jazyka Markdown použite syntax úryvku poznámkového bloku Jupyter.
Bunku nazvite pridaním metaúdajov buniek do poznámkového bloku jupyteru.
- V Jupyteri môžete upraviť metaúdaje buniek tak, že najprv povolíte panel s nástrojmi bunky: Zobraziť > panel s nástrojmi > bunky Upraviť metaúdaje.
- Keď je povolený panel s nástrojmi buniek, vyberte položku Upraviť metaúdaje v bunke, ktorú chcete pomenovať.
- Metaúdaje môžete upraviť aj priamo v štruktúre JSON poznámkového bloku.
Do metaúdajov bunky pridajte atribút "name":
"metadata": {"name": "<name>"},
Napríklad:
"metadata": {"name": "workspace"},
Tip
Môžete pridať ľubovoľné ďalšie metaúdaje, ktoré vám pomôžu sledovať, kde sa bunka používa. Napríklad:
"metadata": { "name": "workspace", "msdoc": "how-to-track-experiments.md" },
Ak je notebook, na ktorý chcete odkazovať, v inom odkladacom priestore, nastavte odkladací priestor kódu ako závislý odkladací priestor.
Keď poznámkový blok obsahuje požadované metaúdaje, odkazujte naň v súbore markdown. <cell-name-value>
Použite poznámkový blok, ktorý ste pridali do notebooku<path>
, a vlastnosť, ktorú ste nastavili ako závislý odkladací priestor.
[!notebook-<language>[] (<path>/<notebook-name.ipynb>?name=<cell-name-value>)]
Napríklad:
[!notebook-python[] (~/MachineLearningNotebooks/train-on-local.ipynb?name=workspace)]
Dôležité
Táto syntax je blokovým rozšírením v jazyku Markdown. Musí sa použiť v samostatnom riadku.
Pre identifikátor použite ktorýkoľvek z podporovaných <language>
jazykov.
Úryvky kódu môžu byť spustiteľné v okne prehliadača v nasledujúcich jazykoch:
- Azure Cloud Shell
- Azure PowerShell Cloud Shell
- C# REPL
Keď je povolený interaktívny režim, vykreslené polia kódu obsahujú tlačidlo Vyskúšať alebo Spustiť. Napríklad:
```azurepowershell-interactive
New-AzResourceGroup -Name myResourceGroup -Location westeurope
```
Vykreslí sa nasledovne:
New-AzResourceGroup -Name myResourceGroup -Location westeurope
And
```csharp-interactive
var aFriend = "Maria";
Console.WriteLine($"Hello {aFriend}");
```
Sa vykreslí ako:
var aFriend = "Maria";
Console.WriteLine($"Hello {aFriend}");
Ak chcete zapnúť túto funkciu pre konkrétny blok kódu, použite špeciálny identifikátor jazyka. K dispozícii sú tieto možnosti:
azurepowershell-interactive
– povolí použitie služby Azure PowerShell Cloud Shell ako v predchádzajúcom príkladeazurecli-interactive
– povolí použitie služby Azure Cloud Shellcsharp-interactive
– povolí použitie služby C# REPL
V prípade služieb Azure Cloud Shell a PowerShell Cloud Shell môžu používatelia spúšťať príkazy len použitím svojho vlastného konta Azure.
Interaktívny režim môžete povoliť pre úryvky kódu zahrnuté v odkaze.
Ak chcete zapnúť túto funkciu pre konkrétny blok kódu, použite atribút interactive
. Dostupné hodnoty atribútov sú:
cloudshell-powershell
– povolí použitie služby Azure PowerShell Cloud Shell ako v predchádzajúcom príkladecloudshell-bash
– povolí použitie služby Azure Cloud Shelltry-dotnet
– povolí službu Try .NETtry-dotnet-class
– povolí službu Try .NET s podpornou triedoutry-dotnet-method
– povolí službu Try .NET s podpornou metódou
Tu sú niektoré príklady:
:::code source="PowerShell.ps1" interactive="cloudshell-powershell":::
:::code source="Bash.sh" interactive="cloudshell-bash":::
V prípade služieb Azure Cloud Shell a PowerShell Cloud Shell môžu používatelia spúšťať príkazy len použitím svojho vlastného konta Azure.
Pre funkciu .NET Interactive závisí obsah vášho bloku kódov na tom, ktorú z troch podporných funkcií si vyberiete:
- Bez podpory (
try-dotnet
): Blok kódov by mal predstavovať úplný text programu. Napríklad súbor Program.cs vytvorený šablónoudotnet new console
bude platný. Táto možnosť je najvhodnejšia v prípade, ak chcete zobraziť celý malý program vrátane direktív typuusing
, ktoré sú potrebné. Príkazy na najvyššej úrovni nie sú momentálne podporované. - Podporná metóda (
try-dotnet-method
): Blok kódov by mal reprezentovať obsahMain
metódy v konzolovej aplikácii. Môžete odhadnúť direktívy typuusing
pridané šablónoudotnet new console
. Toto nastavenie je vhodné použiť pre krátke úryvky kódu, ktoré demonštrujú jedinú funkciu. - Podporná trieda (
try-dotnet-class
): Blok kódov by mal reprezentovať triedu s metódou , ktorá saMain
používa ako vstupný bod programu. Táto možnosť sa používa na zobrazenie členov interakcie medzi triedami.
Syntax:
:::code language="<language>" source="<path>" <attribute>="<attribute-value>":::
Dôležité
Táto syntax je blokovým rozšírením v jazyku Markdown. Musí sa použiť v samostatnom riadku.
<language>
(voliteľné)- Jazyk úryvku kódu Ďalšie informácie nájdete v časti Podporované jazyky v tomto článku.
<path>
(povinné)- Relatívna cesta v súborovom systéme, ktorá označuje súbor s úryvkom kódu, na ktorý sa bude odkazovať.
<attribute>
a<attribute-value>
(voliteľné)- Používa sa na špecifikovanie spôsobu načítania kódu zo súboru a jeho zobrazenia:
range
:1,3-5
Rozsah riadkov. Tento príklad zahrňuje riadky 1, 3, 4 a 5.id
:Create
ID úryvku, ktorý sa má vložiť zo súboru s kódom. Táto hodnota nemôže existovať súčasne s rozsahom.highlight
:2-4,6
Rozsah a/alebo počet riadkov, ktoré je potrebné zvýrazniť vo vygenerovanom úryvku kódu. Číslovanie je relatívne vzhľadom na zobrazené riadky (podľa zadaného rozsahu alebo ID), nie na súbor.interactive
:cloudshell-powershell
,cloudshell-bash
,try-dotnet
,try-dotnet-class
,try-dotnet-method
Hodnota reťazca určuje povolené typy interaktivity.- Podrobnosti o reprezentácii názvu značky v zdrojových súboroch úryvku kódu podľa jazyka nájdete v téme Usmernenia pre DocFX.
- Používa sa na špecifikovanie spôsobu načítania kódu zo súboru a jeho zobrazenia:
Balík na tvorbu informácií obsahuje funkciu na poskytovanie dokončovania v príkazoch a overenia dostupných identifikátorov jazyka pre bloky obhradenia kódu.
Názov | Platné aliasy |
---|---|
.NET Core CLI | dotnetcli |
1C | 1c |
ABNF | abnf |
Denníky prístupu | accesslog |
Ada | ada |
Zostavovač ARM | armasm , arm |
Zostavovač AVR | avrasm |
ActionScript | actionscript , as |
Adam | 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 , nawk , gawk |
Axapta | axapta |
AzCopy | azcopy |
Azure CLI | azurecli |
Azure CLI (Interactive) | azurecli-interactive |
Azure PowerShell | azurepowershell |
Azure Powershell (Interactive) | azurepowershell-interactive |
Bash | bash , sh , zsh |
Základná | basic |
BNF | bnf |
C | c |
C# | csharp , cs |
C# (Interactive) | csharp-interactive |
C++ | cpp , c , cc , h , c++ , h++ , , hpp |
C++/CX | cppcx |
C++/WinRT | cppwinrt |
C/AL | cal |
Skript objektu vyrovnávacej pamäte | cos , cls |
CMake | cmake , cmake.in |
Coq | coq |
CSP | csp |
CSS | css |
Cap'n Proto | capnproto , capnp |
Clojure | clojure , clj |
CoffeeScript | coffeescript , coffee , cson , iced |
Crmsh | crmsh , crm , pcmk |
Crystal | crystal , cr |
Cypher (Neo4j) | cypher |
D | d |
DAX Power BI | dax |
Súbor zóny DNS | dns , zone , bind |
DOS | dos , bat , cmd |
Dart | dart |
Delphi | delphi , dpr , dfm , pas , pascal , freepascal , lazarus , , lpr , lfm |
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 , xls , xlsx |
Extempore | extempore , xtlang , xtm |
F# | fsharp , fs |
FIX | fix |
Fortran | fortran , f90 , f95 |
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 |
Riadidlá | handlebars , hbs , html.hbs , html.handlebars |
Haskell | haskell , hs |
Haxe | haxe , hx |
Hy | hy , hylang |
Ini | ini |
Inform7 | inform7 , i7 |
IRPF90 | irpf90 |
JSON | json |
Java | java , jsp |
JavaScript | javascript , js , jsx |
Kotlin | kotlin , kt |
Kusto | kusto |
Leaf | leaf |
Lasso | lasso , ls , lassoscript |
Less | less |
LDIF | ldif |
Lisp | lisp |
LiveCode Server | livecodeserver |
LiveScript | livescript , ls |
Lua | lua |
Makefile | makefile , mk , mak |
Markdown | markdown , md , mkdown , mkd |
Mathematica | mathematica , mma , wl |
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 , mm , objc , obj-c |
OpenGL Shading Language | glsl |
OpenSCAD | openscad , scad |
Oracle Rules Language | ruleslanguage |
Oxygene | oxygene |
PF | pf , pf.conf |
PHP | php , php3 , php4 , php5 , php6 |
Parser3 | parser3 |
Perl | perl , pl , pm |
Plaintext no highlight | plaintext |
Pony | pony |
PostgreSQL & PL/pgSQL | pgsql , postgres , postgresql |
PowerShell | powershell , ps |
PowerShell (Interactive) | powershell-interactive |
Prebieha spracovanie | processing |
Prolog | prolog |
Vlastnosti | properties |
Protocol Buffers | protobuf |
Puppet | puppet , pp |
Python | python , py , gyp |
Výsledky profilovača jazyka Python | profile |
Q# | qsharp |
Q | k , kdb |
QML | qml |
R | r |
Razor CSHTML | cshtml , razor , razor-cshtml |
ReasonML | reasonml , re |
RenderMan RIB | rib |
RenderMan RSL | rsl |
Roboconf | graph , instances |
Robot Framework | robot , rf |
Súbory špecifikácií RPM | rpm-specfile , rpm , spec , rpm-spec , specfile |
Ruby | ruby , rb , gemspec , podspec , thor , irb |
Rust | rust , rs |
SAS | SAS , sas |
SCSS | scss |
SQL | sql |
STEP Part 21 | p21 , step , stp |
Scala | scala |
Schéma | scheme |
Scilab | scilab , sci |
Shape Expressions | shexc |
Prostredie | shell , console |
Smali | smali |
Smalltalk | smalltalk , st |
Solidity | solidity , sol |
Stan | stan |
Stata | stata |
Štruktúrovaný text | iecst , scl , stl , structured-text |
Stylus | stylus , styl |
SubUnit | subunit |
Supercollider | supercollider , sc |
Swift | swift |
Tcl | tcl , tk |
Terraform (HCL) | terraform , tf , hcl |
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 |
Skript Vim | vim |
Visual Basic | vb |
Visual Basic for Applications | vba |
X++ | xpp |
Zostava x86 | x86asm |
XL | xl , tao |
XQuery | xquery , xpath , xq |
XAML | xaml |
XML | xml , xhtml , rss , atom , xjb , xsd , xsl , , plist |
YAML | yml , yaml |
Zephir | zephir , zep |
Tip
Balík na tvorbu informácií, funkcia Dev Lang Completion používa prvý platný alias, keď sú k dispozícii viaceré aliasy.
Informácie o formátovaní textu pre iné typy obsahu ako kód nájdete v téme Pokyny na formátovanie textu.