Plantillas personalizadas para dotnet new

  • Artículo

El SDK de .NET cuenta con muchas plantillas ya instaladas y listas para su uso. El comando dotnet new no es solo la forma de usar una plantilla, sino también cómo instalarlas y desinstalarlas. Puede crear plantillas personalizadas propias para cualquier tipo de proyecto, como una aplicación, un servicio, una herramienta o una biblioteca de clases. Incluso puede crear una plantilla que genere uno o más archivos independientes, como un archivo de configuración.

Puede instalar plantillas personalizadas desde un paquete NuGet en cualquier fuente NuGet, haciendo referencia a un archivo .nupkg de NuGet directamente o especificando un directorio del sistema de archivos que contenga la plantilla. El motor de plantillas ofrece características que le permiten reemplazar valores, incluir y excluir archivos y ejecutar operaciones de procesamiento personalizadas cuando se usa la plantilla.

El motor de plantillas es de código abierto, y el repositorio de código en línea está en dotnet/templating en GitHub. Puede encontrar más plantillas, incluidas plantillas de terceros, mediante dotnet new search. Para obtener información sobre cómo crear y usar plantillas personalizadas, vea Cómo crear sus propias plantillas para dotnet new y la Wiki del repositorio de GitHub dotnet/templating.

Nota:

Los ejemplos de plantillas están disponibles en el repositorio de GitHub dotnet/templating.

Para seguir un tutorial y crear una plantilla, vea el tutorial Creación de una plantilla personalizada para dotnet new.

Plantillas predeterminadas .NET

Cuando instala el SDK de .NET, recibe más de una docena de plantillas integradas para crear proyectos y archivos, incluidas aplicaciones de consola, bibliotecas de clases, proyectos de prueba unitaria, aplicaciones de ASP.NET Core (incluidos los proyectos Angular y React) y archivos de configuración. Para enumerar las plantillas integradas, ejecute el comando dotnet new list:

dotnet new list

Configuración

Una plantilla consta de las siguientes partes:

  • Archivos de origen y carpetas.
  • Un archivo de configuración (template.json).

Archivos de origen y carpetas

Los archivos de origen y las carpetas incluyen todos los archivos y carpetas que quiera que el motor de plantilla use cuando se ejecuta el comando dotnet new <TEMPLATE>. El motor de plantillas está diseñado para usar proyectos ejecutables como código fuente para generar proyectos. Esto presenta varias ventajas:

  • El motor de plantillas no necesita que inserte tokens especiales en su código de origen del proyecto.
  • Los archivos de código no son archivos especiales ni se modifican de ninguna manera para que funcionen con el motor de plantillas. Por lo tanto, las herramientas que usa normalmente para trabajar con los proyectos también funcionan con el contenido de la plantilla.
  • Compile, ejecute y depure sus proyectos de plantilla de la forma en que lo hace para cualquiera de sus otros proyectos.
  • Puede crear rápidamente una plantilla de un proyecto existente simplemente agregando un archivo de configuración ./.template.config/template.json al proyecto.

Los archivos y las carpetas que se almacenan en la plantilla no se limitan a tipos de proyectos .NET formales. Los archivos de origen y las carpetas pueden constar de cualquier contenido que quiera crear cuando se use la plantilla, incluso si el motor de plantillas genera solo un archivo como su salida.

Los archivos que genera la plantilla se pueden modificar según la lógica y la configuración que ha proporcionado en el archivo de configuración template.json. El usuario puede invalidar esta configuración pasando las opciones al comando dotnet new <TEMPLATE>. Un ejemplo común de una lógica personalizada es proporcionar un nombre para una clase o variable en el archivo de código que se implementa mediante una plantilla.

template.json

El archivo template.json se coloca en una carpeta .template.config en el directorio raíz de la plantilla. El archivo proporciona información de configuración al motor de plantillas. La configuración mínima necesita los miembros que se muestran en la tabla siguiente, que es suficiente para crear una plantilla funcional.

Miembro Tipo Descripción
$schema Identificador URI El esquema JSON para el archivo template.json. Los editores que admiten los esquemas JSON habilitan las características de edición JSON cuando se especifica el esquema. Por ejemplo, Visual Studio Code necesita este miembro para habilitar IntelliSense. Use un valor de http://json.schemastore.org/template.
author cadena El autor de la plantilla.
classifications array(string) Cero o más características de la plantilla que un usuario puede usar para buscar la plantilla al buscarla. Las clasificaciones también aparecen en la columna Etiquetas cuando aparece en una lista de plantillas que se han generado mediante el comando dotnet new list.
identity cadena Un nombre único para esta plantilla.
name cadena El nombre de la plantilla que los usuarios deben ver.
shortName cadena Un nombre abreviado predeterminado para seleccionar la plantilla que se aplica a entornos donde el usuario especifica el nombre de la plantilla; no se selecciona mediante una GUI. Por ejemplo, un nombre abreviado es útil al usar plantillas desde un símbolo del sistema con comandos de la CLI.
sourceName string Nombre del árbol de origen que se va a reemplazar por el nombre que especifica el usuario. El motor de plantillas buscará cualquier aparición del valor sourceName mencionado en el archivo de configuración y la reemplazará en los nombres de archivo y en el contenido del archivo. El valor con el que se reemplazará se puede proporcionar usando las opciones -n o --name mientras se ejecuta una plantilla. Si no se especifica ningún nombre, se usa el directorio actual.
preferNameDirectory Boolean Indica si se debe crear un directorio para la plantilla si se especifica un nombre pero no se establece un directorio de salida (en lugar de crear el contenido directamente en el directorio actual). El valor predeterminado es false.

El esquema completo del archivo template.json puede encontrarse en el Almacenamiento del esquema JSON. Para más información sobre el archivo template.json, consulte la wiki de plantillas dotnet. Para obtener ejemplos más detallados e información sobre cómo hacer que las plantillas sean visibles en Visual Studio, consulte los recursos que ha preparado Sayed Hashimi.

Ejemplo

Por ejemplo, esta es una carpeta de plantillas que tiene dos archivos de contenido: console.cs y readme.txt. También existe la carpeta requerida denominada .template.config que contiene el archivo template.json.

└───mytemplate
    │   console.cs
    │   readme.txt
    │
    └───.template.config
            template.json

El archivo template.json tiene un aspecto parecido al siguiente:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Travis Chau",
  "classifications": [ "Common", "Console" ],
  "identity": "AdatumCorporation.ConsoleTemplate.CSharp",
  "name": "Adatum Corporation Console Application",
  "shortName": "adatumconsole"
}

La carpeta mytemplate es un paquete de plantillas instalable. Una vez instalado el paquete, shortName se puede utilizar con el comando dotnet new. Por ejemplo, dotnet new adatumconsole generaría los archivos console.cs y readme.txt en la carpeta actual.

Localización de plantillas

Las plantillas de .NET son localizables. Si se localiza una plantilla en el idioma que coincide con la configuración regional actual, sus elementos aparecerán en el mismo idioma que la CLI. Al crear plantillas, la localización es opcional.

Los elementos localizables de una plantilla son:

  • Nombre
  • Autor
  • Descripción
  • Símbolos
    • Descripción
    • Display Name (Nombre para mostrar)
    • Las descripciones y el nombre para mostrar de las opciones de los parámetros de elección
  • Acciones relacionadas con la publicación
    • Descripción
    • Instrucciones manuales

Los archivos de localización están en formato JSON y solo puede haber un archivo por referencia cultural. La convención de nomenclatura es: templatestrings.<lang code>.json, donde lang code corresponde a una de las opciones CultureInfo . Todos los archivos de localización deben estar dentro de la carpeta .template-config\localize.

El archivo JSON de localización consta de pares clave-valor:

  • La clave es la referencia a un elemento de template.json que se va a localizar. Si el elemento es un elemento secundario, use la ruta de acceso completa con un delimitador /.
  • El valor es la cadena de localización del elemento que la clave proporciona.

Para más información sobre la localización de plantillas, consulte la página de localización de la wiki de plantillas dotnet.

Ejemplo

Por ejemplo, este es el archivo template.json con algunos campos localizables:

{
  "$schema": "http://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."
    }
  }
}

Y algunos campos se van a localizar a portugués de Brasil. El nombre de archivo será templatestrings.pt-BR.json para que coincida con la referencia cultural y 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."
}

Empaquetado de una plantilla en un paquete NuGet (archivo nupkg)

Una plantilla personalizada se empaqueta con el comando la dotnet pack y un archivo .csproj. Como alternativa, se puede usar NuGet con el comando nuget pack junto con un archivo .nuspec. Pero NuGet necesita .NET Framework en Windows y Mono en Linux y macOS.

El archivo .csproj es ligeramente diferente al archivo .csproj de un proyecto de código tradicional. Tenga en cuenta la siguiente configuración:

  1. El valor <PackageType> se agrega y se establece en Template.
  2. El valor <PackageVersion> se agrega y establece en un número de versión de NuGet.
  3. El valor <PackageId> se agrega y se establece en un identificador único. Este identificador se usa para desinstalar el paquete de plantillas y lo usan las fuentes NuGet para registrar su paquete de plantillas.
  4. Se debe establecer la configuración de metadatos genérica: <Title>, <Authors>, <Description> y <PackageTags>.
  5. Debe establecerse la configuración <TargetFramework>, aunque no se usen los datos binarios generados por el proceso de la plantilla. En el ejemplo siguiente se establece en netstandard2.0.

Un paquete de plantillas, en forma de paquete NuGet .nupkg, requiere que todas las plantillas se almacenen en la carpeta content dentro del paquete. Hay algunas opciones de configuración más para agregar a un archivo .csproj para asegurarse de que el paquete .nupkg generado se puede instalar como un paquete de plantilla:

  1. El valor <IncludeContentInPack> se establece en true para incluir cualquier archivo que el proyecto establece como content en el paquete NuGet.
  2. El valor <IncludeBuildOutput> se establece en false para excluir todos los archivos binarios generados por el compilador desde el paquete NuGet.
  3. El valor <ContentTargetFolders> se establece en content. Esto garantiza que los archivos establecidos como content se almacenan en la carpeta content carpeta en el paquete NuGet. Esta carpeta del paquete NuGet la analiza el sistema de plantillas dotnet.

Una manera sencilla de excluir todos los archivos de código para que el proyecto de su plantilla no los compile es usando el elemento <Compile Remove="**\*" /> del archivo de proyecto, dentro de un elemento <ItemGroup>.

Una manera sencilla de estructurar su paquete de plantillas es colocar todas las plantillas en carpetas individuales y luego cada carpeta de plantillas dentro de una carpeta templates que se encuentra en el mismo directorio que el archivo .csproj . De esta manera, puede usar un solo elemento del proyecto para incluir todos los archivos y carpetas en templates como content. Dentro de un elemento <ItemGroup>, cree un elemento <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />.

Este es un archivo .csproj de ejemplo que sigue estas las pautas. Empaqueta la carpeta secundaria templates en la carpeta del paquete content y excluye cualquier archivo de código de la compilación.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <PackageType>Template</PackageType>
    <PackageVersion>1.0</PackageVersion>
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <Title>AdatumCorporation Templates</Title>
    <Authors>Me</Authors>
    <Description>Templates to use when creating an application for Adatum Corporation.</Description>
    <PackageTags>dotnet-new;templates;contoso</PackageTags>
    <TargetFramework>netstandard2.0</TargetFramework>

    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />
    <Compile Remove="**\*" />
  </ItemGroup>

</Project>

En el siguiente ejemplo se muestra la estructura de archivos y carpetas de usar .csproj para crear un paquete de plantillas. El archivo MyDotnetTemplates.csproj y la carpeta templates se encuentran en la raíz de un directorio denominado project_folder. La carpeta templates contiene dos plantillas: mytemplate1 y mytemplate2. Cada plantilla tiene archivos de contenido y una carpeta .template.config con un archivo de configuración template.json.

project_folder
│   MyDotnetTemplates.csproj
│
└───templates
    ├───mytemplate1
    │   │   console.cs
    │   │   readme.txt
    │   │
    │   └───.template.config
    │           template.json
    │
    └───mytemplate2
        │   otherfile.cs
        │
        └───.template.config
                template.json

Nota:

Para asegurarse de que el paquete de plantillas aparece en el resultado de dotnet new search, establezca el tipo de paquete NuGet en Template.

Instalación de un paquete de plantillas

Use el comando dotnet new install para instalar un paquete de plantillas.

Para instalar un paquete de plantillas desde un paquete NuGet almacenado en nuget.org

Use el identificador del paquete NuGet para instalar un paquete de plantillas.

dotnet new install <NUGET_PACKAGE_ID>

Instalación de un paquete de plantillas desde un origen de NuGet personalizado

Proporcione un origen de NuGet personalizado (por ejemplo, https://api.my-custom-nuget.com/v3/index.json).

dotnet new install <NUGET_PACKAGE_ID> --nuget-source <SOURCE>

Para instalar un paquete de plantillas desde un archivo nupkg local

Proporcione la ruta de acceso a un archivo de paquete NuGet .nupkg.

dotnet new install <PATH_TO_NUPKG_FILE>

Para instalar un paquete de plantillas desde un directorio del sistema de archivos

Las plantillas se pueden instalar desde una carpeta de plantillas, como la carpeta mytemplate1 del ejemplo anterior. Especifique la ruta de acceso de la carpeta .template.config. La ruta de acceso al directorio de plantillas no tiene por qué ser absoluta.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Obtención de una lista de los paquetes de plantillas instalados

El comando de desinstalación, sin ningún otro parámetro, enumera todos los paquetes de plantillas instalados y las plantillas incluidas.

dotnet new uninstall

Ese comando devuelve algo similar a la salida siguiente:

Currently installed items:
   Microsoft.Azure.WebJobs.ProjectTemplates
      Version: 4.0.1942
      Details:
         Author: Microsoft
         NuGetSource: https://api.nuget.org/v3/index.json
      Templates:
         Azure Functions (func) C#
         Azure Functions (func) F#
      Uninstall Command:
         dotnet new uninstall Microsoft.Azure.WebJobs.ProjectTemplates
...

El primer nivel de los elementos situados después de Currently installed items: son los identificadores que se usan en la desinstalación de un paquete de plantillas. Y, en el ejemplo anterior, se muestra Microsoft.Azure.WebJobs.ProjectTemplates. Si el paquete de plantillas se instaló mediante una ruta de acceso del sistema de archivos, este identificador es la ruta de acceso de la carpeta .template.config. Solo los paquetes de plantillas instalados mediante dotnet new install se muestran en la lista. No se muestran los paquetes de plantillas integrados en el SDK de .NET.

Desinstalación de un paquete de plantillas

Use el comando dotnet new uninstall para desinstalar un paquete de plantillas.

Si el paquete lo instaló una fuente de NuGet o un archivo .nupkg directamente, proporcione el identificador.

dotnet new uninstall <NUGET_PACKAGE_ID>

Si el paquete se instaló mediante la especificación de una ruta de acceso a la carpeta .template.config, use esa ruta de acceso para desinstalarlo. Puede ver la ruta de acceso absoluta del paquete de plantillas en la salida proporcionada por el comando dotnet new uninstall. Para más información, consulte la sección Obtención de una lista de plantillas instaladas.

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Crear un proyecto con una plantilla personalizada

Después de que se instale una plantilla, use la plantilla ejecutando el comando dotnet new <TEMPLATE> como lo haría con cualquier otra plantilla preinstalada. También puede especificar opciones en el comando dotnet new, incluidas las opciones específicas de plantilla que ha definido en la configuración de la plantilla. Proporcione el nombre breve de la plantilla directamente al comando:

dotnet new <TEMPLATE>

Vea también