Compartir a través de

Tutorial: Creación de un paquete de plantilla

  • Artículo

Con .NET, puede crear e implementar plantillas que generen proyectos, archivos e incluso recursos. Este tutorial es la tercera parte de una serie que le enseña a crear, instalar y desinstalar plantillas para su uso con el comando dotnet new.

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

En esta parte de la serie aprenderá a:

  • Creación de un paquete de plantillas mediante el paquete NuGet Microsoft.TemplateEngine.Authoring.Templates.
  • Instale un paquete de plantilla desde un archivo de paquete NuGet.
  • Desinstale un paquete de plantilla por identificador de paquete.

Prerrequisitos

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

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

  • Abra un terminal y vaya a la carpeta de trabajo.

  • Instale .NET 8 o .NET 9.

  • 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.

Creación de un proyecto de paquete de plantilla

Un paquete de plantilla es una o varias plantillas empaquetadas en un paquete NuGet. Al instalar o desinstalar un paquete de plantilla, se agregan o quitan todas las plantillas contenidas en el paquete, respectivamente.

Los paquetes de plantilla se representan mediante un paquete NuGet (archivo .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 admite la instalación de paquetes de plantilla desde una fuente de paquetes NuGet, un archivo de .nupkg o un directorio con una plantilla.

Normalmente, se usa un archivo de proyecto de C# para compilar código y generar un binario. Sin embargo, el proyecto también se puede usar para generar un paquete de plantilla. Al cambiar la configuración del .csproj, puede impedir que compile cualquier código e incluya en su lugar todos los recursos de las plantillas como recursos. Cuando se compila este proyecto, genera un paquete NuGet de plantillas.

El paquete que va a generar incluirá el elemento y las plantillas del proyecto creadas anteriormente.

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 de archivo del proyecto en AdatumCorporation.Utility.Templates.csproj. Verás un resultado similar al 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 lléntelo 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 ...

Descripción del xml del proyecto

Las configuraciones en <PropertyGroup> en el fragmento XML se dividen en dos grupos.

El primer grupo se ocupa de las propiedades necesarias para un paquete NuGet. Las cuatro configuraciones de <Package*> tienen que ver con las propiedades del paquete NuGet para identificar su paquete en un feed de NuGet. El valor de <PackageId>, además de ser usado por NuGet, también se usa para desinstalar el paquete de plantilla. La configuración restante, como <Title> y <PackageTags>, tiene que ver con los metadatos que se muestran 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 plantilla aparezca en los resultados dotnet new search, <PackageType> debe establecerse en Template.

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

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

  • La configuración de <NoDefaultExcludes> garantiza que los archivos y carpetas que comienzan con un . (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 en la carpeta de plantillas como parte del contenido. Está configurado también para excluir la carpeta bin o la carpeta obj para evitar que se incluya el código compilado (si se han probado y compilado las plantillas). En segundo lugar, el elemento <Compile> excluye todos los archivos de código de la compilación independientemente de dónde se encuentren. Esta configuración impide que el proyecto que se usa para crear el paquete de plantilla intente compilar el código en las plantillas de jerarquía de carpetas.

Sugerencia

Para obtener más información sobre la configuración de metadatos de NuGet, consulte 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 del proyecto. Antes de compilar el paquete de plantilla, compruebe que la estructura de carpetas es correcta. Cualquier plantilla que desee empaquetar debe colocarse en la carpeta plantillas, en su propia carpeta. La estructura de carpetas debe ser similar a la siguiente jerarquía:

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

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

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

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 plantilla 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 una salida similar a la 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 plantilla

Independientemente de si ha instalado el paquete de plantilla con el archivo .nupkg directamente o mediante el canal de NuGet, quitar un paquete de plantilla es lo mismo. Use el <PackageId> de la plantilla que desea desinstalar. Para obtener una lista de plantillas instaladas, ejecute el comando dotnet new uninstall.

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 plantilla. El comando genera información sobre qué paquetes de plantilla se desinstalaron.

¡Felicidades! Ha instalado y desinstalado un paquete de plantilla.

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.