Compartir a través de

Plantillas personalizadas para dotnet new

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

Puede instalar plantillas personalizadas desde un paquete NuGet en cualquier fuente de NuGet, haciendo referencia directamente a un archivo .nupkg de NuGet o especificando un directorio del sistema de archivos que contenga la plantilla. El motor de plantillas ofrece características que 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 más información sobre cómo crear y usar plantillas personalizadas, vea How to create your own templates for dotnet new and the dotnet/templating GitHub repo Wiki.

Nota:

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

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

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 se compone de las siguientes partes:

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

Archivos y carpetas de origen

Los archivos y carpetas de origen incluyen los archivos y carpetas que quiera que use el motor de plantillas cuando se ejecute el dotnet new <TEMPLATE> comando. 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 requiere que inserte tokens especiales en el código fuente del proyecto.
  • Los archivos de código no son archivos especiales ni se modifican de ninguna manera para trabajar con el motor de plantillas. Por lo tanto, las herramientas que normalmente se usan al trabajar con proyectos también funcionan con contenido de plantilla.
  • Compile, ejecute y depure los proyectos de plantilla igual que para cualquiera de los otros proyectos.
  • Puede crear rápidamente una plantilla a partir de un proyecto existente agregando un archivo de configuración ./.template.config/template.json al proyecto.

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

Los archivos generados por la plantilla se pueden modificar en función de la lógica y la configuración que haya proporcionado en el archivo de configuración detemplate.json . El usuario puede invalidar esta configuración pasando opciones al dotnet new <TEMPLATE> comando . Un ejemplo común de lógica personalizada es proporcionar un nombre para una clase o variable en el archivo de código implementado por 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 requiere los miembros que se muestran en la tabla siguiente, lo que es suficiente para crear una plantilla funcional.

Miembro Tipo Descripción
$schema URI Esquema JSON del archivo template.json . Los editores que admiten esquemas JSON habilitan las características de edición de JSON cuando se especifica el esquema. Por ejemplo, Visual Studio Code requiere que este miembro habilite IntelliSense. Use un valor de http://json.schemastore.org/template.
author cuerda / cadena 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 generadas mediante el dotnet new list comando .
identity cuerda / cadena Un nombre único para esta plantilla.
name cuerda / cadena Nombre de la plantilla que deben ver los usuarios.
shortName cuerda / cadena Nombre abreviado predeterminado para seleccionar la plantilla que se aplica a entornos en los que el usuario especifica el nombre de la plantilla, no se selecciona a través de una GUI. Por ejemplo, el nombre corto es útil cuando se usan plantillas desde un terminal con comandos de línea de comandos.
sourceName cuerda / cadena 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 de sourceName mencionada en el archivo de configuración y la reemplazará en los nombres de archivo y en el contenido del archivo. El valor por el que se va a reemplazar se puede proporcionar mediante las -n opciones o --name mientras se ejecuta una plantilla. Si no se especifica ningún nombre, se usa el directorio actual.
preferNameDirectory Booleano Indica si se va a crear un directorio para la plantilla si se especifica el 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 se encuentra en el almacén de esquemas JSON. Para obtener más información sobre el archivo template.json , consulte la wiki de plantillas de 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 creados por Sayed Hashimi.

Ejemplo

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

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

El archivo template.json tiene el siguiente aspecto:

{
  "$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 plantilla instalable. Una vez instalado el paquete, shortName se puede usar con el dotnet new comando . Por ejemplo, dotnet new adatumconsole haría que los archivos console.cs y readme.txt salieran en la carpeta actual.

Localización de plantillas

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

Los elementos localizables de una plantilla son:

  • Nombre
  • Autor
  • Descripción
  • Símbolos
    • Descripción
    • Nombre de pantalla
    • Descripciones y nombres visibles de las opciones para los parámetros de selección
  • Acciones posteriores
    • Descripción
    • Instrucciones manuales

Los archivos de localización tienen un formato JSON y solo debe existir 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 .template-config\localize carpeta .

El 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 proporcionado por la clave.

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

Ejemplo

Por ejemplo, este es template.json archivo 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 el siguiente 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."
}

Empaquetar una plantilla en un paquete NuGet (archivo nupkg)

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

El archivo .csproj es ligeramente diferente de un archivo .csproj tradicional de code-project. Tenga en cuenta la siguiente configuración:

  1. El valor <PackageType> se agrega y se establece en Template.
  2. La <PackageVersion> configuración se agrega y se establece en un número de versión de NuGet válido.
  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 de NuGet para registrar el paquete de plantillas.
  4. Se debe establecer la configuración de metadatos genéricos: <Title>, <Authors>, <Description>y <PackageTags>.
  5. La <TargetFramework> configuración debe establecerse, aunque no se use el binario generado por el proceso de plantilla. En el ejemplo siguiente, se establece en netstandard2.0.

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

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

Una manera fácil de excluir todos los archivos de código de la compilación del proyecto de plantilla es mediante el uso del <Compile Remove="**\*" /> elemento del archivo de proyecto, dentro de un <ItemGroup> elemento.

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

Este es un archivo .csproj de ejemplo que sigue todas estas instrucciones. Empaqueta la carpeta hija templates en la carpeta del paquete de contenido 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 ejemplo siguiente se muestra la estructura de archivos y carpetas del uso de .csproj para crear un paquete de plantilla. 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 detemplate.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 plantilla

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

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

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

dotnet new install <NUGET_PACKAGE_ID>

Para instalar un paquete de plantilla 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 plantilla 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 plantilla desde un directorio del sistema de archivos

Las plantillas se pueden instalar desde una carpeta de plantilla, como la carpeta mytemplate1 del ejemplo anterior. Especifique la ruta de la carpeta .template.config. No es necesario que la ruta de acceso al directorio de plantilla sea absoluta.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Obtener una lista de paquetes de plantilla instalados

El comando uninstall, sin ningún otro parámetro, enumera todos los paquetes de plantilla 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 elementos después de Currently installed items: son los identificadores utilizados en la desinstalación de un paquete de plantilla. Y, en el ejemplo anterior, se muestra Microsoft.Azure.WebJobs.ProjectTemplates. Si el paquete de plantilla se instaló mediante una ruta de acceso del sistema de archivos, este identificador es la ruta de acceso de carpeta de la carpeta .template.config . En la lista solo se muestran los paquetes de plantilla instalados a través de dotnet new install. No se muestran los paquetes de plantilla integrados en el SDK de .NET.

Desinstalación de un paquete de plantilla

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

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

dotnet new uninstall <NUGET_PACKAGE_ID>

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

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Creación de un proyecto mediante una plantilla personalizada

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

dotnet new <TEMPLATE>

Consulte también