Koodin sisällyttäminen dokumentaatioon

Artikkeli
10/04/2024

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

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.

Sisäisen koodin tyyli

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.

Lihavoitu tyyli

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.

Linkit

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ä.

Paikkamerkit

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>

Koodilohkot

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

Näyttökuvat

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.

Koodin vahvistus

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.

Korostus

Katkelmissa on yleensä enemmän koodia, kuin mikä on tarpeen kontekstin antamiseksi. Koodikatkelman tärkeimpien rivien korostaminen helpottaa luettavuutta seuraavassa esimerkissä esitetyllä tavalla:

Example showing highlighted code

Et voi korostaa koodia, kun sisällytät sen artikkelin Markdown-tiedostoon. Se toimii vain koodikatkelmissa, jotka on sisällytetty viittauksella kooditiedostoon.

Vaakasuorat vierityspalkit

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.

Tunnista selvästi virheellinen koodi

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.

Sisäiset koodilohkot

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.

Muistiinpano

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.

Säilön sisäiset koodikatkelmien viittaukset

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.

Kooditiedoston polku

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ä.

Valitut rivinumerot

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.

Nimetty katkelma

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.

Valittujen rivien korostus

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.

Säilön ulkopuoliset koodikatkelmien viittaukset

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.

Muistiinpano

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.

Katkelmia Jupyter-muistikirjassa

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.

Metatietojen lisääminen muistikirjaan

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"
    },

Määritä säilön käyttöoikeus

Jos muistikirjatiedosto, johon haluat viitata, on eri säilössä, määritä koodisäilö riippuvaisena säilönä.

Jupyter-muistikirjan katkelman syntaksiviittaus

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>.

Vuorovaikutteiset koodikatkelmat

Sisäiset vuorovaikutteiset koodilohkot

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 -palvelun
csharp-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.

Koodikatkelmat, jotka on sisällytetty viittauksella

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 -palvelun
try-dotnet -Ottaa käyttöön Try .NET -palvelun
try-dotnet-class -Ottaa käyttöön Try .NET -palvelun ja luokkarakenteen
try-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 luonut dotnet new console, on täysin kelvollinen. Ne ovat erityisen hyödyllisiä näyttämään koko pienen ohjelman mukaan lukien tarvittaessa using-ohjeet. Tässä vaiheessa ylätason lausekkeita ei tueta.
Menetelmärakenne (try-dotnet-method): Koodilohkon tulisi edustaa menetelmän Main sisältöä konsolisovelluksessa. Voit omaksua using-direktiivit, jotka dotnet 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ä on Main ohjelman aloituskohta. Niitä voidaan käyttää osoittamaan, kuinka luokan jäsenet toimivat keskenään.

Katkelman syntaksiviittaus

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.

Tuetut kielet

Learn Authoring Pack sisältää ominaisuuden, jonka avulla lauseke saadaan valmiiksi ja vahvistus käytettävissä olevista koodiaitalohkojen kielitunnisteista.

Aidatut koodilohkot

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`, `hc++`, , `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`, `pascalfreepascal`, `lazarus`, , `lprlfm`
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`, `atomxjb`, `xsd`, , `xslplist`
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ä.

Seuraavat vaiheet

Lisätietoja tekstin muotoilemisesta muille sisältötyypeille kuin koodille on ohjeaiheessa Tekstin muotoiluohjeet.

Jaa

Koodin sisällyttäminen dokumentaatioon

Koodielementit

Sisäisen koodin tyyli

Lihavoitu tyyli

Linkit

Paikkamerkit

Koodilohkot

Näyttökuvat

Koodin vahvistus

Korostus

Vaakasuorat vierityspalkit

Tunnista selvästi virheellinen koodi

Sisäiset koodilohkot

Säilön sisäiset koodikatkelmien viittaukset

Kooditiedoston polku

Valitut rivinumerot

Nimetty katkelma

Valittujen rivien korostus

Säilön ulkopuoliset koodikatkelmien viittaukset

Katkelmia Jupyter-muistikirjassa

Metatietojen lisääminen muistikirjaan

Määritä säilön käyttöoikeus

Jupyter-muistikirjan katkelman syntaksiviittaus

Vuorovaikutteiset koodikatkelmat

Sisäiset vuorovaikutteiset koodilohkot

Koodikatkelmat, jotka on sisällytetty viittauksella

Katkelman syntaksiviittaus

Tuetut kielet

Aidatut koodilohkot

Seuraavat vaiheet

Palaute

Lisäresursseja