Hay varias maneras de incluir código en un artículo publicado en Microsoft Learn que no son las capturas de pantalla:
Elementos individuales (palabras) dentro de una línea.
Este es un ejemplo de estilo code.
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. El formato de código también se puede usar para las propiedades, los métodos, las clases y las palabras clave del lenguaje. Para obtener más información, consulte Elementos de código, más adelante en este artículo.
Bloques de código en el archivo Markdown del artículo.
```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. Para obtener más información, consulte Bloques de código, más adelante en este artículo.
Bloques de código por referencia a un archivo de código del repositorio local.
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. No siempre resulta obvio lo que se califica como código. Por ejemplo, los nombres de paquetes NuGet deben tratarse como código. En caso de duda, consulte Instrucciones para la aplicación de formato al texto.
Estilo de código insertado
Para incluir un elemento de código en el texto del artículo, debe delimitarlo entre acentos graves (`) para indicar estilo de código.
El estilo de código insertado no debe usar el formato de marca de graduación triple.
Markdown.
Representado
De forma predeterminada, Entity Framework interpreta una propiedad con el nombre `Id` o `ClassnameID` como clave principal.
De forma predeterminada, Entity Framework interpreta como la clave principal una propiedad que se denomine Id o ClassnameID.
Cuando un artículo se localiza (se traduce a otros idiomas), el texto con estilo de código se deja sin traducir. Si quiere evitar la localización sin usar el estilo de código, vea Cadenas no localizadas.
Estilo negrita
Algunas guías de estilo antiguas especifican la negrita para el código insertado. La negrita es una opción cuando el estilo de código es tan molesto que puede poner en peligro la legibilidad. 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. Si decide usar el estilo negrita, utilice la sintaxis de cadenas no localizadas para asegurarse de que el código no está localizado.
Vínculos
En algunos contextos puede ser más útil un vínculo a la documentación de referencia que el formato de código. Si usa un vínculo, no aplique el formato de código al texto del vínculo. Si aplica el estilo código a un vínculo, puede que sea difícil identificarlo como tal.
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. Por ejemplo:
The first reference to <xref:System.CommandLine> in this text is a link.
Subsequent references to `System.CommandLine` can be in code style.
Representado:
La primera referencia a System.CommandLine en este texto es un vínculo.
Las referencias posteriores a System.CommandLine pueden figurar en estilo de código.
Marcadores de posición
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 corchetes angulares. Por ejemplo:
az group delete -n <ResourceGroupName>
Puede que vea que los corchetes deben quitarse al sustituir valores reales. La Guía de estilo de escritura de Microsoft indica que se debe usar la cursiva, a la que puede dar formato dentro del código insertado entre corchetes angulares:
<ResourceGroupName> es el grupo de recursos en el que...
Las llaves { } no se recomiendan para su uso como marcadores de posición sintácticos. Se pueden confundir con la misma notación usada en texto reemplazable, cadenas de formato, interpolación de cadenas, plantillas de texto y construcciones de programación similares.
Los nombres de marcador de posición se pueden separar por guiones ("kebab case"), con guiones bajos o sin separarlos ("Pascal case"). El uso de kebab case puede generar errores de sintaxis y los guiones bajos pueden entrar en conflicto con el subrayado. Usar todo en mayúsculas puede entrar en conflicto con las constantes con nombre en muchos idiomas, aunque también puede llamar la atención sobre el nombre del marcador de posición.
<Resource-Group-Name> o <ResourceGroupName>
Bloques de código
La sintaxis para incluir código en un documento depende de dónde se encuentre el código:
Todos los métodos enumerados en la sección anterior tienen como resultado bloques de código que se pueden usar:
Puede copiar y pegar de ellos.
Están indexados por motores de búsqueda.
Son accesibles para los lectores de pantalla.
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. Use capturas de pantalla del IDE solo para el código si está mostrando algo sobre el propio IDE, como IntelliSense. No use capturas de pantallas solo para mostrar el color y el resaltado.
Validación de código
Algunos repositorios han implementado procesos que compilan automáticamente todos los códigos de ejemplo para comprobar si hay errores. El repositorio de .NET lo hace. Para obtener más información, consulte Contribución en el repositorio. NET.
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.
Resaltado
Los fragmentos de código suelen incluir más código del necesario para proporcionar contexto. La legibilidad mejora si se resaltan las líneas clave en las que se está centrando en el fragmento, como en este ejemplo:
No se puede resaltar el código cuando se incluye en el archivo Markdown del artículo. Solo funciona con los fragmentos de código incluidos por referencia en un archivo de código.
Barras de desplazamiento horizontal
Divida las líneas largas para evitar las barras de desplazamiento horizontal. Las barras de desplazamiento en los bloques de código hacen que el código resulte difícil de leer. 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.
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, pero tenga en cuenta que la presencia o ausencia de una barra de desplazamiento no es el único criterio de legibilidad. 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.
Identificación clara de código no correcto
En algunos casos, resulta útil señalar patrones de programación que se deben evitar, por ejemplo:
Código que provocará un error del compilador.
Código que se compilará correctamente, pero no se recomienda.
Para estos casos:
Explique el error tanto en los comentarios de código como en el texto del artículo.
A menudo, los lectores omiten el texto del artículo y solo ven el código, por lo que no basta con explicar el error solo en el texto del artículo. Tampoco basta con explicar el error solo en los comentarios de código, ya que los comentarios de código no se localizan.
Le recomendamos que comente el código si provocaría un error del compilador.
El código comentado no interrumpirá el sistema de integración continua (CI) si el repositorio del artículo tiene uno en la actualidad o implementa uno en el futuro.
Para obtener un ejemplo de cómo presentar código que no se recomienda, vea Ejemplo de uso de Rune: cambio de mayúsculas y minúsculas. En este ejemplo, el consejo para evitarlo está integrado incluso en el propio código, ya que el nombre del método de C# es ConvertToUpperBadExample.
Bloques de código insertado
Use bloques de código insertados únicamente cuando no resulte práctico mostrar código por referencia a un archivo de código. 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. Además, el código insertado puede omitir el contexto que podría ayudar al desarrollador a entender y usar el código. Estas consideraciones se aplican principalmente a los lenguajes de programación. 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).
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 delimitación de tres acentos graves (```) o mediante el sangrado. La barrera es preferible porque le permite especificar el lenguaje. 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.
Los indicadores de lenguaje se colocan inmediatamente después de los tres acentos graves de apertura, como en el siguiente ejemplo:
GitHub Flavored Markdown admite la delimitación de bloquees de código con tildes (~) o con acentos graves (`).
El símbolo utilizado para abrir y cerrar el bloque de código debe ser coherente dentro del mismo bloque de código.
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.
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. Siempre que sea posible, use un indicador de idioma o de entorno en los bloques de código insertado.
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. Si es así, cámbielas de nuevo a las comillas normales (' y "). Como alternativa, usa la característica de reemplazo de comillas inteligentes del paquete de creación de Learn.
Referencias de fragmentos de código en el repositorio
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. 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. Puedes 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 de Learn.
En Visual Studio Code, presione Alt + M u Opción + M y seleccione Fragmento de código.
Cuando lo haya hecho, se le solicitará una búsqueda completa, una búsqueda con ámbito o una referencia entre repositorios. Para buscar de forma local, seleccione Búsqueda completa.
Escriba un término de búsqueda para buscar el archivo. Cuando lo haya encontrado, selecciónelo.
Después, seleccione una opción para determinar qué líneas de código deben incluirse en el fragmento. Las opciones son: Id., Intervalo y Ninguna.
En función de la selección realizada en el paso 4, puede que deba proporcionar un valor.
En este ejemplo, solo se muestran las líneas 2-24 y 26 del archivo de código StudentController.cs.
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.
Use solo letras y caracteres de subrayado para el nombre.
En el ejemplo se muestra la sección snippet_Create del archivo de código. El archivo de código de este ejemplo tiene etiquetas de fragmento de código C# en los comentarios del código:
// code excluded from the snippet
// <snippet_Create>
// code included in the snippet
// </snippet_Create>
// code excluded from the snippet
Los fragmentos de código con nombre se pueden anidar, como se muestra en el ejemplo siguiente:
// <Method>
public static void SomeMethod()
{
// <Line>
// Single line of code.
// </Line>
}
// </Method>
Cuando se representa el fragmento de código Method, las etiquetas Line no se incluyen en la salida representada.
Siempre que pueda, haga referencia a una sección con nombre en lugar de especificar números de línea. 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.
Y no necesariamente se le notificará de tales cambios. El artículo finalmente comienza a mostrar líneas incorrectas y no tendrá ninguna idea de que algo haya cambiado.
El ejemplo resalta las líneas 2 y 5, contando desde el inicio del fragmento de código mostrado. Los números de línea que hay que resaltar no cuentan desde el inicio del archivo de código. En otras palabras, se resaltan las líneas 3 y 6 del archivo de código.
Referencias de fragmentos de código fuera del repositorio
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. Cuando lo haga, especifique un nombre. Ese nombre actúa como un nombre de carpeta para las referencias de código.
Por ejemplo, el repositorio de documentos es Azure/azure-docs y el repositorio de código es Azure/azure-functions-durable-extension.
En la carpeta raíz de azure-docs, agregue la siguiente sección en .openpublishing.publish.config.json:
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.
Puedes 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 de Learn.
En Visual Studio Code, presione Alt + M u Opción + M y seleccione Fragmento de código.
Cuando lo haya hecho, se le solicitará una búsqueda completa, una búsqueda con ámbito o una referencia entre repositorios. Para buscar en los repositorios, seleccione Referencia entre repositorios.
Se le proporcionará una selección de repositorios que se encuentran en .openpublishing.publish.config.json. Seleccione uno.
Escriba un término de búsqueda para buscar el archivo. Cuando lo haya encontrado, selecciónelo.
Después, seleccione una opción para determinar qué líneas de código deben incluirse en el fragmento. Las opciones son: Id., Intervalo y Ninguna.
En función de la selección realizada en el paso 5, puede que deba proporcionar un valor.
Su referencia de fragmento de código tendrá un aspecto similar a este:
En el repositorio azure-functions-durable-extension, ese archivo de código se encuentra en la carpeta samples/csx/shared. 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.
Nota
El nombre que asignes 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. La raíz del conjunto de documentos viene determinada por build_source_folder en .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 (.). Si build_source_folder fuese articles, la ruta de acceso empezaría por ~/../samples-durable-functions en lugar de ~/samples-durable-functions.
Fragmentos de código en un cuaderno de Jupyter Notebook
Puede hacer referencia a una celda de un cuaderno de Jupyter Notebook como un fragmento de código. Para hacer referencia a una celda, siga estos pasos:
Agregue al cuaderno los metadatos de las celdas a las que quiera hacer referencia.
Configure el acceso al repositorio.
Use la sintaxis de los fragmentos de código de cuadernos de Jupyter Notebook en su archivo Markdown.
Adición de metadatos a un cuaderno
Ponga un nombre a la celda agregando los metadatos de celda correspondientes en el cuaderno de Jupyter Notebook.
En Jupyter, puede editar metadatos de celda si primero habilita la barra de herramientas de celda: Ver > Barra de herramientas de celda > Editar metadatos.
Una vez que la barra de herramientas de celda esté habilitada, seleccione Editar metadatos en la celda a la que quiera poner un nombre.
También puede editar los metadatos directamente en la estructura JSON del cuaderno.
En los metadatos de la celda, agregue el atributo "name":
"metadata": {"name": "<name>"},
Por ejemplo:
"metadata": {"name": "workspace"},
Sugerencia
Puede agregar otros metadatos que quiera que le ayuden a realizar un seguimiento de dónde se está usando una celda concreta. Por ejemplo:
Si el archivo de cuaderno al que quiere hacer referencia se encuentra en otro repositorio, tendrá que configurar el repositorio de código como un repositorio dependiente.
Hacer referencia a la sintaxis de fragmentos de código de cuadernos de Jupyter Notebook
Una vez que el cuaderno contenga los metadatos necesarios, haga referencia a él en el archivo Markdown. Use el valor <cell-name-value> que ha agregado al cuaderno y el valor <path> que ha configurado un repositorio dependiente.
```csharp-interactive
var aFriend = "Maria";
Console.WriteLine($"Hello {aFriend}");
```
se representa como:
var aFriend = "Maria";
Console.WriteLine($"Hello {aFriend}");
Para activar esta característica en un bloque de código determinado, use un identificador de lenguaje especial. Las opciones disponibles son:
azurepowershell-interactive: habilita Azure PowerShell Cloud Shell, como en el ejemplo anterior.
azurecli-interactive: habilita Azure Cloud Shell.
csharp-interactive: habilita C# REPL.
En Azure Cloud Shell y PowerShell Cloud Shell, los usuarios pueden ejecutar comandos solo en su propia cuenta de Azure.
Fragmentos de código incluidos por referencia
Puede habilitar el modo interactivo para fragmentos de código incluidos por referencia.
Para activar esta característica en un bloque de código determinado, use el atributo interactive. Los valores de atributo disponibles son los siguientes:
cloudshell-powershell: habilita Azure PowerShell Cloud Shell, como en el ejemplo anterior.
cloudshell-bash: habilita Azure Cloud Shell.
try-dotnet: habilita Try .NET.
try-dotnet-class: habilita Try .NET con scaffolding de clase.
try-dotnet-method: habilita Try .NET. con scaffolding de método.
En Azure Cloud Shell y PowerShell Cloud Shell, los usuarios solo pueden ejecutar comandos en su propia cuenta de Azure.
Para la experiencia de .NET Interactive, el contenido de su bloque de código depende de cuál de las tres experiencias de scaffolding elija:
Sin scaffolding (try-dotnet): el bloque de código debe representar un texto de programa completo. Por ejemplo, el archivo Program.cs generado por dotnet new console sería válido. Son muy útiles para mostrar un programa pequeño completo, incluidas las directivas using necesarias. Las declaraciones de nivel superior no se admiten en este momento.
Scaffolding de método (try-dotnet-method): el bloque de código debe representar el contenido de un método Main en una aplicación de consola. Puede asumir las directivas using agregadas por la plantilla dotnet new console. Esta configuración es más útil para fragmentos cortos que demuestran una función.
Scaffolding de clase (try-dotnet-class): el bloque de código debe representar una clase con un método Main como punto de entrada del programa. Se pueden utilizar para mostrar cómo interactúan los miembros de una clase.
Esta sintaxis es una extensión de Markdown de bloque. Es decir, se debe usar en su propia línea.
<language> (opcional)
Lenguaje del fragmento de código. Para obtener más información, vea la sección Lenguajes admitidos más adelante en este artículo.
<path> (obligatorio)
Ruta de acceso relativa en el sistema de archivos que indica el archivo de fragmento de código al que se va a hacer referencia.
<attribute> y <attribute-value> (opcional)
Se usan conjuntamente para especificar cómo se debe recuperar código del archivo y cómo se debería mostrar:
range: 1,3-5 Un intervalo de líneas. Este ejemplo incluye las líneas 1, 3, 4 y 5.
id: Create Id. del fragmento de código que debe insertarse desde el archivo de código. Este valor no puede coexistir con range.
highlight: 2-4,6 Intervalo o número de líneas que deben resaltarse en el fragmento de código generado. La numeración es relativa a las líneas que se muestran (como se especifica en intervalo o identificador), no en el archivo.
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.
Para detalles sobre la representación de un nombre de etiqueta en los archivos de código fuente de un fragmento de código por lenguaje, consulte las instrucciones de DocFX.
Idiomas compatibles
El paquete de creación de Learn 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.
Use bloques de código con mayor confianza y comprenda cómo influyen en la visibilidad y la accesibilidad de las construcciones de nivel superior e inferior del código.