Inclusión de código en documentosHow to include code in docs

Hay varias maneras de incluir código en un artículo publicado en docs.microsoft.com:There are several ways to include code in an article published on docs.microsoft.com:

  • Elementos individuales (palabras) dentro de una línea.Individual elements (words) within a line.

    Este es un ejemplo de estilo code.Here's an example of code style.

    Use el formato de código al hacer referencia a parámetros y variables con nombre en un bloque de código cercano en el texto.Use code format when referring to named parameters and variables in a nearby code block in your text. El formato de código también se puede usar para las propiedades, los métodos, las clases y las palabras clave del lenguaje.Code format may also be used for properties, methods, classes, and language keywords. Para obtener más información, consulte Elementos de código, más adelante en este artículo.For more information, see Code elements later in this article..

  • Bloques de código en el archivo Markdown del artículo.Code blocks in the article Markdown file.

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

    Use bloques de código insertados cuando no resulte práctico mostrar código por referencia a un archivo de código.Use inline code blocks when it's impractical to display code by reference to a code file. Para obtener más información, consulte Bloques de código, más adelante en este artículo.For more information, see Code blocks later in this article.

  • Bloques de código por referencia a un archivo de código del repositorio local.Code blocks by reference to a code file in the local repository.

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

    Para obtener más información, consulte Referencias de fragmentos de código en el repositorio, más adelante en este artículo.For more information, see In-repo snippet references later in this article.

  • Bloques de código por referencia a un archivo de código de otro repositorio.Code blocks by reference to a code file in another repository.

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

    Para obtener más información, consulte Referencias de fragmentos de código fuera del repositorio, más adelante en este artículo.For more information, see Out-of-repo snippet references later in this article.

  • Bloques de código que permiten al usuario ejecutar código en el explorador.Code blocks that let the user execute code in the browser.

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

    Para obtener más información, consulte Fragmentos de código interactivos, más adelante en este artículo.For more information, see Interactive code snippets later in this article.

Además de explicar el archivo Markdown para cada una de estas formas de incluir código, el artículo proporciona algunas guías generales para todos los bloques de código.Besides explaining the Markdown for each of these ways to include code, the article provides some general guidance for all code blocks.

Elementos de códigoCode elements

Un "elemento de código" es una palabra clave, un nombre de clase o un nombre de propiedad de lenguaje de programación, entre otras.A "code element" is a programming language keyword, class name, property name, and so forth. No siempre resulta obvio lo que se califica como código.It's not always obvious what qualifies as code. Por ejemplo, los nombres de paquetes NuGet deben tratarse como código.For example, NuGet package names should be treated as code. En caso de duda, consulte Instrucciones para la aplicación de formato al texto.When in doubt, see Text formatting guidelines.

Estilo de código insertadoInline code style

Para incluir un elemento de código en el texto del artículo, debe rodeador por acentos graves (`) para indicar estilo de código.To include a code element in article text, surround it with backticks (`) to indicate code style. El estilo de código insertado no debe usar el formato de marca de graduación triple.Inline code style shouldn't use the triple-backtick format.

MarkdownMarkdown RepresentadoRendered
De forma predeterminada, Entity Framework interpreta una propiedad con el nombre `Id` o `ClassnameID` como clave principal.By default, the Entity Framework interprets a property that's named `Id` or `ClassnameID` as the primary key. De forma predeterminada, Entity Framework interpreta una propiedad con el nombre Id o ClassnameID como clave principal.By default, the Entity Framework interprets a property that's named Id or ClassnameID as the primary key.

Cuando un artículo se localiza (se traduce a otros idiomas), el texto con estilo de código se deja sin traducir.When an article is localized (translated into other languages), text styled as code is left untranslated. Si quiere evitar la localización sin usar el estilo de código, vea Cadenas no localizadas.If you want to prevent localization without using code style, see Non-localized strings.

Estilo negritaBold style

Algunas guías de estilo antiguas especifican la negrita para el código insertado.Some older style guides specify bold for inline code. La negrita es una opción cuando el estilo de código es tan molesto que puede poner en peligro la legibilidad.Bold is an option when code style is so obtrusive as to compromise readability. Por ejemplo, una tabla Markdown que contenga principalmente elementos de código podría tener un aspecto demasiado denso al usar únicamente estilo de código.For example, a Markdown table with mostly code elements might look too busy with code styling everywhere. Si decide usar el estilo negrita, utilice la sintaxis de cadenas no localizadas para asegurarse de que el código no está localizado.If you choose to use bold style, use non-localized strings syntax to make sure that code is not localized.

En algunos contextos puede ser más útil un vínculo a la documentación de referencia que el formato de código.A link to reference documentation may be more helpful than code format in some contexts. Si usa un vínculo, no aplique el formato de código al texto del vínculo.If you use a link, don't apply code format to the link text. Si aplica el estilo código a un vínculo, puede que sea difícil identificarlo como tal.Styling a link as code can obscure the fact that the text is a link.

Si usa un vínculo y hace referencia al mismo elemento más adelante en el mismo contexto, aplique formato de código a las instancias siguientes en lugar de vínculos.If you use a link and refer to the same element later in the same context, make the subsequent instances code format rather than links.

Marcadores de posiciónPlaceholders

Si quiere que el usuario reemplace una sección del código mostrado con sus propios valores, use el texto de marcador de posición marcado como desactivado entre llaves o corchetes angulares.If you want the user to replace a section of displayed code with their own values, use placeholder text marked off by angle brackets or curly braces. Por ejemplo, az group delete -n <ResourceGroupName>.For example: az group delete -n <ResourceGroupName>. Explique que se deben quitar los corchetes o llaves al sustituirlo por los valores reales.Explain that the brackets or braces must be removed when substituting real values.

Bloques de códigoCode blocks

La sintaxis para incluir código en un documento depende de dónde se encuentre el código:The syntax for including code in a doc depends on where the code is located:

A continuación se muestran las instrucciones que se aplican a los tres tipos de bloques de código:Following are guidelines that apply to all three types of code blocks:

Capturas de pantallaScreenshots

Todos los métodos enumerados en la sección anterior tienen como resultado bloques de código que se pueden usar:All of the methods listed in the preceding section result in usable code blocks:

  • Puede copiar y pegar de ellos.You can copy and paste from them.
  • Están indexados por motores de búsqueda.They're indexed by search engines.
  • Son accesibles para los lectores de pantalla.They're accessible to screen readers.

Estos son solo algunos de los motivos por los que no se recomiendan las capturas de pantalla del IDE como método para incluir código en un artículo.These are just a few of the reasons why IDE screenshots aren't recommended as a method of including code in an article. Use capturas de pantalla del IDE solo para el código si está mostrando algo sobre el propio IDE, como IntelliSense.Use IDE screenshots for code only if you're showing something about the IDE itself, like IntelliSense. No use capturas de pantallas solo para mostrar el color y el resaltado.Don't use screenshots just to show colorization and highlighting.

Validación de códigoCode validation

Algunos repositorios han implementado procesos que compilan automáticamente todos los códigos de ejemplo para comprobar si hay errores.Some repositories have implemented processes that automatically compile all sample code to check for errors. El repositorio de .NET lo hace.The .NET repository does this. Para obtener más información, consulte Contribución en el repositorio. NET.For more information, see Contributing in the .NET repository.

Si va a incluir bloques de código de otro repositorio, trabaje con los propietarios en una estrategia de mantenimiento para el código, de modo que el código incluido no se interrumpa ni quede desactualizado a medida que se envían nuevas versiones de las bibliotecas que usa el código.If you are including code blocks from another repository, work with the owners on a maintenance strategy for the code so that your included code does not break or go out of date as new versions of the libraries the code uses are shipped.

ResaltadoHighlighting

Los fragmentos de código suelen incluir más código del necesario para proporcionar contexto.Snippets typically include more code than necessary in order to provide context. La legibilidad mejora si se resaltan las líneas clave en las que se está centrando en el fragmento, como en este ejemplo:It helps readability when you highlight the key lines that you're focusing on in the snippet, as in this example:

Ejemplo que muestra código resaltado

No se puede resaltar el código cuando se incluye en el archivo Markdown del artículo.You can't highlight code when you include it in the article Markdown file. Solo funciona con los fragmentos de código incluidos por referencia en un archivo de código.It works only for code snippets included by reference to a code file.

Barras de desplazamiento horizontalHorizontal scroll bars

Divida las líneas largas para evitar las barras de desplazamiento horizontal.Break up long lines to avoid horizontal scroll bars. Las barras de desplazamiento en los bloques de código hacen que el código resulte difícil de leer.Scroll bars on code blocks make code hard to read. Son especialmente problemáticas en bloques de código más largos, donde puede ser imposible ver la barra de desplazamiento y la línea que desea leer al mismo tiempo.They're especially problematic on longer code blocks, where it may be impossible to see the scroll bar and the line you want to read at the same time.

Una buena práctica para minimizar las barras de desplazamiento horizontal en bloques de código es fragmentar las líneas de código de más de 85 caracteres,A good practice for minimizing horizontal scroll bars on code blocks is to break up code lines longer than 85 characters. pero tenga en cuenta que la presencia o ausencia de una barra de desplazamiento no es el único criterio de legibilidad.But keep in mind that the presence or absence of a scroll bar isn't the only criterion of readability. Si la división de una línea antes de los 85 caracteres perjudica la legibilidad o la facilidad de copiar y pegar, no dude en sobrepasarlos.If breaking a line before 85 hurts readability or copy-paste convenience, feel free to go over 85.

Bloques de código insertadoInline code blocks

Use bloques de código insertados únicamente cuando no resulte práctico mostrar código por referencia a un archivo de código.Use inline code blocks only when it's impractical to display code by reference to a code file. El código insertado suele ser más difícil de probar y de mantener actualizado, en comparación con un archivo de código que forma parte de un proyecto completo.Inline code is generally more difficult to test and keep up to date compared to a code file that is part of a complete project. Además, el código insertado puede omitir el contexto que podría ayudar al desarrollador a entender y usar el código.And inline code may omit context that could help the developer to understand and use the code. Estas consideraciones se aplican principalmente a los lenguajes de programación.These considerations apply mainly to programming languages. También se pueden usar los bloques de código insertado para las salidas y entradas (como JSON), los lenguajes de consulta (como SQL) y los lenguajes de scripting (como PowerShell).Inline code blocks can also be used for outputs and inputs (such as JSON), query languages (such as SQL), and scripting languages (such as PowerShell).

Hay dos formas de indicar que una sección de texto de un archivo de artículo es un bloque de código: mediante una barrera de tres acentos graves (```) o mediante el sangrado.There are two ways to indicate a section of text in an article file is a code block: by fencing it in triple-backticks (```) or by indenting it. La barrera es preferible porque le permite especificar el lenguaje.Fencing is preferred because it lets you specify the language. No aplique sangrías, ya que es muy fácil equivocarse, y otro escritor podría tener dificultades para entender su intención cuando tenga que editar el artículo.Avoid using indentation because it's too easy to get wrong and it may be hard for another writer to understand your intent when they need to edit your article.

Los indicadores de lenguaje se colocan inmediatamente después de los tres acentos graves de apertura, como en el siguiente ejemplo:Language indicators are placed immediately after the opening triple-backticks, as in the following example:

Markdown:Markdown:

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

Representado:Rendered:

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

Para más información sobre los valores que se puede utilizar como indicadores de lenguaje, consulte el artículo sobre nombres de lenguajes y alias.For information about the values you can use as language indicators, see Language names and aliases.

Si usa una palabra de idioma o de entorno que no se admite después de los tres acentos graves (```), la palabra aparecerá en la barra de título de la sección de código en la página representada.If you use a language or environment word after the triple-backticks (```) that isn't supported, that word appears in the code section title bar on the rendered page. Siempre que sea posible, use un indicador de idioma o de entorno en los bloques de código insertado.Whenever possible, use a language or environment indicator in your inline code blocks.

Nota

Si copia y pega código desde un documento de Word, asegúrese de que no tiene "comillas tipográficas", que no son válidas en el código (por ejemplo, y ).If you copy and paste code from a Word document, make sure it has no "curly quotes," which aren't valid in code (for example, and ). Si es así, cámbielas de nuevo a las comillas normales (' y ").If it does, change them back to normal quotes (' and "). Como alternativa, use la característica de reemplazo de comillas inteligentes del paquete de creación de Docs.Alternatively, rely on the Docs Authoring Pack, smart quotes replacement feature.

Referencias de fragmentos de código en el repositorioIn-repo snippet references

La mejor manera de incluir fragmentos de código para lenguajes de programación en los documentos es por referencia a un archivo de código.The preferred way to include code snippets for programming languages in docs is by reference to a code file. Este método ofrece la posibilidad de resaltar líneas de código y hace que el contexto más amplio del fragmento de código esté disponible en GitHub para que lo usen los desarrolladores.This method gives you the ability to highlight lines of code and makes the wider context of the snippet available on GitHub for developers to use. Puede incluir código mediante el formato de tres puntos (:::), ya sea manualmente o en Visual Studio Code con la ayuda del paquete de creación docs.microsoft.com.You can include code by using the triple colon format (:::) either manually or in Visual Studio Code with the help of the docs.microsoft.com Authoring Pack.

  1. En Visual Studio Code, presione Alt + M u Opción + M y seleccione Fragmento de código.In Visual Studio Code, click Alt + M or Option + M and select Snippet.
  2. Cuando lo haya hecho, se le solicitará una búsqueda completa, una búsqueda con ámbito o una referencia entre repositorios.Once Snippet is selected, you will be prompted for Full Search, Scoped Search or Cross-Repository Reference. Para buscar de forma local, seleccione Búsqueda completa.To search locally, select Full Search.
  3. Escriba un término de búsqueda para buscar el archivo.Enter a search term to find the file. Cuando lo haya encontrado, selecciónelo.Once you've found the file, select the file.
  4. Después, seleccione una opción para determinar qué líneas de código deben incluirse en el fragmento.Next, select an option to determine which line(s) of code should be included in the snippet. Las opciones son las siguientes: Id. , Intervalo y Ninguna.The options are: ID, Range and None.
  5. En función de la selección realizada en el paso 4, puede que deba proporcionar un valor.Based on your selection from Step 4, provide a value if necessary.

Mostrar el archivo de código completo:Display entire code file:

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

Mostrar parte de un archivo de código mediante la especificación de números de línea:Display part of a code file by specifying line numbers:

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

Mostrar parte de un archivo de código mediante la especificación de un nombre de fragmento de código:Display part of a code file by specifying a snippet name:

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

En las secciones siguientes se explican estos ejemplos:The following sections explain these examples:

Para obtener más información, consulte Referencia de sintaxis de fragmentos de código, más adelante en este artículo.For more information, see Snippet syntax reference later in this article.

Ruta de acceso al archivo de códigoPath to code file

Ejemplo:Example:

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

El ejemplo procede del repositorio de documentos ASP.NET, el archivo de artículos aspnetcore/data/ef-mvc/crud.md.The example is from the ASP.NET docs repo, aspnetcore/data/ef-mvc/crud.md article file. El archivo de código se hace referencia mediante una ruta de acceso relativa a aspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs en el mismo repositorio.The code file is referenced by a relative path to aspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs in the same repository.

Números de línea seleccionadosSelected line numbers

Ejemplo:Example:

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

En este ejemplo, solo se muestran las líneas 2-24 y 26 del archivo de código StudentController.cs.This example displays only lines 2-24 and 26 of the StudentController.cs code file.

Dé preferencia a los fragmentos de código con nombre sobre los números de línea codificados de forma rígida, tal como se explica en la sección siguiente.Prefer named snippets over hard-coded line numbers, as explained in the next section.

Fragmento de código con nombreNamed snippet

Ejemplo:Example:

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

Use solo letras y caracteres de subrayado para el nombre.Use only letters and underscores for the name.

En el ejemplo se muestra la sección snippet_Create del archivo de código.The example displays the snippet_Create section of the code file. El archivo de código de este ejemplo tiene etiquetas de fragmento de código C# en los comentarios del código:The code file for this example has snippet tags in comments in the C# code:

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

Siempre que pueda, haga referencia a una sección con nombre en lugar de especificar números de línea.Whenever you can, refer to a named section rather than specifying line numbers. Las referencias de números de línea son frágiles porque los archivos de código inevitablemente cambian de manera que hacen que los números de línea cambien.Line number references are brittle because code files inevitably change in ways that make line numbers change. Y no necesariamente se le notificará de tales cambios.You don't necessarily get notified of such changes. El artículo finalmente comienza a mostrar líneas incorrectas y no tendrá ninguna idea de que algo haya cambiado.Your article eventually starts showing the wrong lines and you have no clue anything has changed.

Resaltado de líneas seleccionadasHighlighting selected lines

Ejemplo:Example:

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

El ejemplo resalta las líneas 2 y 5, contando desde el inicio del fragmento de código mostrado.The example highlights lines 2 and 5, counting from the start of the displayed snippet. Los números de línea que hay que resaltar no cuentan desde el inicio del archivo de código.Line numbers to highlight don't count from the start of the code file. En otras palabras, se resaltan las líneas 3 y 6 del archivo de código.In other words, lines 3 and 6 of the code file are highlighted.

Referencias de fragmentos de código fuera del repositorioOut-of-repo snippet references

Si el archivo de código al que quiere hacer referencia se encuentra en otro repositorio, tendrá que configurar el repositorio de código como un repositorio dependiente.If the code file you want to reference is in a different repository, set up the code repository as a dependent repository. Cuando lo haga, especifique un nombre.When you do that, you specify a name for it. Ese nombre actúa como un nombre de carpeta para las referencias de código.That name then acts like a folder name for purposes of code references.

Por ejemplo, el repositorio de documentos es Azure/azure-docs y el repositorio de código es Azure/azure-functions-durable-extension.For example, the docs repository is Azure/azure-docs, and the code repository is Azure/azure-functions-durable-extension.

En la carpeta raíz de azure-docs, agregue la siguiente sección en .openpublishing.publish.config.json:In the root folder of azure-docs, add the following section in .openpublishing.publish.config.json:

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

Ahora, cuando haga referencia a samples-durable-functions como si fuera una carpeta de azure-docs , en realidad estará haciendo referencia a la carpeta raíz del repositorio azure-functions-durable-extension.Now when you refer to samples-durable-functions as if it were a folder in azure-docs, you're actually referring to the root folder in the azure-functions-durable-extension repository.

Puede incluir código mediante el formato de tres puntos (:::), ya sea manualmente o en Visual Studio Code con la ayuda del paquete de creación docs.microsoft.com.You can include code by using the triple colon format (:::) either manually or in Visual Studio Code with the help of the docs.microsoft.com Authoring Pack.

  1. En Visual Studio Code, presione Alt + M u Opción + M y seleccione Fragmento de código.In Visual Studio Code, click Alt + M or Option + M and select Snippet.
  2. Cuando lo haya hecho, se le solicitará una búsqueda completa, una búsqueda con ámbito o una referencia entre repositorios.Once Snippet is selected, you will be prompted for Full Search, Scoped Search or Cross-Repository Reference. Para buscar en los repositorios, seleccione Referencia entre repositorios.To search across repositories, select Cross-Repository Reference.
  3. Se le proporcionará una selección de repositorios que se encuentran en .openpublishing.publish.config.json.You will be given a selection of repositories that are in .openpublishing.publish.config.json. Seleccione uno.Select a repository.
  4. Escriba un término de búsqueda para buscar el archivo.Enter a search term to find the file. Cuando lo haya encontrado, selecciónelo.Once you've found the file, select the file.
  5. Después, seleccione una opción para determinar qué líneas de código deben incluirse en el fragmento.Next, select an option to determine which line(s) of code should be included in the snippet. Las opciones son las siguientes: Id. , Intervalo y Ninguna.The options are: ID, Range and None.
  6. En función de la selección realizada en el paso 5, puede que deba proporcionar un valor.Based on your selection from Step 5, provide a value.

Su referencia de fragmento de código tendrá un aspecto similar a este:Your snippet reference will look like this:

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

En el repositorio azure-functions-durable-extension, ese archivo de código se encuentra en la carpeta samples/csx/shared.In the azure-functions-durable-extension repository, that code file is in the samples/csx/shared folder. Como se indicó anteriormente, los números de línea que hay que resaltar son relativos al inicio del fragmento de código, en lugar de al inicio del archivo.As noted earlier, line numbers for highlighting are relative to the start of the snippet rather than the start of the file.

Nota

El nombre que asigne al repositorio dependiente es relativo a la raíz del repositorio principal, pero la tilde (~) hace referencia a la raíz del conjunto de documentos.The name you assign to the dependent repository is relative to the root of the main repository, but the tilde (~) refers to the root of the doc set. La raíz del conjunto de documentos viene determinada por build_source_folder en . openpublishing.publish.config.json.The doc set root is determined by build_source_folder in .openpublishing.publish.config.json. La ruta de acceso al fragmento de código en el ejemplo anterior funciona en el repositorio Azure-docs porque build_source_folder hace referencia a la raíz del repositorio (.).The path to the snippet in the preceding example works in the azure-docs repo because build_source_folder refers to the repo root (.). Si build_source_folder fuese articles, la ruta de acceso empezaría por ~/../samples-durable-functions en lugar de ~/samples-durable-functions.If build_source_folder were articles, the path would start with ~/../samples-durable-functions instead of ~/samples-durable-functions.

Fragmentos de código interactivosInteractive code snippets

Bloques de código insertado interactivosInline interactive code blocks

Para los siguientes lenguajes, los fragmentos de código se pueden hacer ejecutables en la ventana del explorador:For the following languages, code snippets can be made executable in the browser window:

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

Cuando está habilitado el modo interactivo, los cuadros de código representados tienen un botón Probar o Ejecutar.When interactive mode is enabled, the rendered code boxes have a Try It or Run button. Por ejemplo:For example:

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

se representa de la forma siguiente:renders as follows:

New-AzResourceGroup -Name myResourceGroup -Location westeurope

Para activar esta característica en un bloque de código determinado, use un identificador de lenguaje especial.To turn on this feature for a particular code block, use a special language identifier. Las opciones disponibles son:The available options are:

  • azurepowershell-interactive: habilita Azure PowerShell Cloud Shell, como en el ejemplo anterior.azurepowershell-interactive - Enables the Azure PowerShell Cloud Shell, as in the preceding example
  • azurecli-interactive: habilita Azure Cloud Shell.azurecli-interactive - Enables the Azure Cloud Shell
  • csharp-interactive: habilita C# REPL.csharp-interactive - Enables the C# REPL

En Azure Cloud Shell y PowerShell Cloud Shell, los usuarios pueden ejecutar comandos solo en su propia cuenta de Azure.For the Azure Cloud Shell and PowerShell Cloud Shell, users can run commands against only their own Azure account.

Fragmentos de código incluidos por referenciaCode snippets included by reference

Puede habilitar el modo interactivo para fragmentos de código incluidos por referencia.You can enable interactive mode for code snippets included by reference. Estos son unos ejemplos:Here are examples:

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

Para activar esta característica en un bloque de código determinado, use el atributo interactive.To turn on this feature for a particular code block, use the interactive attribute. Los valores de atributo disponibles son los siguientes:The available attribute values are:

  • cloudshell-powershell: habilita Azure PowerShell Cloud Shell, como en el ejemplo anterior.cloudshell-powershell - Enables the Azure PowerShell Cloud Shell, as in the preceding example
  • cloudshell-bash: habilita Azure Cloud Shell.cloudshell-bash - Enables the Azure Cloud Shell
  • try-dotnet: habilita Try .NET.try-dotnet - Enables Try .NET
  • try-dotnet-class: habilita Try .NET con scaffolding de clase.try-dotnet-class - Enables Try .NET with class scaffolding
  • try-dotnet-method: habilita Try .NET. con scaffolding de método.try-dotnet-method - Enables Try .NET with method scaffolding

En Azure Cloud Shell y PowerShell Cloud Shell, los usuarios solo pueden ejecutar comandos en su propia cuenta de Azure.For the Azure Cloud Shell and PowerShell Cloud Shell, users can only run commands against their own Azure account.

Referencia de sintaxis de fragmentos de códigoSnippet syntax reference

Sintaxis:Syntax:

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

Importante

Esta sintaxis es una extensión de Markdown de bloque.This syntax is a block Markdown extension. Es decir, se debe usar en su propia línea.It must be used on its own line.

  • <language> (opcional)<language> (optional)

    • Lenguaje del fragmento de código.Language of the code snippet. Para obtener más información, vea la sección Lenguajes admitidos más adelante en este artículo.For more information, see the Supported languages section later in this article.
  • <path> (obligatorio)<path> (mandatory)

    • Ruta de acceso relativa del sistema de archivos que indica el archivo del fragmento de código al que se hace referencia.Relative path in the file system that indicates the code snippet file to reference.
  • <attribute> y <attribute-value> (opcional)<attribute> and <attribute-value> (optional)

    Se usan conjuntamente para especificar cómo se debe recuperar código del archivo y cómo se debería mostrar:Used together to specify how the code should be retrieved from the file and how it should be displayed:

    • range: 1,3-5 corresponde a un intervalo de líneas.range: 1,3-5 A range of lines. Este ejemplo incluye las líneas 1, 3, 4 y 5.This example includes lines 1, 3, 4, and 5.
    • id: snippet_Create Id. del fragmento de código que debe insertarse desde el archivo de código.id: snippet_Create The ID of the snippet that needs to be inserted from the code file. Este valor no puede coexistir con el intervalo.This value cannot co-exist with range.
    • highlight: 2-4,6 Intervalo o número de líneas que deben resaltarse en el fragmento de código generado.highlight: 2-4,6 Range and/or numbers of lines that need to be highlighted in the generated code snippet. La numeración es relativa a las líneas que se muestran (como se especifica en intervalo o identificador), no en el archivo.The numbering is relative to the lines displayed (as specified by range or id), not the file.
    • interactive: cloudshell-powershell, cloudshell-bash, try-dotnet, try-dotnet-class, try-dotnet-method El valor de cadena determina qué tipos de interactividad están habilitados.interactive: cloudshell-powershell, cloudshell-bash, try-dotnet, try-dotnet-class, try-dotnet-method String value determines what kinds of interactivity are enabled.
    • Para obtener más información sobre la presentación en archivos de origen de fragmento de código por idioma, vea las directrices de DocFX .For details about tag name representation in code snippet source files by language, see the DocFX guidelines.

Lenguajes admitidosSupported languages

El paquete de creación de Docs incluye una característica para proporcionar la finalización de instrucciones y la validación de los identificadores de idioma disponibles para los bloques de barrera de código.The Docs Authoring Pack includes a feature to provide statement completion and validation of the available language identifiers for code fence blocks.

Bloques de código delimitadosFenced code blocks

NameName Alias válidosValid aliases
CLI de .NET Core.NET Core CLI dotnetcli
1C1C 1c
ABNFABNF abnf
Registros de accesoAccess logs accesslog
AdaAda ada
Ensamblador de ARMARM assembler armasm, armarmasm, arm
Ensamblador de AVRAVR assembler avrasm
ActionScriptActionScript actionscript, asactionscript, as
AlanAlan alan, ialan, i
AngelScriptAngelScript angelscript, ascangelscript, asc
ANTLRANTLR antlr
ApacheApache apache, apacheconfapache, apacheconf
AppleScriptAppleScript applescript, osascriptapplescript, osascript
ArcadeArcade arcade
AsciiDocAsciiDoc asciidoc, adocasciidoc, adoc
AspectJAspectJ aspectj
ASPXASPX aspx
ASP.NET (C#)ASP.NET (C#) aspx-csharp
ASP.NET (VB)ASP.NET (VB) aspx-vb
AutoHotkeyAutoHotkey autohotkey
AutoItAutoIt autoit
AwkAwk awk, mawk, nawk, gawkawk, mawk, nawk, gawk
AxaptaAxapta axapta
AzCopyAzCopy azcopy
CLI de AzureAzure CLI azurecli
CLI de Azure CLI (interactiva)Azure CLI (Interactive) azurecli-interactive
Azure PowerShellAzure Powershell azurepowershell
Azure PowerShell (interactivo)Azure Powershell (Interactive) azurepowershell-interactive
BashBash bash, sh, zshbash, sh, zsh
BasicBasic basic
BNFBNF bnf
CC c
C#C# csharp, cscsharp, cs
C# (interactivo)C# (Interactive) csharp-interactive
C++C++ cpp, c, cc, h, c++, h++, hppcpp, c, cc, h, c++, h++, hpp
C++/CXC++/CX cppcx
C++/WinRTC++/WinRT cppwinrt
C/ALC/AL cal
Script de objeto de cachéCache Object Script cos, clscos, cls
CMakeCMake cmake, cmake.incmake, cmake.in
CoqCoq coq
CSPCSP csp
CSSCSS css
Cap'n ProtoCap'n Proto capnproto, capnpcapnproto, capnp
ClojureClojure clojure, cljclojure, clj
CoffeeScriptCoffeeScript coffeescript, coffee, cson, icedcoffeescript, coffee, cson, iced
CrmshCrmsh crmsh, crm, pcmkcrmsh, crm, pcmk
CrystalCrystal crystal, crcrystal, cr
Cypher (Neo4j)Cypher (Neo4j) cypher
DD d
DAX Power BIDAX Power BI dax
Archivo de zona de DNSDNS Zone file dns, zone, binddns, zone, bind
DOSDOS dos, bat, cmddos, bat, cmd
DartDart dart
DelphiDelphi delphi, dpr, dfm, pas, pascal, freepascal, lazarus, lpr, lfmdelphi, dpr, dfm, pas, pascal, freepascal, lazarus, lpr, lfm
DiffDiff diff, patchdiff, patch
DjangoDjango django, jinjadjango, jinja
DockerfileDockerfile dockerfile, dockerdockerfile, docker
dsconfigdsconfig dsconfig
DTS (árbol de dispositivos)DTS (Device Tree) dts
DustDust dust, dstdust, dst
DylanDylan dylan
EBNFEBNF ebnf
ElixirElixir elixir
ElmElm elm
ErlangErlang erlang, erlerlang, erl
ExcelExcel excel, xls, xlsxexcel, xls, xlsx
ContraerExtempore extempore, xtlang, xtmextempore, xtlang, xtm
F#F# fsharp, fsfsharp, fs
FIXFIX fix
FortranFortran fortran, f90, f95fortran, f90, f95
G-CodeG-Code gcode, ncgcode, nc
GamsGams gams, gmsgams, gms
GAUSSGAUSS gauss, gssgauss, gss
GDScriptGDScript godot, gdscriptgodot, gdscript
GherkinGherkin gherkin
GN para NinjaGN for Ninja gn, gnign, gni
GoGo go, golanggo, golang
GoloGolo golo, gololanggolo, gololang
GradleGradle gradle
GroovyGroovy groovy
HTMLHTML html, xhtmlhtml, xhtml
HTTPHTTP http, httpshttp, https
HamlHaml haml
HandlebarsHandlebars handlebars, hbs, html.hbs, html.handlebarshandlebars, hbs, html.hbs, html.handlebars
HaskellHaskell haskell, hshaskell, hs
HaxeHaxe haxe, hxhaxe, hx
HyHy hy, hylanghy, hylang
IniIni ini
Inform7Inform7 inform7, i7inform7, i7
IRPF90IRPF90 irpf90
JSONJSON json
JavaJava java, jspjava, jsp
JavaScriptJavaScript javascript, js, jsxjavascript, js, jsx
KotlinKotlin kotlin, ktkotlin, kt
KustoKusto kusto
LeafLeaf leaf
LassoLasso lasso, ls, lassoscriptlasso, ls, lassoscript
LessLess less
LDIFLDIF ldif
LispLisp lisp
LiveCode ServerLiveCode Server livecodeserver
LiveScriptLiveScript livescript, lslivescript, ls
LuaLua lua
Archivo MakeMakefile makefile, mk, makmakefile, mk, mak
MarkdownMarkdown markdown, md, mkdown, mkdmarkdown, md, mkdown, mkd
MathematicaMathematica mathematica, mma, wlmathematica, mma, wl
MatlabMatlab matlab
MaximaMaxima maxima
Lenguaje incrustado de MayaMaya Embedded Language mel
MercuryMercury mercury
Lenguaje de scripting mIRCmIRC Scripting Language mirc, mrcmirc, mrc
MizarMizar mizar
Managed Object FormatManaged Object Format mof
MojoliciousMojolicious mojolicious
MonoMonkey monkey
MoonscriptMoonscript moonscript, moonmoonscript, moon
MS Graph (interactivo)MS Graph (Interactive) msgraph-interactive
N1QLN1QL n1ql
NSISNSIS nsis
NGinxNginx nginx, nginxconfnginx, nginxconf
NimrodNimrod nimrod, nimnimrod, nim
NixNix nix
OCamlOCaml ocaml, mlocaml, ml
Objective CObjective C objectivec, mm, objc, obj-cobjectivec, mm, objc, obj-c
OpenGL Shading LanguageOpenGL Shading Language glsl
OpenSCADOpenSCAD openscad, scadopenscad, scad
Lenguaje de reglas de OracleOracle Rules Language ruleslanguage
OxygeneOxygene oxygene
PFPF pf, pf.confpf, pf.conf
PHPPHP php, php3, php4, php5, php6php, php3, php4, php5, php6
Parser3Parser3 parser3
PerlPerl perl, pl, pmperl, pl, pm
Texto sin formato no resaltadoPlaintext no highlight plaintext
PonyPony pony
PostgreSQL & PL/pgSQLPostgreSQL & PL/pgSQL pgsql, postgres, postgresqlpgsql, postgres, postgresql
PowerShellPowerShell powershell, pspowershell, ps
PowerShell (interactivo)PowerShell (Interactive) powershell-interactive
ProcesamientoProcessing processing
PrólogoProlog prolog
PropiedadesProperties properties
Búferes de protocoloProtocol Buffers protobuf
PuppetPuppet puppet, pppuppet, pp
PythonPython python, py, gyppython, py, gyp
Resultados del generador de perfiles de PythonPython profiler results profile
Q#Q# qsharp
QQ k, kdbk, kdb
QMLQML qml
RR r
Razor CSHTMLRazor CSHTML cshtml, razor, razor-cshtmlcshtml, razor, razor-cshtml
ReasonMLReasonML reasonml, rereasonml, re
RenderMan RIBRenderMan RIB rib
RenderMan RSLRenderMan RSL rsl
RoboconfRoboconf graph, instancesgraph, instances
Robot FrameworkRobot Framework robot, rfrobot, rf
Archivos de especificaciones RPMRPM spec files rpm-specfile, rpm, spec, rpm-spec, specfilerpm-specfile, rpm, spec, rpm-spec, specfile
RubyRuby ruby, rb, gemspec, podspec, thor, irbruby, rb, gemspec, podspec, thor, irb
RustRust rust, rsrust, rs
SASSAS SAS, sasSAS, sas
SCSSSCSS scss
SQLSQL sql
STEP Part 21STEP Part 21 p21, step, stpp21, step, stp
ScalaScala scala
SchemeScheme scheme
ScilabScilab scilab, sciscilab, sci
Expresión de formasShape Expressions shexc
ShellShell shell, consoleshell, console
SmaliSmali smali
SmalltalkSmalltalk smalltalk, stsmalltalk, st
SoliditySolidity solidity, solsolidity, sol
StanStan stan
StataStata stata
Texto estructuradoStructured Text iecst, scl, stl, structured-textiecst, scl, stl, structured-text
StylusStylus stylus, stylstylus, styl
SubUnitSubUnit subunit
SupercolliderSupercollider supercollider, scsupercollider, sc
SwiftSwift swift
TclTcl tcl, tktcl, tk
Terraform (HCL)Terraform (HCL) terraform, tf, hclterraform, tf, hcl
Test Anything ProtocolTest Anything Protocol tap
TeXTeX tex
ThriftThrift thrift
TOMLTOML toml
TPTP tp
TwigTwig twig, craftcmstwig, craftcms
TypeScriptTypeScript typescript, tstypescript, ts
VB.NETVB.NET vbnet, vbvbnet, vb
VBScriptVBScript vbscript, vbsvbscript, vbs
VHDLVHDL vhdl
ValaVala vala
VerilogVerilog verilog, vverilog, v
Vim ScriptVim Script vim
X++X++ xpp
Lenguaje ensamblador x86x86 Assembly x86asm
XLXL xl, taoxl, tao
xQueryXQuery xquery, xpath, xqxquery, xpath, xq
XAMLXAML xaml
XMLXML xml, xhtml, rss, atom, xjb, xsd, xsl, plistxml, xhtml, rss, atom, xjb, xsd, xsl, plist
YAMLYAML yml, yamlyml, yaml
ZephirZephir zephir, zepzephir, zep

Sugerencia

El paquete de creación de Docs,la característica de finalización del lenguaje de desarrollo, usa el primer alias válido cuando hay varios alias disponibles.The Docs Authoring Pack, Dev Lang Completion feature uses the first valid alias when multiple aliases are available.

Pasos siguientesNext steps

Para obtener información sobre cómo aplicar formato al texto para otros tipos de contenido que no sean código, vea Instrucciones para aplicar formato al texto.For information on text formatting for content types other than code, see Text formatting guidelines.