Compartir a través de

Tutorial: Creación de un paquete de plantillas

  • Artículo

Con .NET, puede crear e implementar plantillas que generan proyectos, archivos e inclusos recursos. Este tutorial es el tercero de una serie que enseña a crear, instalar y desinstalar plantillas para usarlas con el comando dotnet new.

Puede ver la plantilla completada en el repositorio de GitHub de ejemplos de .NET.

En esta parte de la serie, aprenderá a:

  • Creación de un paquete de plantillas mediante el paquete NuGet Microsoft.TemplateEngine.Authoring.Templates.
  • Instalar un paquete de plantilla desde un archivo de paquete NuGet.
  • Desinstalar un paquete de plantillas por identificador de paquete.
  • Crear un proyecto *.csproj para compilar un paquete de plantillas.
  • Configurar el archivo del proyecto para el empaquetado.
  • Instalar un paquete de plantilla desde un archivo de paquete NuGet.
  • Desinstalar un paquete de plantillas por identificador de paquete.

Requisitos previos

  • Complete la parte 1 y la parte 2 de esta serie de tutoriales.

    En este tutorial se usan las dos plantillas que se crearon en las dos primeras partes de esta serie de tutoriales. Puede usar otra plantilla siempre que la copie como una carpeta en la carpeta working\content.

  • Abra un terminal y vaya a la carpeta working.

  • Instale .NET 8.

  • Instalar la plantilla Microsoft.TemplateEngine.Authoring.Templates desde la fuente del paquete NuGet.

    • Ejecute el comando dotnet new install Microsoft.TemplateEngine.Authoring.Templates desde el terminal.

Importante

Este artículo está escrito para .NET 7. Sin embargo, también se aplica a .NET 6 y versiones anteriores, con una diferencia: la sintaxis dotnet new es diferente. Los subcomandos list, search, install, y uninstall deben ser --list, --search, --install y --uninstall, respectivamente.

Poe ejemplo, el comando dotnet new install de .NET 7 se convierte en dotnet new --install en .NET 6. Use el comando dotnet new --help para ver una lista de todas las opciones y subcomandos.

Creación de un proyecto de paquete de plantillas

Un paquete de plantillas consiste en una o más plantillas empaquetadas en un paquete NuGet. Cuando instala o desinstala un paquete de plantillas, se agregan o se quitan todas las plantillas del paquete, respectivamente.

Los paquetes de plantillas se representan con un archivo de paquete NuGet ( .nupkg). Además, al igual que ocurre con cualquier paquete NuGet, puede cargar el paquete de plantillas a una fuente NuGet. El comando dotnet new install permite la instalación de paquetes de plantillas desde una fuente de paquetes NuGet, un archivo .nupkg o un directorio con una plantilla.

Por lo general, se usa un archivo del proyecto de C# para compilar el código y generar un archivo binario. Sin embargo, el proyecto también se puede usar para generar un paquete de plantillas. Si cambia la configuración del archivo .csproj, puede impedir que compile código y, en su lugar, incluir todos los recursos de las plantillas como recursos. Cuando se compila este proyecto, genera un paquete NuGet de paquete de plantillas.

El paquete que va a generar incluirá el [item] y(cli-templates-create-item-template.md) y las plantillas de proyecto creadas previamente.

El paquete Microsoft.TemplateEngine.Authoring.Templates contiene plantillas útiles para la creación de plantillas. Para instalar este paquete, nuget.org debe estar disponible como fuente NuGet en el directorio de trabajo.

  1. En la carpeta de trabajo, ejecute el siguiente comando para crear el paquete de plantilla:

    dotnet new templatepack -n "AdatumCorporation.Utility.Templates"

    El parámetro -n establece el nombre del archivo de proyecto en AdatumCorporation.Utility.Templates.csproj. Verá un resultado similar a la salida siguiente.

    The template "Template Package" was created successfully.

Processing post-creation actions...
Description: Manual actions required
Manual instructions: Open *.csproj in the editor and complete the package metadata configuration. Copy the templates to _content_ folder. Fill in README.md.

  2. A continuación, abra el archivo AdatumCorporation.Utility.Templates.csproj en un editor de código y rellénelo según las sugerencias de la plantilla:

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

  <PropertyGroup>
    <!-- The package metadata. Fill in the properties marked as TODO below -->
    <!-- Follow the instructions on https://learn.microsoft.com/nuget/create-packages/package-authoring-best-practices -->
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <PackageVersion>1.0</PackageVersion>
    <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>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>net8.0</TargetFramework>
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
    ... cut for brevity ...

  1. En la carpeta de trabajo, ejecute el siguiente comando para crear el paquete de plantilla:

    dotnet new console -n AdatumCorporation.Utility.Templates

    El parámetro -n establece el nombre del archivo de proyecto en AdatumCorporation.Utility.Templates.csproj. Verá un resultado similar a la salida siguiente.

    The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on .\AdatumCorporation.Utility.Templates.csproj...
  Restore completed in 52.38 ms for C:\code\working\AdatumCorporation.Utility.Templates.csproj.

Restore succeeded.

  2. Elimine el archivo Program.cs. La nueva plantilla de proyecto genera este archivo, pero no lo usa el motor de plantillas.

  3. A continuación, abra el archivo templatepack.csproj en su editor favorito y reemplace el contenido por el XML siguiente:

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

  <PropertyGroup>
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <PackageVersion>1.0</PackageVersion>
    <Title>AdatumCorporation Templates</Title>
    <Authors>Me</Authors>
    <Description>Templates to use when creating an application for Adatum Corporation.</Description>
    <PackageTags>dotnet-new;templates;adatum</PackageTags>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>netstandard2.0</TargetFramework>
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
  </PropertyGroup>

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

</Project>

Descripción del XML del proyecto

La configuración en <PropertyGroup> en el fragmento de código XML se divide en dos grupos.

El primer grupo trata con las propiedades requeridas para un paquete de NuGet. Los cuatro valores <Package*> están relacionados con las propiedades del paquete de NuGet para identificar el paquete en una fuente NuGet. El valor <PackageId>, mientras lo usa NuGet, también se usa para desinstalar el paquete de plantilla. Los valores restantes, como <Title> y <PackageTags>, están relacionados con los metadatos que aparecen en la fuente NuGet y el administrador de paquetes de .NET. Para más información sobre la configuración de NuGet, consulte el artículo sobre propiedades de NuGet y MSBuild.

Nota:

Para asegurarse de que el paquete de plantillas aparece en los resultados de dotnet new search, <PackageType> debe establecerse en Template.

En el segundo grupo, la configuración <TargetFramework> garantiza que MSBuild se ejecute correctamente al ejecutar el comando pack para compilar y empaquetar el proyecto. En el grupo también se incluyen los valores relacionados con la configuración del proyecto para incluir las plantillas en la carpeta adecuada del paquete de NuGet cuando se crea:

  • La configuración <NoWarn> suprime un mensaje de advertencia que no se aplica a los proyectos del paquete de plantillas.

  • La configuración <NoDefaultExcludes> garantiza que los archivos y las carpetas que comienzan con. (como .gitignore) forman parte de la plantilla. El comportamiento predeterminado de los paquetes de NuGet es omitir esos archivos y carpetas.

<ItemGroup> contiene dos elementos. En primer lugar, el elemento <Content> incluye todo lo que hay en la carpeta templates como contenido. También se establece para excluir cualquier carpeta bin o carpeta obj para evitar que se incluya cualquier código compilado (si probó y compiló las plantillas). En segundo lugar, el elemento <Compile> excluye todos los archivos de código de la compilación, independientemente de dónde estén ubicados. Esta configuración evita que el proyecto que se usa para crear un paquete de plantillas intente compilar el código en la jerarquía de carpetas templates.

Sugerencia

Para obtener más información sobre la configuración de metadatos de NuGet, vea Empaquetar una plantilla en un paquete NuGet (archivo nupkg).

El archivo del proyecto creado incluye tareas de MSBuild de creación de plantillas y la configuración de localización.

  <PropertyGroup>
    <LocalizeTemplates>false</LocalizeTemplates>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.TemplateEngine.Tasks" Version="*" PrivateAssets="all" IsImplicitlyDefined="true"/>
  </ItemGroup>

Importante

La carpeta de contenido content contiene una carpeta SampleTemplate. Eliminar esta carpeta, ya que se agregó a la plantilla de creación con fines de demostración.

Estas tareas de MSBuild proporcionan validación de plantillas y funcionalidades de localización de las plantillas. La localización está deshabilitada de forma predeterminada. Para habilitar la creación de archivos de localización, establezca LocalizeTemplates en true.

Empaquetar e instalar

Guarde el archivo de proyecto. Antes de compilar el paquete de plantillas, compruebe que la estructura de carpetas sea correcta. Cualquier plantilla que quiera empaquetar debe colocarse en la carpeta de plantillas, en su propia carpeta. La estructura de carpetas debe un aspecto similar a la jerarquía siguiente:

working
│   AdatumCorporation.Utility.Templates.csproj
└───content
    ├───extensions
    │   └───.template.config
    │           template.json
    └───consoleasync
        └───.template.config
                template.json

La carpeta de contenido tiene dos carpetas: extensions y consoleasync.

En el terminal, en la carpeta de trabajo, ejecute el comando dotnet pack. Este comando compila el proyecto y crea un paquete de NuGet en la carpeta working\bin\Debug, como se indica en el siguiente resultado:

MSBuild version 17.8.0-preview-23367-03+0ff2a83e9 for .NET
  Determining projects to restore...
  Restored C:\code\working\AdatumCorporation.Utility.Templates.csproj (in 1.16 sec).

  AdatumCorporation.Utility.Templates -> C:\code\working\bin\Release\net8.0\AdatumCorporation.Utility.Templates.dll
  Successfully created package 'C:\code\working\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg'.

A continuación, instale el paquete de plantillas con el comando dotnet new install. En Windows:

dotnet new install .\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

En Linux o macOS:

dotnet new install bin/Release/AdatumCorporation.Utility.Templates.1.0.0.nupkg

Debería ver un resultado similar al siguiente:

The following template packages will be installed:
   C:\code\working\AdatumCorporation.Utility.Templates\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

Success: AdatumCorporation.Utility.Templates::1.0.0 installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code
Example templates: async project                  consoleasync             [C#]              Common/Console/C#9

Si cargó el paquete de NuGet en una fuente NuGet, puede usar el comando dotnet new install <PACKAGE_ID>, donde <PACKAGE_ID> es igual que el valor <PackageId> del archivo .csproj.

Desinstalación del paquete de plantillas

Independientemente de cómo instaló el paquete de plantillas, ya sea directamente con el archivo .nupkg o mediante una fuente NuGet, el proceso para quitar un paquete de plantillas es el mismo. Use el <PackageId> de la plantilla que quiere desinstalar. Ejecute el comando dotnet new uninstall para ver una lista de las plantillas que están instaladas.

C:\working> dotnet new uninstall
Currently installed items:
... cut to save space ...

  AdatumCorporation.Utility.Templates
    Details:
      NuGetPackageId: AdatumCorporation.Utility.Templates
      Version: 1.0.0
      Author: Me
    Templates:
      Example templates: async project (consoleasync) C#
      Example templates: string extensions (stringext) C#
    Uninstall Command:
      dotnet new uninstall AdatumCorporation.Utility.Templates

Ejecute dotnet new uninstall AdatumCorporation.Utility.Templates para desinstalar el paquete de plantillas. El comando muestra información sobre qué paquetes de plantillas se han desinstalado.

¡Enhorabuena! Ya instaló y desinstaló un paquete de plantillas.

Pasos siguientes

Para más información sobre las plantillas, que en gran parte ya conoce, consulte el artículo Plantillas personalizadas para dotnet new.