plantillas de .NET para autores

Como autor de plantillas, creará plantillas de .NET: planos técnicos que generan proyectos, archivos u otros recursos a partir de una estructura predefinida. Cuando los usuarios ejecutan dotnet new <shortName>, el motor de plantilla de .NET lee la plantilla y genera la salida en el directorio actual. Visual Studio cuadro de diálogo Crear un nuevo proyecto también usa el motor de plantillas de .NET para .NET plantillas de proyecto, por lo que las plantillas creadas para la CLI también funcionan en Visual Studio.

El SDK de .NET se incluye con plantillas integradas para puntos de partida comunes, como aplicaciones de consola, bibliotecas de clases y proyectos de ASP.NET. Además de esas plantillas integradas, puede crear sus propias plantillas y distribuirlas como paquetes NuGet.

Este artículo es una referencia para los autores de plantillas. Trata cómo se estructuran, configuran y distribuyen las plantillas. Para obtener instrucciones paso a paso para crear y empaquetar plantillas, consulte la sección Contenido relacionado .

Tipos de plantilla

El motor de plantillas de .NET admite tres tipos de plantillas: plantillas de elemento, plantillas de proyecto y plantillas de solución.

  • Las plantillas de elemento generan uno o varios archivos, como un archivo de código, un archivo de configuración u otro recurso, sin generar un proyecto completo alrededor de ellos. Por ejemplo, una plantilla de elemento podría generar un archivo de clase que agrega un conjunto de métodos de extensión o un archivo de configuración JSON que sigue un diseño estándar que usa el equipo. Para obtener información sobre cómo crear una plantilla de elemento, consulte Tutorial: Creación de una plantilla de elemento.

  • Project plantillas generan una estructura de project completa. La plantilla de proyecto de consola integrada, por ejemplo, genera un .csproj archivo, un Program.cs archivo y cualquier otro archivo que componen el proyecto. Cree una plantilla de proyecto cuando quiera proporcionar a los usuarios un punto de partida de proyecto completo en lugar de archivos individuales. Para obtener información sobre cómo crear una plantilla de proyecto, consulte Tutorial: Creación de una plantilla de proyecto.

  • Las plantillas de solución generan una solución con uno o varios proyectos. Por ejemplo, una plantilla de solución puede crear un proyecto de API emparejado con un proyecto de prueba en un solo paso.

Al crear su propia plantilla, declara su tipo mediante el tags.type campo en el archivo de template.json configuración. Los valores válidos son "project", "item"y "solution". Estos valores permiten a los usuarios filtrar los resultados cuando buscan plantillas con dotnet new search o dotnet new list.

Tip

Project y plantillas de solución aparecen en el cuadro de diálogo Visual Studio Crear un nuevo project, pero las plantillas de elemento no aparecen en el cuadro de diálogo Agregar>nuevo elemento. Los usuarios pueden acceder a plantillas de elemento desde la dotnet new CLI.

Estructura de plantilla

Una plantilla es una carpeta en el disco que contiene dos cosas: los archivos de origen de la plantilla y una subcarpeta especial .template.config . Cuando un usuario ejecuta dotnet new <shortName>, el motor de plantillas copia los archivos de origen en la ubicación de salida y aplica cualquier configuración que haya definido para la plantilla.

mytemplate/
├── console.cs
├── readme.txt
└── .template.config/
    ├── template.json
    └── icon.png

Los archivos de origen pueden ser cualquier tipo de archivo. El motor de plantillas no requiere que inserte tokens o marcadores especiales en el código fuente. Usa los archivos as-is, lo que significa que puede compilar, ejecutar y depurar el proyecto de origen de una plantilla exactamente igual que un proyecto de .NET normal. Para convertir un proyecto existente en una plantilla, agregue un .template.config/template.json archivo a la raíz del proyecto.

Opcionalmente, puede insertar tokens de sustitución vinculados a parámetros de plantilla (símbolos) directamente en archivos de origen de plantilla y nombres de archivo. Si los tokens no son código fuente válido, no puede compilar, ejecutar ni depurar el proyecto de origen antes de implementarlo como plantilla. Los tokens no afectan a los proyectos que los usuarios crean a partir de la plantilla implementada porque el motor de plantillas los reemplaza durante la creación del proyecto.

El único archivo necesario dentro .template.config de es template.json. Ese archivo indica al motor de plantillas todo lo que necesita: el nombre de la plantilla, el nombre corto, el autor, las clasificaciones y los parámetros que los usuarios pueden pasar al crear a partir de la plantilla. También puede colocar un icon.png archivo en la .template.config carpeta . El terminal no muestra iconos, pero Visual Studio muestra el icono situado junto a la plantilla en el cuadro de diálogo Crear un nuevo proyecto. Un PNG de 128×128 funciona bien.

El archivo template.json

El template.json archivo es el único elemento de configuración necesario en una plantilla. Se encuentra dentro de la .template.config carpeta y le indica al motor de plantillas cómo presentar y procesar la plantilla. En la tabla siguiente se describen los campos obligatorios y opcionales comunes:

Campo Tipo Obligatorio Description
$schema URI No Esquema JSON para template.json. Establézcalo https://json.schemastore.org/template en para habilitar IntelliSense en editores como Visual Studio Code.
author string No Autor de la plantilla.
classifications array(string) No Los usuarios de etiquetas pueden usar para buscar la plantilla con dotnet new search o dotnet new list. Estos valores aparecen en la columna Etiquetas de la lista de plantillas.
description string No Descripción de lo que crea la plantilla.
identity string Sí Identificador único de la plantilla.
name string Sí Nombre para mostrar de la plantilla que se muestra a los usuarios.
shortName string Sí Los usuarios de nombre corto pasan a dotnet new para crear a partir de la plantilla, como console o classlib.
sourceName string No Cadena de los archivos de origen y los nombres de archivo que reemplaza el motor de plantillas por el nombre que proporciona el usuario a través -n de o --name. Si el usuario no proporciona un nombre, el motor usa el nombre del directorio actual.
preferNameDirectory boolean No Cuando true y el usuario proporcionan un nombre pero ningún directorio de salida, el motor de plantillas crea un nuevo directorio con ese nombre en lugar de escribir archivos en el directorio actual. El valor predeterminado es false.
tags object No Metadatos que identifican propiedades como el idioma y el tipo de plantilla. Use tags.language para el idioma y tags.type para project, itemo solution.

Dos campos merecen atención adicional. El sourceName campo es cómo las plantillas controlan la nomenclatura: establézela en una cadena que aparece en los nombres de archivo y el código fuente (como MyTemplate), y el motor de plantillas reemplaza cada aparición por el nombre que el usuario pasa al crear la plantilla. El classifications campo controla la detectabilidad; elija etiquetas que describan con precisión el propósito de la plantilla para que los usuarios puedan encontrarlo al buscar.

Este es un mínimo template.json para una plantilla de consola:

{
  "$schema": "https://json.schemastore.org/template",
  "author": "Your Name",
  "classifications": [ "Common", "Console" ],
  "description": "Creates a console application.",
  "identity": "MyCompany.ConsoleTemplate.CSharp",
  "name": "My Console App",
  "shortName": "myconsole",
  "sourceName": "MyConsoleApp",
  "tags": {
    "language": "C#",
    "type": "project"
  }
}

El esquema completo está disponible en el almacén de esquemas JSON. Para obtener opciones de configuración avanzadas, como la inclusión de archivos condicionales, las acciones posteriores a la creación y las plantillas de varios proyectos, consulte la wiki dotnet/templating GitHub.

Parámetros de plantilla (símbolos)

La symbols sección de template.json define los parámetros que los usuarios pueden pasar al crear a partir de la plantilla. Cada símbolo se convierte en una opción de la CLI en dotnet new <shortName>, por lo que un símbolo denominado ClassName se convierte --ClassName (o -C si define un nombre corto).

Cada entrada de símbolo admite la siguiente configuración común:

Setting Description
type Debe ser "parameter" para los parámetros orientados al usuario.
description Se muestra en la plantilla ayuda a la salida cuando los usuarios ejecutan dotnet new <shortName> -?.
datatype Tipo de datos esperado, como "text", "bool"o "choice".
replaces Cadena del contenido del archivo de origen que reemplaza el motor de plantillas por el valor del parámetro.
fileRename Cadena en los nombres de archivo de origen que reemplaza el motor de plantillas por el valor del parámetro.
defaultValue Valor utilizado cuando el usuario no proporciona el parámetro .

La replaces configuración y fileRename son la forma en que los símbolos impulsan la sustitución. Cuando un usuario proporciona un valor, el motor de plantillas reemplaza cada aparición de la cadena dentro del replaces contenido del archivo y cada aparición de la fileRename cadena en los nombres de archivo. Si el usuario no proporciona un valor, defaultValue se usa en su lugar.

Por ejemplo, el símbolo siguiente permite a los usuarios establecer el nombre de clase cuando crean a partir de la plantilla. Se cambia el nombre del archivo y la clase dentro de ella se actualiza para que coincida con:

"symbols": {
  "ClassName": {
    "type": "parameter",
    "description": "The name of the code file and class.",
    "datatype": "text",
    "replaces": "StringExtensions",
    "fileRename": "StringExtensions",
    "defaultValue": "StringExtensions"
  }
}

Con este símbolo definido, un usuario puede ejecutar dotnet new <shortName> --ClassName MyHelpers para generar un archivo denominado MyHelpers.cs que contiene una clase denominada MyHelpers. Sin la marca , el archivo y la clase mantienen el nombre StringExtensionspredeterminado .

Para comprobar los parámetros que expone la plantilla, pase -? a su nombre corto después de instalarlo:

dotnet new <shortName> -?

Paquetes de plantilla

Un paquete de plantilla es un archivo NuGet (.nupkg) que agrupa una o varias de las plantillas juntas. Cuando un usuario instala el paquete de plantillas, el motor de plantillas de .NET registra cada plantilla dentro de él a la vez. Los paquetes son la manera estándar de distribuir plantillas. Publique un único paquete para NuGet.org o una fuente privada de NuGet, o comparta un archivo local .nupkg y los usuarios obtengan toda la colección con un comando.

Para compilar un paquete de plantilla, use un archivo de proyecto de C# (.csproj) configurado para actuar como un proyecto de empaquetado en lugar de como un proyecto de compilación. La configuración clave que hace que este trabajo sea:

Setting Value Purpose
PackageType Template Marca el paquete como un paquete de plantilla para que aparezca en dotnet new search los resultados.
IncludeContentInPack true Incluye archivos de contenido en el paquete NuGet.
IncludeBuildOutput false Impide que los archivos binarios compilados se agreguen al paquete.
ContentTargetFolders content Coloca las carpetas de plantilla dentro de la content carpeta del paquete NuGet, que es donde el motor de plantillas espera encontrarlos.

La templatepack plantilla de proyecto proporciona la manera más fácil de crear un proyecto de empaquetado:

  1. Instale el Microsoft. Paquete NuGet TemplateEngine.Authoring.Templates:

    dotnet new install Microsoft.TemplateEngine.Authoring.Templates

  2. Cree el proyecto de empaquetado:

    dotnet new templatepack -n <PackageName>

El proyecto generado incluye la configuración correcta .csproj , una content carpeta para las plantillas y las tareas de MSBuild para la validación de plantillas y la localización opcional.

Para ver un tutorial completo sobre cómo crear, empaquetar y publicar un paquete de plantilla, consulte Tutorial: Creación de un paquete de plantilla.

Prueba local de la plantilla

Durante el desarrollo de plantillas, instale la plantilla directamente desde su carpeta para probarla sin compilar primero un paquete. Pase la ruta de acceso al directorio que contiene la .template.config carpeta :

dotnet new install ./mytemplate/

Para ver todos los paquetes de plantilla instalados y el comando exacto para desinstalar cada uno, ejecute dotnet new uninstall sin argumentos:

dotnet new uninstall

Para desinstalar una plantilla instalada desde un directorio, pase la misma ruta de acceso de directorio que usó para instalarla:

dotnet new uninstall ./mytemplate/

Una vez que esté listo para compartir la plantilla, empaquetarla como un paquete NuGet (consulte Paquetes de plantilla) y distribuirla. Los usuarios instalan la plantilla publicada con dotnet new install y uno de los argumentos de origen siguientes:

  • Identificador de paquete NuGet, que instala la versión estable más reciente de los orígenes de NuGet configurados para el directorio actual:

    dotnet new install AdatumCorporation.ConsoleTemplate.CSharp

  • Un identificador de paquete NuGet con una dirección URL de fuente personalizada. La --nuget-source opción usa la fuente especificada, además de los orígenes de NuGet configurados, solo para esa instalación:

    dotnet new install AdatumCorporation.ConsoleTemplate.CSharp --nuget-source https://mynugetfeed.example.com/v3/index.json

  • Ruta de acceso a un archivo local .nupkg :

    dotnet new install ./AdatumCorporation.ConsoleTemplate.CSharp.1.0.0.nupkg

Warning

Las plantillas pueden ejecutar tareas de MSBuild y código arbitrario durante la creación del proyecto. Instale solo plantillas de orígenes de confianza.

Para desinstalar un paquete instalado desde un origen de NuGet o un archivo local .nupkg , use el identificador del paquete NuGet:

dotnet new uninstall AdatumCorporation.ConsoleTemplate.CSharp

Las plantillas del SDK integradas no aparecen en la lista de desinstalación y no se pueden quitar con dotnet new uninstall.

Localización de plantillas

El motor de plantillas de .NET admite la localización opcional de metadatos de plantilla. Al proporcionar archivos de localización, los hosts como dotnet new y el cuadro de diálogo Visual Studio Nuevo Project muestran el nombre, la descripción y la información de símbolos de la plantilla en el idioma del usuario en lugar del idioma original creado.

Los siguientes campos de plantilla admiten la localización:

  • name
  • author
  • description
  • Símbolo description y displayName
  • Descripción y nombre para mostrar de cada opción en un parámetro de elección
  • Después de la acción description y manualInstructions

Para agregar la localización, cree una localize subcarpeta dentro .template.config de y agregue un archivo JSON por idioma. Asigne un nombre a cada archivo templatestrings.<lang-code>.json, donde <lang-code> coincide con un nombre válido CultureInfo , como pt-BR, zh-Hanso de. Cada archivo contiene pares clave-valor donde la clave es una ruta de acceso al elemento de template.json, utilizando / como delimitador para campos anidados.

Por ejemplo, dado un elemento template.json con el siguiente contenido:

{
  "$schema": "https://json.schemastore.org/template",
  "author": "Microsoft",
  "classifications": [ "Config" ],
  "name": "EditorConfig file",
  "description": "Creates an .editorconfig file for configuring code style preferences.",
  "symbols": {
    "Empty": {
      "type": "parameter",
      "datatype": "bool",
      "defaultValue": "false",
      "displayName": "Empty",
      "description": "Creates empty .editorconfig instead of the defaults for .NET."
    }
  }
}

Un archivo de localización portugués brasileño denominado templatestrings.pt-BR.json tendría este aspecto:

{
  "author": "Microsoft",
  "name": "Arquivo EditorConfig",
  "description": "Cria um arquivo .editorconfig para configurar as preferências de estilo de código.",
  "symbols/Empty/displayName": "Vazio",
  "symbols/Empty/description": "Cria .editorconfig vazio em vez dos padrões para .NET."
}

El motor de plantillas analiza estos archivos cuando carga información de plantilla y devuelve valores localizados automáticamente en función de la referencia cultural de la interfaz de usuario actual; no se requieren pasos adicionales del usuario.

La localización es opcional. Si no incluye archivos de localización, la plantilla funciona normalmente y siempre muestra los valores de template.json. Para obtener más información, consulte la página de localización wiki dotnet/templating.

Integración de Visual Studio

Visual Studio cuadro de diálogo Crear un nuevo proyecto usa el motor de plantillas de .NET para .NET plantillas de proyecto. Las plantillas que cree para dotnet new trabajar también en Visual Studio, sin ninguna configuración adicional. Cuando un usuario instala el paquete de plantillas con dotnet new install, Visual Studio detecta y expone automáticamente esas plantillas en el cuadro de diálogo.

Project y plantillas de solución aparecen en el cuadro de diálogo Crear un nuevo project junto con las plantillas del SDK integradas. Los usuarios pueden encontrar plantillas por nombre, idioma o etiquetas desde el classifications campo del archivo de template.json la plantilla. Las clasificaciones precisas ayudan a la superficie de la plantilla en las categorías de filtro adecuadas, por lo que debe elegirlas cuidadosamente. Para dar a la plantilla una apariencia pulida en el cuadro de diálogo, agregue un icon.png elemento a la .template.config carpeta , Visual Studio lo muestra junto al nombre de la plantilla.

Las plantillas de elemento no aparecen actualmente en el cuadro de diálogo Agregar>nuevo elemento . Los usuarios todavía pueden usar plantillas de elemento con el dotnet new comando en el terminal.

Para que la plantilla se pueda detectar para Visual Studio usuarios que aún no lo han instalado, publique el paquete de plantilla en nuget.org. El cuadro de diálogo Crear un nuevo proyecto incluye una opción Instalar más plantillas desde la opción de búsqueda en línea que busca nuget.org paquetes de plantilla. Cuando un usuario instala el paquete a través de esa opción, Visual Studio usa el mismo mecanismo de instalación que dotnet new install.

Para obtener instrucciones más detalladas sobre la integración específica de Visual Studio, como controlar el criterio de ordenación de plantillas y configurar opciones adicionales específicas del IDE, consulte el repositorio template-sample de Sayed Hashimi.

Contenido relacionado

  • Last updated on