Koodin sisällyttäminen dokumentaatioon
Koodin voi sisällyttää Microsoft Learnissa julkaistuun artikkeliin useilla muilla tavoilla kuin näyttökuvilla :
Erilliset elementit (sanat) samalla rivillä
Tässä on esimerkki
code
-tyylistä.Käytä koodimuotoa viitatessasi nimettyihin parametreihin ja muuttujiin läheisessä koodilohkossa tekstissäsi. Koodimuotoa voidaan käyttää myös ominaisuuksien, menetelmien, luokkien ja kielen avainsanojen kohdalla. Lisätietoja on tämän artikkelin kohdassa Koodielementit.
Koodilohkot artikkelin Markdown-tiedostossa
```csharp public static void Log(string message) { _logger.LogInformation(message); } ```
Käytä sisäisiä koodilohkoja, kun koodin näyttäminen on hankalaa kooditiedostoon viittaamalla. Lisätietoja on tämän artikkelin kohdassa Koodilohkot.
Koodilohkot viittauksella paikallisessa säilössä olevaan kooditiedostoon
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::
Lisätietoja on tämän artikkelin kohdassa Säilön sisäiset koodikatkelmien viittaukset.
Koodilohkot viittauksella toisessa säilössä olevaan kooditiedostoon
:::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::
Lisätietoja on tämän artikkelin kohdassa Säilön ulkopuoliset koodikatkelmien viittaukset.
Koodilohkot, joiden avulla käyttäjä voi suorittaa koodia selaimessa
:::code source="PowerShell.ps1" interactive="cloudshell-powershell":::
Lisätietoja on tämän artikkelin kohdassa Vuorovaikutteiset koodikatkelmat.
Artikkelissa kerrotaan kunkin koodin lisäämistavan Markdown-menetelmästä sekä annetaan yleisiä ohjeita kaikille koodilohkoille.
Koodielementit ovat esimerkiksi ohjelmointikielen avainsanoja sekä luokkien ja ominaisuuksien nimiä. Koodin määritelmä ei ole aina ilmeinen. Esimerkiksi NuGet-pakettien nimiä tulee käsitellä koodina. Jos et ole asiasta varma, katso ohjeaihe Tekstin muotoiluohjeet.
Jos haluat sisällyttää koodielementin artikkelin tekstiin, ympäröi se asetuksilla ('), jotka ilmaisevat koodityyliä. Älä käytä sisäisen koodin tyylissä kolminkertaisia gravis-merkkejä.
Merkintä | Hahmonnettu |
---|---|
Entity Framework tulkitsee oletusarvoisesti Id- tai ClassnameID-nimisen ominaisuuden perusavaimeksi. | Entity Framework tulkitsee oletusarvoisesti Id - tai ClassnameID -nimisen ominaisuuden perusavaimeksi. |
Kun artikkeli lokalisoidaan (käännetään muille kielille), koodityylinen teksti jätetään kääntämättä. Jos haluat estää lokalisoinnin koodityyliä käyttämättä, lisätietoja on ohjeaiheessa Lokalisoimattomat merkkijonot.
Joissakin vanhemmissa tyylioppaissa määritetään lihavointi sisäisen koodin tyyliksi. Lihavointi on vaihtoehtona, jos koodityyli heikentäisi luettavuutta. Esimerkiksi enimmäkseen koodielementtejä sisältävää Markdown-taulukkoa voi olla vaikea lukea, jos siinä on käytetty paljon koodityyliä. Jos valitset lihavoidun tyylin, käytä lokalisoimattomien merkkijonojen syntaksia varmistaaksesi, että koodia ei lokalisoida.
Linkki viitedokumentaatioon voi olla joissakin konteksteissa koodimuotoa hyödyllisempi. Jos käytät linkkiä, älä käytä linkin tekstissä koodimuotoa. Tekstiä ei välttämättä mielletä linkiksi, jos se muotoillaan koodina.
Jos käytät linkkiä ja viittaat samaan elementtiin myöhemmin samassa asiayhteydessä, muotoile seuraavat esiintymät koodimuodolla linkkien sijaan. Esimerkkejä:
The first reference to <xref:System.CommandLine> in this text is a link.
Subsequent references to `System.CommandLine` can be in code style.
Hahmonnettu:
Ensimmäinen viittaus System.CommandLine tähän tekstiin on linkki.
Seuraavat viittaukset kohteeseen System.CommandLine
voivat olla koodityylisiä.
Jos haluat, että käyttäjä korvaa osan näytettävästä koodista omilla arvoillaan, käytä kulmasulkeilla merkittyä paikkamerkkitekstiä. Esimerkkejä:
az group delete -n <ResourceGroupName>
Saatat huomata, että hakasulkeet on poistettava, kun koodi korvataan reaaliarvoilla. Microsoft Writing Style Guide vaatii kursivointia, joita voit muotoilla kulmasulkeen sisäiseen koodiin:
<ResourceGroupName>
on resurssiryhmä, jossa...
Aaltosulkeita { } ei suositella käytettäväksi syntaktisina paikkamerkkeinä. Ne voidaan sekoittaa samaan merkintätapaan, jota käytetään korvattavassa tekstissä, muotoilumerkkijonossa, merkkijonon interpoloinnissa, tekstimalleissa ja vastaavissa ohjelmointirakenteissa.
Paikkamerkkien nimet voidaan erottaa yhdysmerkeillä ("kebab-kirjainkoko"), joiden alaviivat ovat tai joita ei voi erottaa lainkaan (Pascal-kirjainkoko). Kebab-tapaus voi luoda syntaksivirheitä ja alaviivoja, jotka saattavat olla ristiriidassa alleviivauksen kanssa. Kaikki enimmäisarvot saattavat olla ristiriidassa nimettyjen vakioiden kanssa monilla kielillä, mutta se voi myös kiinnittää huomiota paikkamerkin nimeen.
<Resource-Group-Name>
tai<ResourceGroupName>
Syntaksi koodin sisällyttämiselle asiakirjaan määräytyy sen mukaan, missä koodi sijaitsee:
- Artikkelin Markdown-tiedostossa
- Samassa säilössä olevassa kooditiedostossa
- Eri säilössä olevassa kooditiedostossa
Seuraavat ohjeet koskevat kaikkia kolmea koodilohkotyyppiä:
- Kuvakaappauksia
- Koodin vahvistuksen automatisoiminen
- Korosta koodin avainrivit
- Vältä vaakasuuntaisia vierityspalkkeja
- Tunnista selvästi virheellinen koodi
Kaikkien edellisessä osiossa lueteltujen menetelmien tuloksena ovat käyttökelpoiset koodilohkot:
- Kopiointi ja liittäminen on mahdollista koodilohkoista.
- Koodilohkot ovat hakukoneiden indeksoimia.
- Koodilohkot ovat näytönlukuohjelmien käytettävissä.
Tässä on kerrottu vain muutamia syitä siihen, miksi IDE-näyttökuvia ei suositella menetelmäksi koodin sisällyttämiselle artikkeliin. Käytä IDE-näyttökuvia koodia varten vain, jos haluat näyttää jotakin itse IDE-kohteesta, esimerkiksi IntelliSensestä. Älä käytä näyttökuvia vain värien ja korostuksen näyttämiseen.
Jotkin säilöt ovat ottaneet käyttöön prosesseja, jotka kääntävät automaattisesti kaikki mallikoodit virheiden tarkistusta varten. .NET-säilö tekee näin. Lisätietoja on kohdassa Osallistuminen .NET-säilössä.
Jos sisällytät koodilohkoja toisesta säilöstä, tee yhteistyötä omistajien kanssa koodin ylläpitostrategian suhteen, jotta sisällytetty koodi ei katkea tai vanhene, kun uudet versiot koodin käyttämistä kirjastoista toimitetaan.
Katkelmissa on yleensä enemmän koodia, kuin mikä on tarpeen kontekstin antamiseksi. Koodikatkelman tärkeimpien rivien korostaminen helpottaa luettavuutta seuraavassa esimerkissä esitetyllä tavalla:
Et voi korostaa koodia, kun sisällytät sen artikkelin Markdown-tiedostoon. Se toimii vain koodikatkelmissa, jotka on sisällytetty viittauksella kooditiedostoon.
Vältä vaakasuuntaisia vierityspalkkeja katkaisemalla pitkiä rivejä. Koodilohkojen vierityspalkit tekevät koodin lukemisesta vaikeaa. Ne ovat erityisen ongelmallisia pidemmissä koodilohkoissa, joissa vierityspalkin ja luettavan rivin näkeminen samaan aikaan voi olla mahdotonta.
Hyvänä käytäntönä koodilohkojen vaakasuuntaisten vierityspalkkien vähentämisessä on katkaista yli 85 merkkiä pitkät koodirivit. Muista kuitenkin, että vierityspalkki ei ole ainoa asia, joka vaikuttaa luettavuuteen. Jos rivin katkaiseminen ennen 85 merkkiä haittaa luettavuutta tai kopiointia ja liittämistä, koodirivi voi hyvin olla yli 85-merkkinen.
Joissakin tilanteissa on hyödyllistä huomauttaa koodausmalleista, joita tulisi välttää, esimerkiksi:
- Koodi, joka aiheuttaa kääntäjävirheen, jos sitä yritetään.
- Koodi, joka kääntyy oikein, mutta jota ei suositella.
Näitä skenaarioita varten:
Selitä virhe sekä koodin kommenteissa että artikkelin tekstissä.
Lukijat ohittavat usein artikkelin tekstin ja tarkastelevat vain koodia, joten ei riitä, että se selittää virheen vain artikkelin tekstissä. Virheen selittäminen ei myöskään riitä vain koodikommentteihin, koska koodikommentteja ei lokalisoida.
Harkitse koodin kommentointia, jos se aiheuttaa kääntäjävirheen.
Kommentoitu koodi ei häiritse jatkuvaa integrointia (CI), jos artikkelin säilössä on sellainen nyt tai se toteuttaa sellaisen tulevaisuudessa.
Jos haluat esimerkin sellaisen koodin esittämisestä, jota ei suositella, katso Suorita käyttöesimerkki: kirjainkoon muuttaminen. Tässä esimerkissä neuvot välttämään sitä sisältyy jopa itse koodiin, kuten C#-menetelmän nimi on ConvertToUpperBadExample
.
Käytä sisäisiä koodilohkoja vain, kun koodin näyttäminen on hankalaa kooditiedostoon viittaamalla. Sisäistä koodia on yleensä vaikeampi testata ja pitää ajan tasalla verrattuna kooditiedostoon, joka on osa täydellistä projektia. Sisäinen koodi saattaa ohittaa kontekstin, joka auttaa kehittäjää ymmärtämään ja käyttämään koodia. Nämä seikat koskevat lähinnä ohjelmointikieliä. Sisäisiä koodilohkoja voidaan käyttää myös tuloksissa ja syötteissä (kuten JSON), kyselykielissä (kuten SQL) ja komentosarjakielissä (kuten PowerShell).
Artikkelitiedoston tekstiosion voi määrittää koodilohkoksi kahdella tavalla: aitaamalla sen kolminkertaisten grastikoiden ('') tai sisentämällä sen. Aitaaminen on suositeltava tapa, koska sen avulla voit määrittää kielen. Vältä sisentämistä, koska se on helppo ymmärtää väärin, ja lisäksi toisen kirjoittajan voi olla vaikea ymmärtää tarkoitustasi, kun hän haluaa muokata artikkelia.
Kieli-ilmaisimet sijoitetaan heti avaavien kolminkertaisten gravit-merkkien jälkeen, kuten seuraavassa esimerkissä:
Markdown:
```json
{
"aggregator": {
"batchSize": 1000,
"flushTimeout": "00:00:30"
}
}
```
Hahmonnettu:
{
"aggregator": {
"batchSize": 1000,
"flushTimeout": "00:00:30"
}
}
Vihje
GitHub Flavored Markdown tukee koodilohkojen erotinta aaltovihjeillä (~) ja aksenttimerkeillä ('). Koodilohkon avaamiseen ja sulkemiseen käytettävän symbolin on oltava johdonmukainen samassa koodilohkossa.
Jos haluat lisätietoja arvoista, joita voit käyttää kieli-ilmaisimina, katso ohjeaihe Kielten nimet ja aliakset.
Jos käytät kolminkertaisten gravististen ('') jälkeen kielen tai ympäristön sanaa, jota ei tueta, kyseinen sana näkyy hahmonnetun sivun koodiosan otsikkorivillä. Käytä sisäisissä koodilohkoissa kieli- tai ympäristöilmaisinta aina kun mahdollista.
Huomautus
Jos kopioit ja liität koodia Word-asiakirjasta, varmista, että siinä ei ole "kaarevia lainausmerkkejä", jotka eivät ole kelvollisia koodissa. Jos koodi sisältää niitä, muuta ne takaisin normaaleiksi lainausmerkeiksi ('
ja "
). Vaihtoehtoisesti voit luottaa Learn Authoring Packin älykkäiden lainausmerkkien korvaustoimintoon.
Suositeltavin tapa sisällyttää koodikatkelmia ohjelmointikieliin asiakirjoissa on viittaaminen kooditiedostoon. Tämän menetelmän avulla voit korostaa koodirivejä, ja siten koodikatkelman laajempi konteksti on kehittäjien käytettävissä GitHubissa. Voit sisällyttää koodin käyttämällä kolminkertaista kaksoispistemuotoa (:::) joko manuaalisesti tai Visual Studio Codessa Learn Authoring Packin avulla.
- Valitse Visual Studio Codessa Alt + M tai Optio + M ja valitse Snippet (Katkelma).
- Kun katkelma on valittuna, näet valinnat Full Search (Täysi haku), Scoped Search (Aluehaku) ja Cross-Repository Reference (Säilöjen välinen viittaus). Voit hakea paikallisesti valitsemalla Täysi haku.
- Etsi tiedosto kirjoittamalla hakusana. Kun olet löytänyt tiedoston, valitse se.
- Valitse seuraavaksi vaihtoehto, joka määrittää, mitkä koodirivit katkelmaan sisällytetään. Vaihtoehdot ovat: ID (tunnus) ja Range (alue) ja None (ei mitään).
- Anna arvo tarvittaessa sen mukaan, mitä valitsit vaiheessa 4.
Näytä koko kooditiedosto:
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs":::
Näytä kooditiedoston osa määrittämällä rivinumerot:
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::
Näytä kooditiedoston osa määrittämällä koodikatkelman nimi:
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::
Seuraavissa osioissa selitetään nämä esimerkit:
- Käytä suhteellista polkua kooditiedostoon
- Sisällytä vain valitut rivinumerot
- Viittaa nimettyyn katkelmaan
- Korosta valitut rivit
Lisätietoja on tämän artikkelin kohdassa Katkelman syntaksiviittaus.
Esimerkki:
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::
Esimerkki on ASP.NET Docs-säilöstä, artikkelitiedostosta aspnetcore/data/ef-mvc/crud.md. Kooditiedostoon viitataan suhteellisella polulla aspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs samassa säilössä.
Esimerkki:
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::
Tässä esimerkissä näytetään vain rivit 2–24 ja 26 StudentController.cs-kooditiedostosta.
Käytä mieluummin nimettyjä katkelmia kuin pysyväiskoodattuja rivinumeroita, kuten seuraavassa osiossa selitetään.
Esimerkki:
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::
Käytä nimessä vain kirjaimia ja alaviivoja.
Esimerkissä näkyy kooditiedoston osa snippet_Create
. Tämän esimerkin kooditiedostossa on katkelmatunnisteita C#-koodin kommenteissa:
// code excluded from the snippet
// <snippet_Create>
// code included in the snippet
// </snippet_Create>
// code excluded from the snippet
Nimetyt koodikatkelmat voidaan sijoittaa sisäkkäin seuraavassa esimerkissä esitetyllä tavalla:
// <Method>
public static void SomeMethod()
{
// <Line>
// Single line of code.
// </Line>
}
// </Method>
Method
Kun koodikatkelma hahmonnetaan, Line
tunnisteet eivät sisälly hahmonnettuun tulosteeseen.
Aina kun mahdollista, viittaa nimettyyn osaan sen sijaan, että määrittäisit rivinumerot. Rivinumeroviittaukset eivät ole pysyviä, koska kooditiedostot muuttuvat ennemmin tai myöhemmin siten, että rivinumerot vaihtuvat. Et välttämättä saa ilmoitusta tällaisista muutoksista. Tällöin artikkelissasi näkyy väärät rivit, eikä sinulla ole aavistustakaan siitä, että jokin on muuttunut.
Esimerkki:
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26" highlight="2,5":::
Esimerkki korostaa rivit 2 ja 5 laskien näytettävän katkelman alusta. Korostettavia rivinumeroita ei lasketa kooditiedoston alusta. Toisin sanoen kooditiedoston rivit 3 ja 6 korostetaan.
Jos viitattava kooditiedosto sijaitsee eri säilössä, määritä koodisäilö riippuvaisena säilönä. Kun teet niin, sille määritetään nimi. Kyseinen nimi toimii kansion nimen kaltaisesti koodiviittauksissa.
Esimerkiksi asiakirjasäilö on Azure/azure-docs, ja koodisäilö on Azure/azure-functions-durable-extension.
Lisää azure-docs-säilön pääkansioon seuraava osio kohtaan .openpublishing.publish.config.json:
{
"path_to_root": "samples-durable-functions",
"url": "https://github.com/Azure/azure-functions-durable-extension",
"branch": "main",
"branch_mapping": {}
},
Kun nyt viittaat kohtaan samples-durable-functions azure-docsin kansion tavoin, viittaat itse asiassa azure-functions-durable-extension-säilön pääkansioon.
Voit sisällyttää koodin käyttämällä kolminkertaista kaksoispistemuotoa (:::) joko manuaalisesti tai Visual Studio Codessa Learn Authoring Packin avulla.
- Valitse Visual Studio Codessa Alt + M tai Optio + M ja valitse Snippet (Katkelma).
- Kun katkelma on valittuna, näet valinnat Full Search (Täysi haku), Scoped Search (Aluehaku) ja Cross-Repository Reference (Säilöjen välinen viittaus). Jos haluat hakea useasta säilöstä, valitse Cross-Repository Reference (Säilöjen välinen viittaus).
- Saat valikoiman säilöistä, jotka ovat kohteessa .openpublishing.publish.config.json. Valitse säilö.
- Etsi tiedosto kirjoittamalla hakusana. Kun olet löytänyt tiedoston, valitse se.
- Valitse seuraavaksi vaihtoehto, joka määrittää, mitkä koodirivit katkelmaan sisällytetään. Vaihtoehdot ovat: ID (tunnus) ja Range (alue) ja None (ei mitään).
- Anna arvo sen mukaan, mitä valitsit vaiheessa 5.
Katkelmaviittauksesi näyttää tältä:
:::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::
azure-functions-durable-extension-säilössä kooditiedosto sijaitsee samples/csx/shared-kansiossa. Kuten edellä mainittiin, korostuksen rivinumerot ovat suhteessa katkelman alkuun tiedoston alun sijaan.
Huomautus
Riippuvaiseen säilöön määrittämäsi nimi on suhteessa pääsäilön pääkansioon, mutta tilde (~
) viittaa asiakirjajoukon pääkansioon. Docset-pääkansion määrittää build_source_folder
in .openpublishing.publish.config.json
. Edellisessä esimerkissä oleva katkelman polku toimii azure-docs-säilössä, koska build_source_folder
viittaa säilön pääkansioon (.
). Jos build_source_folder
olisi articles
, polun alku olisi ~/../samples-durable-functions
, ei ~/samples-durable-functions
.
Voit viitata Jupyter-muistikirjassa olevan solun koodikatkelmana. Soluun viittaaminen:
- Lisää muistikirjaan solun metatiedot soluille, joihin haluat viitata.
- Määritä säilön käyttöoikeus.
- Käytä Jupyter-muistikirjan katkelman syntaksia markdown-tiedostossasi.
Nimeä solu lisäämällä solun metatietoja Jupyter-muistikirjaan.
- Jupyterissa voit muokata solujen metatietoja ottamalla ensin käyttöön solun työkalurivin: Näytä > solun työkalurivi > Muokkaa metatietoja.
- Kun solun työkalurivi on käytössä, valitse muokkaa metatietoja solussa, jonka haluat nimetä.
- Voit myös muokata metatietoja suoraan muistikirjan JSON-rakenteessa.
Lisää solun metatietoihin "name"-määrite:
"metadata": {"name": "<name>"},
Esimerkkejä:
"metadata": {"name": "workspace"},
Vihje
Voit lisätä muita metatietoja, joiden avulla voit seurata, missä solua käytetään. Esimerkkejä:
"metadata": { "name": "workspace", "msdoc": "how-to-track-experiments.md" },
Jos muistikirjatiedosto, johon haluat viitata, on eri säilössä, määritä koodisäilö riippuvaisena säilönä.
Kun muistikirja sisältää tarvittavat metatiedot, viittaa siihen Markdown-tiedostossasi. <cell-name-value>
Käytä muistikirjaan lisäämääsi muistikirjaa ja <path>
määrität sen riippuvaiseksi säilöksi.
[!notebook-<language>[] (<path>/<notebook-name.ipynb>?name=<cell-name-value>)]
Esimerkkejä:
[!notebook-python[] (~/MachineLearningNotebooks/train-on-local.ipynb?name=workspace)]
Tärkeä
Tämä syntaksi on Markdown-lohkolaajennus. Sitä on käytettävä omalla rivillään.
Käytä tunnisteessa mitä tahansa tuetuista kielistä<language>
.
Koodikatkelmista voidaan tehdä suoritettavia tiedostoja selainikkunassa seuraavilla kielillä:
- Azure Cloud Shell
- Azure PowerShell Cloud Shell
- C# REPL
Kun vuorovaikutteinen tila on käytössä, hahmonnetun koodin ruuduissa on Kokeile- tai Suorita-painikkeet. Esimerkkejä:
```azurepowershell-interactive
New-AzResourceGroup -Name myResourceGroup -Location westeurope
```
hahmontuu seuraavasti:
New-AzResourceGroup -Name myResourceGroup -Location westeurope
And
```csharp-interactive
var aFriend = "Maria";
Console.WriteLine($"Hello {aFriend}");
```
hahmonuu seuraavasti:
var aFriend = "Maria";
Console.WriteLine($"Hello {aFriend}");
Jos haluat ottaa tämän ominaisuuden käyttöön tietyssä koodilohkossa, käytä erityistä kielitunnistetta. Käytettävissä olevat vaihtoehdot:
azurepowershell-interactive
– ottaa käyttöön Azure PowerShell Cloud Shell -palvelun, kuten edellisessä esimerkissäazurecli-interactive
– ottaa käyttöön Azure Cloud Shell -palveluncsharp-interactive
-ottaa käyttöön C# REPL -palvelun
Azure Cloud Shell- ja PowerShell Cloud Shell -palveluiden tapauksessa käyttäjät voivat suorittaa komentoja vain omalla Azure-tilillään.
Voit ottaa vuorovaikutteisen tilan käyttöön koodikatkelmille, jotka on sisällytetty viittauksella.
Jos haluat ottaa tämän ominaisuuden käyttöön tietyssä koodilohkossa, käytä määritettä interactive
. Käytettävissä olevat määritearvot ovat:
cloudshell-powershell
– ottaa käyttöön Azure PowerShell Cloud Shell -palvelun, kuten edellisessä esimerkissäcloudshell-bash
– ottaa käyttöön Azure Cloud Shell -palveluntry-dotnet
-Ottaa käyttöön Try .NET -palveluntry-dotnet-class
-Ottaa käyttöön Try .NET -palvelun ja luokkarakenteentry-dotnet-method
– ottaa käyttöön Try .NET -palvelun ja menetelmärakenteen
Seuraavassa on muutamia esimerkkejä:
:::code source="PowerShell.ps1" interactive="cloudshell-powershell":::
:::code source="Bash.sh" interactive="cloudshell-bash":::
Azure Cloud Shell- ja PowerShell Cloud Shell -palveluiden tapauksessa käyttäjät voivat suorittaa komentoja vain omalla Azure-tilillään.
.NET Interactive -kokemuksessa koodilohkon sisältö riippuu siitä, minkä kolmesta rakennekokemuksesta valitset:
- Ei rakennetta (
try-dotnet
): Koodilohkon tulisi edustaa koko ohjelman tekstiä. Esimerkiksi Program.cs -tiedosto, jonka on luonutdotnet new console
, on täysin kelvollinen. Ne ovat erityisen hyödyllisiä näyttämään koko pienen ohjelman mukaan lukien tarvittaessausing
-ohjeet. Tässä vaiheessa ylätason lausekkeita ei tueta. - Menetelmärakenne (
try-dotnet-method
): Koodilohkon tulisi edustaa menetelmänMain
sisältöä konsolisovelluksessa. Voit omaksuausing
-direktiivit, jotkadotnet new console
-malli on lisännyt. Tämä asetus on hyödyllisin lyhyille katkelmille, joissa on yksi ominaisuus. - Luokkarakenne (
try-dotnet-class
): Koodilohkon tulisi edustaa luokkaa, jossa menetelmä onMain
ohjelman aloituskohta. Niitä voidaan käyttää osoittamaan, kuinka luokan jäsenet toimivat keskenään.
Syntaksi:
:::code language="<language>" source="<path>" <attribute>="<attribute-value>":::
Tärkeä
Tämä syntaksi on Markdown-lohkolaajennus. Sitä on käytettävä omalla rivillään.
<language>
(valinnainen)- Koodikatkelman kieli. Lisätietoja on jäljempänä tämän artikkelin kohdassa Tuetut kielet.
<path>
(pakollinen)- Tiedostojärjestelmässä oleva suhteellinen polku, joka osoittaa koodikatkelmatiedoston, johon viitataan.
<attribute>
ja<attribute-value>
(valinnainen)- Käytetään yhdessä määrittämään, miten koodi noudetaan tiedostosta ja miten se tulisi näyttää:
range
:1,3-5
Rivialue. Tämä esimerkki sisältää rivit 1, 3, 4 ja 5.id
:Create
Sen katkelman tunnus, joka on lisättävä kooditiedostosta. Tämä arvo ei voi olla olemassa rinnakkain alueen kanssa.highlight
:2-4,6
Luodussa koodikatkelmassa korostettävien rivien alue ja/tai numerot. Numerointi on suhteessa näkyvissä oleviin riveihin (alueen tai tunnuksen mukaan), ei tiedostoon.interactive
:cloudshell-powershell
,cloudshell-bash
,try-dotnet
,try-dotnet-class
,try-dotnet-method
-merkkijonoarvo määrittää, millaiset vuorovaikutteisuudet ovat käytössä.- Lisätietoja tunnisteen nimen esittämisestä koodikatkelmien lähdetiedostoissa kielen mukaan on artikkelissa DocFX-ohjeet.
- Käytetään yhdessä määrittämään, miten koodi noudetaan tiedostosta ja miten se tulisi näyttää:
Learn Authoring Pack sisältää ominaisuuden, jonka avulla lauseke saadaan valmiiksi ja vahvistus käytettävissä olevista koodiaitalohkojen kielitunnisteista.
Nimi | Kelvolliset aliakset |
---|---|
.NET Core CLI | dotnetcli |
1C | 1c |
ABNF | abnf |
Access logs | accesslog |
Ada | ada |
ARM assembler | armasm , arm |
AVR assembler | avrasm |
ActionScript | actionscript , as |
Alan | alan , i |
AngelScript | angelscript , asc |
ANTLR | antlr |
Apache | apache , apacheconf |
AppleScript | applescript , osascript |
Arcade | arcade |
AsciiDoc | asciidoc , adoc |
AspectJ | aspectj |
ASPX | aspx |
ASP.NET (C#) | aspx-csharp |
ASP.NET (VB) | aspx-vb |
AutoHotkey | autohotkey |
AutoIt | autoit |
Awk | awk , 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 |
Perus | 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 |
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 , cson , iced |
Crmsh | crmsh , crm , pcmk |
Crystal | crystal , cr |
Cypher (Neo4j) | cypher |
D | d |
DAX Power BI | dax |
DNS Zone file | 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 |
Ohjaustangot | 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 |
Pienempi | less |
LDIF | ldif |
Lisp | lisp |
LiveCode Server | livecodeserver |
LiveScript | livescript , ls |
Lua | lua |
Makefile | makefile , mk , mak |
Merkintä | 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 |
Käsittely | processing |
Prolog | prolog |
Ominaisuudet | properties |
Protocol Buffers | protobuf |
Puppet | puppet , pp |
Python | python , py , gyp |
Python profiler results | 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 |
RPM spec files | 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 |
Malli | scheme |
Scilab | scilab , sci |
Shape Expressions | shexc |
Käyttöliittymä | shell , console |
Smali | smali |
Smalltalk | smalltalk , st |
Solidity | solidity , sol |
Stan | stan |
Stata | stata |
Structured 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 |
Vim Script | vim |
Visual Basic | vb |
Visual Basic for Applications | vba |
X++ | xpp |
x86 Assembly | 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 |
Vihje
Learn Authoring Pack, Dev Lang -viimeistelyn ominaisuus käyttää ensimmäistä kelvollista aliasta, kun useita aliaksia on käytettävissä.
Lisätietoja tekstin muotoilemisesta muille sisältötyypeille kuin koodille on ohjeaiheessa Tekstin muotoiluohjeet.