Lue englanniksi

Jaa


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

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.

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:

Seuraavat ohjeet koskevat kaikkia kolmea koodilohkotyyppiä:

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.

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.

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.

  1. Valitse Visual Studio Codessa Alt + M tai Optio + M ja valitse Snippet (Katkelma).
  2. 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.
  3. Etsi tiedosto kirjoittamalla hakusana. Kun olet löytänyt tiedoston, valitse se.
  4. Valitse seuraavaksi vaihtoehto, joka määrittää, mitkä koodirivit katkelmaan sisällytetään. Vaihtoehdot ovat: ID (tunnus) ja Range (alue) ja None (ei mitään).
  5. 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:

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.

  1. Valitse Visual Studio Codessa Alt + M tai Optio + M ja valitse Snippet (Katkelma).
  2. 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).
  3. Saat valikoiman säilöistä, jotka ovat kohteessa .openpublishing.publish.config.json. Valitse säilö.
  4. Etsi tiedosto kirjoittamalla hakusana. Kun olet löytänyt tiedoston, valitse se.
  5. Valitse seuraavaksi vaihtoehto, joka määrittää, mitkä koodirivit katkelmaan sisällytetään. Vaihtoehdot ovat: ID (tunnus) ja Range (alue) ja None (ei mitään).
  6. 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.

Katkelmia Jupyter-muistikirjassa

Voit viitata Jupyter-muistikirjassa olevan solun koodikatkelmana. Soluun viittaaminen:

  1. Lisää muistikirjaan solun metatiedot soluille, joihin haluat viitata.
  2. Määritä säilön käyttöoikeus.
  3. Käytä Jupyter-muistikirjan katkelman syntaksia markdown-tiedostossasi.

Metatietojen lisääminen muistikirjaan

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