Come includere il codice nella documentazione

Esistono diversi modi diversi da quelli degli screenshot per includere il codice in un articolo pubblicato in Microsoft Learn:

• Singoli elementi (parole) all'interno di una riga.

  Ecco un esempio dello stile code.

  Usare il formato codice quando si fa riferimento a variabili e parametri denominati in un blocco di codice vicino all'interno del testo. Il formato codice può essere usato anche per proprietà, metodi, classi e parole chiave del linguaggio. Per altre informazioni, vedere la sezione Elementi di codice più avanti in questo articolo.

• Blocchi di codice nel file Markdown dell'articolo.

      ```csharp
      public static void Log(string message)
      {
          _logger.LogInformation(message);
      }
      ```
  

  Usare i blocchi di codice inline quando non è possibile visualizzare il codice facendo riferimento a un file di codice. Per altre informazioni, vedere la sezione Blocchi di codice più avanti in questo articolo.

• Blocchi di codice facendo riferimento a un file di codice nel repository locale.

  :::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::
  

  Per altre informazioni, vedere la sezione Riferimenti a frammenti di codice nel repository più avanti in questo articolo.

• Blocchi di codice facendo riferimento a un file di codice in un altro repository.

  :::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::
  

  Per altre informazioni, vedere la sezione Riferimenti a frammenti di codice al di fuori del repository più avanti in questo articolo.

• Blocchi di codice che consentono all'utente di eseguire codice nel browser.

  :::code source="PowerShell.ps1" interactive="cloudshell-powershell":::
  

  Per altre informazioni, vedere la sezione Frammenti di codice interattivi più avanti in questo articolo.

Oltre a illustrare il Markdown per ognuno di questi metodi di inserimento di codice, l'articolo offre anche alcune indicazioni generali per tutti i blocchi di codice.

Elementi del codice

Un "elemento del codice" è una parola chiave, un nome di classe, un nome di proprietà e altri oggetti di un linguaggio di programmazione. Non è sempre ovvio quali elementi vengono qualificati come codice. Ad esempio, i nomi di pacchetto NuGet devono essere considerati codice. In caso di dubbi, vedere Linee guida per la formattazione del testo.

Stile codice inline

Per includere un elemento di codice nel testo dell'articolo, racchiuderlo tra i backtick (') per indicare lo stile del codice. Nello stile codice inline non deve essere usato il formato del triplo apice inverso.

Markdown	Rendering
Per impostazione predefinita, Entity Framework interpreta una proprietà denominata 'Id' o 'ClassnameID' come chiave primaria.	Per impostazione predefinita, Entity Framework interpreta una proprietà denominata Id o ClassnameID come chiave primaria.

Quando un articolo è localizzato (tradotto in altre lingue), il testo con stile codice viene lasciato non tradotto. Se si vuole impedire la localizzazione senza usare lo stile codice, vedere Stringhe non localizzate.

Stile grassetto

Alcune guide di stile meno recenti raccomandano l'uso del grassetto per il codice inline. Il grassetto è un'opzione da prendere in considerazione quando lo stile codice è talmente invadente da compromettere la leggibilità. Ad esempio una tabella Markdown composta principalmente da elementi di codice può apparire confusa se formattata interamente con lo stile codice. Se si sceglie di applicare lo stile grassetto, usare la sintassi basata su stringhe non localizzate per assicurarsi che il codice non sia localizzato.

Collegamenti

In alcuni contesti, un collegamento alla documentazione di riferimento può essere più utile del formato di codice. Se si usa un collegamento, quindi, non applicare il formato di codice al testo del collegamento. Se si formatta un collegamento con lo stile codice, può risultare difficile capire che il testo è un collegamento.

Se si usa un collegamento e, in seguito, si fa riferimento allo stesso elemento nello stesso contesto, specificare le istanze successive in formato di codice anziché come collegamenti. Ad esempio:

The first reference to <xref:System.CommandLine> in this text is a link.
Subsequent references to `System.CommandLine` can be in code style.

Rendering:

Il primo riferimento a System.CommandLine in questo testo è un collegamento. I riferimenti successivi a System.CommandLine possono essere in stile di codice.

Segnaposto

Se si desidera che l'utente sostituisca una sezione del codice visualizzato con i propri valori, usare il testo segnaposto contrassegnato da parentesi angolari. Ad esempio:

az group delete -n <ResourceGroupName>

È possibile notare che le parentesi quadre devono essere rimosse quando si sostituiscono valori reali. La Guida di stile di scrittura Microsoft richiede corsivo, che è possibile formattare all'interno di un codice inline racchiuso tra parentesi angolari:

<ResourceGroupName> è il gruppo di risorse in cui...

Le parentesi graffe { } sono sconsigliate per l'uso come segnaposto sintattico. Possono essere confusi con la stessa notazione usata in testo sostituibile, stringhe di formato, interpolazione di stringhe, modelli di testo e costrutti di programmazione simili.

I nomi segnaposto possono essere separati da trattini ("maiuscole/minuscole kebab"), con caratteri di sottolineatura o non separati affatto (maiuscole/minuscole Pascal). Il caso kebab può generare errori di sintassi e caratteri di sottolineatura possono essere in conflitto con la sottolineatura. Tutti i maiuscole possono entrare in conflitto con costanti denominate in molte lingue, anche se può attirare l'attenzione sul nome segnaposto.

<Resource-Group-Name> oppure <ResourceGroupName>

Blocchi di codice

La sintassi per l'inserimento di codice in un documento dipende dalla posizione del codice:

• Nel file markdown dell'articolo
• In un file di codice nello stesso repository
• In un file di codice in un repository diverso

Le linee guida seguenti sono applicabili a tutti e tre i tipi di blocchi di codice:

• Screenshot
• Automatizzare la convalida del codice
• Evidenziare le righe chiave del codice
• Evitare barre di scorrimento orizzontali
• Identificare chiaramente il codice non valido

Screenshot

Tutti i metodi elencati nella sezione precedente danno origine a blocchi di codice utilizzabili:

• È possibile usarli per eseguire operazioni di copia e incolla.
• Sono indicizzati dai motori di ricerca.
• Sono accessibili dalle utilità per la lettura dello schermo.

Questi sono solo alcuni dei motivi per cui gli screenshot IDE non sono consigliati come metodi di inserimento di codice in un articolo. È opportuno usare screenshot IDE per il codice solo se si mostrano contenuti relativi all'IDE stesso, come nel caso di IntelliSense. È preferibile non usarli invece per mostrare l'applicazione di colori o sottolineature.

Convalida del codice

Per alcuni repository sono disponibili processi implementati che compilano automaticamente tutto il codice di esempio per individuare eventuali errori. Il repository .NET è uno di questi. Per altre informazioni, vedere Contributing (Contributi) nel repository .NET.

Se si includono blocchi di codice da un altro repository, concordare con i rispettivi proprietari una strategia di gestione del codice che, in caso di distribuzione di nuove versioni delle librerie usate dal codice, impedisca che il codice risulti obsoleto o danneggiato.

Evidenziazione

I frammenti di codice includono in genere più codice rispetto al necessario per fornire contesto. Ciò consente di migliorare la leggibilità evidenziando le righe chiave nel frammento di codice su cui concentrarsi, come nell'esempio seguente:

Non è possibile evidenziare il codice quando lo si include nel file markdown dell'articolo. L'evidenziazione funziona solo per i frammenti di codice inclusi facendo riferimento a un file di codice.

Barre di scorrimento orizzontali

Suddividere le righe lunghe per evitare le barre di scorrimento orizzontali. Le barre di scorrimento nei blocchi di codice peggiorano la leggibilità del codice. Sono particolarmente problematiche nei blocchi di codice più lunghi, in cui potrebbe risultare impossibile visualizzare contemporaneamente la barra di scorrimento e la riga da leggere.

Una buona norma per ridurre al minimo le barre di scorrimento orizzontali nei blocchi di codice consiste nel suddividere le righe di codice più lunghe di 85 caratteri. Tenere presente, tuttavia, che la presenza o l'assenza di una barra di scorrimento non è l'unico criterio di leggibilità. Se l'interruzione di una riga prima dell'85° carattere può comprometterne la leggibilità o ostacolarne il copia e incolla, è preferibile andare oltre gli 85 caratteri.

Identificare chiaramente il codice non valido

In alcuni scenari, è utile indicare i modelli di codifica che devono essere evitati, ad esempio:

• Codice che causerà un errore del compilatore se si tenta.
• Codice che verrà compilato correttamente ma non consigliato.

Per questi scenari:

• Spiegare l'errore sia nei commenti di codice che nel testo dell'articolo.

  I lettori spesso ignorano il testo dell'articolo e esaminano solo il codice, quindi non è sufficiente spiegare l'errore solo nel testo dell'articolo. Inoltre, non è sufficiente spiegare l'errore solo nei commenti di codice, perché i commenti di codice non sono localizzati.

• Prendere in considerazione la possibilità di impostare come commento il codice se si verifica un errore del compilatore.

  Il codice commentato non interromperà il sistema di integrazione continua (CI) se il repository dell'articolo ne ha ora uno o ne implementa uno in futuro.

Per un esempio di come presentare codice non consigliato, vedere Esempio di utilizzo di Rune: modifica del maiuscolo della lettera. In questo esempio, il consiglio di evitare che sia integrato nel codice stesso, perché il nome del metodo C# è ConvertToUpperBadExample.

Blocchi di codice inline

Usare i blocchi di codice inline solo quando non è possibile visualizzare il codice facendo riferimento a un file di codice. Il codice inline è generalmente più difficile da testare e mantenere aggiornato rispetto a un file di codice che fa parte di un progetto completo. È possibile, inoltre, che il codice inline ometta parti di contesto che potrebbero aiutare gli sviluppatori a comprendere e usare meglio il codice. Queste considerazioni si applicano essenzialmente ai linguaggi di programmazione. I blocchi di codice inline possono essere usati anche per output e input (ad esempio, JSON), linguaggi di query (ad esempio, SQL) e linguaggi di scripting (ad esempio, PowerShell).

Esistono due modi per indicare una sezione di testo in un file di articolo è un blocco di codice: fencing in triple backticks (''' ) o rientrandolo. La prima soluzione è preferibile perché consente di specificare il linguaggio. Evitare di impostare rientri perché possono creare confusione e potrebbe essere difficile per un altro autore identificarli nel momento in cui deve modificare l'articolo.

Gli indicatori del linguaggio vengono posizionati subito dopo i tre apici inversi di apertura, come nell'esempio seguente:

Markdown:

    ```json
    {
        "aggregator": {
            "batchSize": 1000,
            "flushTimeout": "00:00:30"
        }
    }
    ```

Rendering:

{
    "aggregator": {
        "batchSize": 1000,
        "flushTimeout": "00:00:30"
    }
}

Suggerimento

GitHub Flavored Markdown supporta il delimitazione dei blocchi di codice con tilde (~) e con backticks ('). Il simbolo usato per aprire e chiudere il blocco di codice deve essere coerente all'interno dello stesso blocco di codice.

Per informazioni sui valori che è possibile usare come indicatori di linguaggio, vedere Language names and aliases (Nomi e alias dei linguaggi).

Se si usa una parola di linguaggio o ambiente dopo i triplo backticks (''') non supportati, tale parola viene visualizzata nella barra del titolo della sezione del codice nella pagina di cui è stato eseguito il rendering. Se possibile, usare un indicatore di linguaggio o di ambiente nei blocchi di codice inline.

Nota

Se si copia e incolla codice da un documento di Word, assicurarsi che non contenga "virgolette curvi", che non sono valide nel codice. Se invece sono presenti, convertirle in virgolette normali (' e "). In alternativa, fare affidamento sulla funzionalità di sostituzione Learn Authoring Pack e virgolette intelligenti.

Riferimenti a frammenti di codice nel repository

Il modo migliore per includere in un documento frammenti di codice per linguaggi di programmazione è quello di fare riferimento a un file di codice. Questo metodo, infatti, offre la possibilità di evidenziare righe di codice e di rendere disponibile agli sviluppatori in GitHub un contesto più ampio del frammento di codice. È possibile includere il codice usando il formato a tre punti (:::) manualmente o in Visual Studio Code con l'aiuto di Learn Authoring Pack.

1. In Visual Studio Code fare clic su ALT+M o Opzione+M e selezionare Snippet (Frammento).
2. Dopo aver selezionato Snippet (Frammento) verrà richiesto di selezionare Full Search (Ricerca completa), Scoped Search (Ricerca con ambito) o Cross-Repository Reference (Riferimento tra repository). Per eseguire la ricerca in locale, selezionare Full Search (Ricerca completa).
3. Immettere un termine di ricerca per trovare il file. Dopo aver trovato il file, selezionarlo.
4. Selezionare quindi un'opzione per determinare le righe di codice da includere nel frammento. Le opzioni sono: ID, Intervallo e Nessuno.
5. In base alla selezione effettuata nel passaggio 4, fornire un valore se necessario.

Visualizzare l'intero file di codice:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs":::

Visualizzare una parte di un file di codice specificando i numeri di riga:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

Visualizzare una parte di un file di codice specificando un nome di frammento:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::

Le sezioni seguenti spiegano questi esempi:

• Usare un percorso relativo al file di codice
• Includere solo i numeri di riga selezionati
• Fare riferimento a un frammento di codice denominato
• Evidenziare righe selezionate

Per altre informazioni, vedere la sezione Informazioni di riferimento per la sintassi per i frammenti di codice più avanti in questo articolo.

Percorso del file di codice

Esempio:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

L'esempio è tratto dal repository docs ASP.NET, file dell'articolo aspnetcore/data/ef-mvc/crud.md. Si fa riferimento al file di codice tramite un percorso relativo a aspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs nello stesso repository.

Numeri di riga selezionati

Esempio:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

Questo esempio mostra solo le righe 2-24 e 26 del file di codice StudentController.cs.

Preferire frammenti di codice denominati piuttosto che numeri di riga hardcoded, come spiegato nella sezione successiva.

Frammento di codice denominato

Esempio:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::

Usare solo lettere e caratteri di sottolineatura per il nome.

L'esempio mostra la sezione snippet_Create del file di codice. Il file di codice per questo esempio contiene tag snippet nei commenti in codice C#:

// code excluded from the snippet
// <snippet_Create>
// code included in the snippet
// </snippet_Create>
// code excluded from the snippet

I frammenti di codice denominati possono essere annidati, come illustrato nell'esempio seguente:

// <Method>
public static void SomeMethod()
{
    // <Line>
    // Single line of code.
    // </Line>
}
// </Method>

Quando viene eseguito il rendering del Method frammento di codice, i Line tag non vengono inclusi nell'output sottoposto a rendering.

Quando possibile, fare riferimento a una sezione denominata piuttosto che specificare numeri di riga. I riferimenti ai numeri di riga sono precari perché i file di codice inevitabilmente cambiano in modi che comportano anche la modifica dei numeri di riga. Non si riceve necessariamente notifica di queste modifiche e nell'articolo iniziano a essere visualizzate le righe sbagliate senza alcuna indicazione di cosa è cambiato.

Evidenziazione delle righe selezionate

Esempio:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26" highlight="2,5":::

Nell'esempio vengono evidenziate le righe 2 e 5, a partire dall'inizio del frammento visualizzato. I numeri di riga da evidenziare non vengono conteggiati dall'inizio del file di codice. In altre parole, vengono evidenziate le righe 3 e 6 del file di codice.

Riferimenti a frammenti di codice al di fuori del repository

Se il file di codice a cui si vuole fare riferimento si trova in un altro repository, impostare il repository del codice come repository dipendente. In questo caso è necessario specificare un nome per il repository. Tale nome funge quindi da nome di cartella ai fini dei riferimenti al codice.

Ad esempio, il repository docs è Azure/azure-docs e il repository del codice è Azure/azure-functions-durable-extension.

Nella cartella radice di azure-docs aggiungere la sezione seguente in .openpublishing.publish.config.json:

    {
      "path_to_root": "samples-durable-functions",
      "url": "https://github.com/Azure/azure-functions-durable-extension",
      "branch": "main",
      "branch_mapping": {}
    },

In questo modo, quando si fa riferimento a samples-durable-functions come se fosse una cartella in azure-docs, in realtà si fa riferimento alla cartella radice nel repository azure-functions-durable-extension.

È possibile includere il codice usando il formato a tre punti (:::) manualmente o in Visual Studio Code con l'aiuto di Learn Authoring Pack.

1. In Visual Studio Code fare clic su ALT+M o Opzione+M e selezionare Snippet (Frammento).
2. Dopo aver selezionato Snippet (Frammento) verrà richiesto di selezionare Full Search (Ricerca completa), Scoped Search (Ricerca con ambito) o Cross-Repository Reference (Riferimento tra repository). Per eseguire la ricerca tra repository, selezionare Cross-Repository Reference (Riferimento tra repository).
3. Verrà fornita una selezione di repository disponibili in .openpublishing.publish.config.json. Selezionare un repository.
4. Immettere un termine di ricerca per trovare il file. Dopo aver trovato il file, selezionarlo.
5. Selezionare quindi un'opzione per determinare le righe di codice da includere nel frammento. Le opzioni sono: ID, Intervallo e Nessuno.
6. In base alla selezione effettuata nel passaggio 5, specificare un valore.

Il riferimento al frammento di codice sarà simile al seguente:

:::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::

Nel repository azure-functions-durable-extension, tale file di codice è disponibile nella cartella samples/csx/shared. Come specificato in precedenza, i numeri di riga per l'evidenziazione fanno riferimento all'inizio del frammento e non all'inizio del file.

Nota

Il nome assegnato al repository dipendente è relativo alla radice del repository principale, ma la tilde (~) fa riferimento alla radice del docset. La radice del docset è determinata da build_source_folder in .openpublishing.publish.config.json. Il percorso del frammento riportato nell'esempio precedente funziona nel repository azure-docs perché build_source_folder fa riferimento alla radice del repository (.). Se build_source_folder fosse articles, il percorso inizierebbe con ~/../samples-durable-functions anziché con ~/samples-durable-functions.

Frammenti di codice in un notebook di Jupyter

È possibile fare riferimento a una cella in un notebook di Jupyter come frammento di codice. Per fare riferimento alla cella:

1. Aggiungere i metadati delle celle al notebook per le celle a cui si desidera fare riferimento.
2. Configurare l'accesso al repository.
3. Usare la sintassi del frammento di codice del notebook jupyter nel file markdown.

Aggiungere metadati al notebook

1. Assegnare alla cella il nome aggiungendo i metadati delle celle nel notebook di Jupyter.

   • In Jupyter è possibile modificare i metadati delle celle abilitando prima la barra degli strumenti delle celle: Visualizza > barra degli strumenti > cella Modifica metadati.
   • Dopo aver abilitato la barra degli strumenti delle celle, selezionare Modifica metadati nella cella da assegnare al nome.
   • In alternativa, è possibile modificare i metadati direttamente nella struttura JSON del notebook.

2. Nei metadati della cella aggiungere un attributo "name":

   "metadata": {"name": "<name>"},
   

   Ad esempio:

   "metadata": {"name": "workspace"},
   

   Suggerimento

   È possibile aggiungere qualsiasi altro metadato che si vuole aiutare a tenere traccia della posizione in cui viene usata la cella. Ad esempio:

       "metadata": {
         "name": "workspace",
         "msdoc": "how-to-track-experiments.md"
       },
   

Configurare l'accesso al repository

Se il file del notebook a cui si vuole fare riferimento si trova in un repository diverso, configurare il repository di codice come repository dipendente.

Informazioni di riferimento sulla sintassi del frammento di notebook di Jupyter

Dopo che il notebook contiene i metadati necessari, farvi riferimento nel file markdown. Usare l'elemento <cell-name-value> aggiunto al notebook e l'oggetto <path> configurato come repository dipendente.

[!notebook-<language>[] (<path>/<notebook-name.ipynb>?name=<cell-name-value>)]

Ad esempio:

[!notebook-python[] (~/MachineLearningNotebooks/train-on-local.ipynb?name=workspace)]

Importante

Questa sintassi è un'estensione Markdown di blocco e deve essere usata su una riga a sé stante.

Usare una delle lingue supportate per l'identificatore <language> .

Frammenti di codice interattivi

Blocchi di codice interattivi inline

Per i linguaggi seguenti, è possibile impostare i frammenti di codice come eseguibili nella finestra del browser:

• Azure Cloud Shell
• Azure PowerShell Cloud Shell
• C# REPL

Quando è abilitata la modalità interattiva, i riquadri del codice dopo il rendering includono un pulsante Prova o Esegui. Ad esempio:

    ```azurepowershell-interactive
    New-AzResourceGroup -Name myResourceGroup -Location westeurope
    ```

Il rendering è il seguente:

New-AzResourceGroup -Name myResourceGroup -Location westeurope

And

    ```csharp-interactive
    var aFriend = "Maria";
    Console.WriteLine($"Hello {aFriend}");
    ```

esegue il rendering come:

    var aFriend = "Maria";
    Console.WriteLine($"Hello {aFriend}");

Per attivare questa funzionalità per un blocco di codice specifico, usare un identificatore di linguaggio speciale. Le opzioni disponibili sono:

• azurepowershell-interactive - Abilita Azure PowerShell Cloud Shell, come nell'esempio precedente
• azurecli-interactive - Abilita Azure Cloud Shell
• csharp-interactive - Abilita REPL C#

Per Azure Cloud Shell e PowerShell Cloud Shell, gli utenti possono eseguire i comandi solo con l'account personale di Azure.

Frammenti di codice inclusi per riferimento

È possibile abilitare la modalità interattiva per i frammenti di codice inclusi per riferimento. Per attivare questa funzionalità per un blocco di codice specifico, usare l'attributo interactive. I valori disponibili per l'attributo sono:

• cloudshell-powershell - Abilita Azure PowerShell Cloud Shell, come nell'esempio precedente
• cloudshell-bash - Abilita Azure Cloud Shell
• try-dotnet -Abilita Try .NET
• try-dotnet-class -Abilita Try .NET con scaffolding delle classi
• try-dotnet-method -Abilita Try .NET con scaffolding dei metodi

Di seguito sono riportati alcuni esempi.

:::code source="PowerShell.ps1" interactive="cloudshell-powershell":::

:::code source="Bash.sh" interactive="cloudshell-bash":::

Per Azure Cloud Shell e PowerShell Cloud Shell, gli utenti possono eseguire i comandi solo con l'account personale di Azure.

Per quanto riguarda .NET Interactive, il contenuto del blocco di codice dipende da quale delle tre esperienze di scaffolding si sceglie:

• Nessuna scaffolding (try-dotnet): il blocco di codice deve rappresentare un testo completo del programma. Ad esempio, il file Program.cs generato da dotnet new console vale come tale. Questi elementi sono molto utili per mostrare un piccolo programma interno, comprendente le direttive using necessarie. Le istruzioni di primo livello non sono supportate in questo scenario.
• Scaffolding del metodo (try-dotnet-method): il blocco di codice deve rappresentare il contenuto di un Main metodo in un'applicazione console. È possibile assumere le direttive using aggiunte dal modello dotnet new console. Questa impostazione è molto utile per piccoli frammenti di codice che dimostrano una funzionalità.
• Scaffolding della classe (try-dotnet-class): il blocco di codice deve rappresentare una classe con un Main metodo come punto di ingresso del programma. Questi elementi possono essere usati per mostrare la modalità di interazione tra i membri di una classe.

Informazioni di riferimento per la sintassi per i frammenti di codice

Sintassi:

:::code language="<language>" source="<path>" <attribute>="<attribute-value>":::

Importante

Questa sintassi è un'estensione Markdown di blocco e deve essere usata su una riga a sé stante.

• <language> (facoltativo)

  • Linguaggio del frammento di codice. Per altre informazioni, vedere la sezione Linguaggi supportati più avanti in questo articolo.

• <path> (obbligatorio)

  • Percorso relativo nel file system che indica il file del frammento di codice a cui fare riferimento.

• <attribute> e <attribute-value> (facoltativi)

  • Usato insieme per specificare come recuperare il codice dal file e come deve essere visualizzato:
    • range: 1,3-5 Intervallo di righe. Questo esempio include le righe 1, 3, 4 e 5.
    • id: Create ID del frammento di codice che deve essere inserito dal file di codice. Questo valore non può coesistere con l'intervallo.
    • highlight: 2-4,6 intervallo e/o numeri di righe che devono essere evidenziati nel frammento di codice generato. La numerazione è relativa alle righe visualizzate (in base a quanto specificato dall'intervallo o dall'ID) e non al file.
    • interactive: cloudshell-powershell, cloudshell-bash, try-dotnet, try-dotnet-classtry-dotnet-method Valore stringa che determina quali tipi di interattività sono abilitati.
    • Per altri dettagli sulla rappresentazione dei nomi di tag nei file di origine dei frammenti di codice in base al linguaggio, vedere le linee guida per DocFX.

Lingue supportate

Learn Authoring Pack include una funzionalità per fornire il completamento delle istruzioni e la convalida degli identificatori di lingua disponibili per i blocchi di isolamento del codice.

Blocchi di codice delimitati

Nome	Alias validi
Interfaccia della riga di comando di .NET Core	dotnetcli
1C	1c
ABNF	abnf
Accedere ai log	accesslog
Ada	ada
Assembler ARM	armasm, arm
Assembler AVR	avrasm
ActionScript	actionscript, as
Mattia	alan, i
AngelScript	angelscript, asc
ANTLR	antlr
Apache	apache, apacheconf
AppleScript	applescript, osascript
Arcade	arcade
AsciiDoc	asciidoc, adoc
AspectJ	aspectj
ASPX	aspx
ASP.NET (C#)	aspx-csharp
ASP.NET (VB)	aspx-vb
AutoHotkey	autohotkey
AutoIt	autoit
Awk	awk, mawk, nawkgawk
Axapta	axapta
AzCopy	azcopy
Interfaccia della riga di comando di Azure	azurecli
Interfaccia della riga di comando di Azure (interattiva)	azurecli-interactive
Azure PowerShell	azurepowershell
Azure PowerShell (interattivo)	azurepowershell-interactive
Bash	bash, sh, zsh
Di base	basic
BNF	bnf
A	c
C#	csharp, cs
C# (interattivo)	csharp-interactive
C++	cpp, c, cc, hc++, , h++hpp
C++/CX	cppcx
C++/WinRT	cppwinrt
C/AL	cal
Script oggetto cache	cos, cls
CMake	cmake, cmake.in
Coq	coq
CSP	csp
CSS	css
Cap'n Proto	capnproto, capnp
Clojure	clojure, clj
CoffeeScript	coffeescript, coffee, csoniced
Crmsh	crmsh, crm, pcmk
Crystal	crystal, cr
Cypher (Neo4j)	cypher
D	d
DAX Power BI	dax
File di zona DNS	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
Manubrio	handlebars, hbs, html.hbshtml.handlebars
Haskell	haskell, hs
Haxe	haxe, hx
Hy	hy, hylang
Ini	ini
Inform7	inform7, i7
IRPF90	irpf90
JSON	json
Java	java, jsp
JavaScript	javascript, js, jsx
Kotlin	kotlin, kt
Kusto	kusto
Foglia	leaf
Lasso	lasso, ls, lassoscript
Minore di	less
LDIF	ldif
Lisp	lisp
LiveCode Server	livecodeserver
LiveScript	livescript, ls
Lua	lua
Makefile	makefile, mk, mak
Markdown	markdown, md, mkdownmkd
Mathematica	mathematica, mma, wl
Matlab	matlab
Maxima	maxima
Maya Embedded Language	mel
Mercurio	mercury
mIRC Scripting Language	mirc, mrc
Mizar	mizar
MOF (Managed Object Format)	mof
Mojolicious	mojolicious
Monkey	monkey
Moonscript	moonscript, moon
MS Graph (interattivo)	msgraph-interactive
N1QL	n1ql
NSIS	nsis
Nginx	nginx, nginxconf
Nimrod	nimrod, nim
Nix	nix
OCaml	ocaml, ml
Objective C	objectivec, mm, objcobj-c
OpenGL Shading Language	glsl
OpenSCAD	openscad, scad
Oracle Rules Language	ruleslanguage
Oxygene	oxygene
PF	pf, pf.conf
PHP	php, php3, php4, php5php6
Parser3	parser3
Perl	perl, pl, pm
PlainText (senza evidenziazione)	plaintext
Pony	pony
PostgreSQL e PL/pgSQL	pgsql, postgres, postgresql
PowerShell	powershell, ps
PowerShell (interattivo)	powershell-interactive
in lavorazione	processing
Prolog	prolog
Proprietà	properties
Buffer di protocollo	protobuf
Puppet	puppet, pp
Python	python, py, gyp
Python Profiler (risultati)	profile
Q#	qsharp
T	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 (file specifiche)	rpm-specfile, rpm, spec, rpm-specspecfile
Ruby	ruby, rb, gemspec, podspec, thorirb
Rust	rust, rs
SAS	SAS, sas
SCSS	scss
SQL	sql
STEP Part 21	p21, step, stp
Scala	scala
Schema	scheme
Scilab	scilab, sci
Shape Expressions	shexc
Shell	shell, console
Smali	smali
Smalltalk	smalltalk, st
Solidity	solidity, sol
Stan	stan
Stata	stata
Testo strutturato	iecst, scl, stlstructured-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, Applications Edition	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

Suggerimento

La funzionalità Learn Authoring Pack, Dev Lang Completion usa il primo alias valido quando sono disponibili più alias.

Passaggi successivi

Per informazioni sulla formattazione del testo in caso di tipi di contenuto diversi dal codice, vedere Linee guida per la formattazione del testo.