Tutorial: Creación de una plantilla de proyecto

Artículo
10/09/2023

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

Sugerencia

Las plantillas de .NET oficiales que se incluyen con el SDK de .NET están en los siguientes repositorios:

Plantillas	Repositorio
Plantillas de elementos comunes, consola y biblioteca de clases	dotnet/sdk
Plantillas de ASP.NET y Blazor	dotnet/aspnetcore
Plantillas de aplicación de una sola página de ASP.NET	dotnet/spa-templates
Plantillas de WPF	dotnet/wpf
Plantillas de Windows Forms	dotnet/winforms
Plantillas de prueba	dotnet/test-templates
Plantillas de MAUI	dotnet/maui

Para ver las plantillas instaladas en el equipo, ejecute el comando dotnet new list.

En esta parte de la serie, aprenderá a:

Crear los recursos de una plantilla de proyecto.
Crear el archivo y la carpeta de configuración de la plantilla.
Instalar una plantilla desde una ruta de acceso de archivo.
Probar una plantilla de elemento.
Desinstalar una plantilla de elemento.

Requisitos previos

Complete la parte 1 de esta serie de tutoriales.
Abra un terminal y vaya a la carpeta working\content.

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 una plantilla de proyecto

Las plantillas de proyecto generan proyectos listos para ejecutarse que facilita a los usuarios empezar a trabajar con un espacio de trabajo de código. .NET incluye algunas plantillas de proyecto, como una aplicación de consola o una biblioteca de clases. En este ejemplo, se crea un nuevo proyecto de aplicación de consola que reemplazará la salida de la consola "Hola mundo" estándar por una que se ejecute de forma asincrónica.

En el terminal, vaya a la carpeta working\content y cree una subcarpeta denominada consoleasync. Entre a la subcarpeta y ejecute dotnet new console para generar la aplicación de consola estándar. Para crear una plantilla nueva, editará los archivos que genere esta plantilla.

working
└───content
    └───consoleasync
            consoleasync.csproj
            Program.cs

Modificación de Program.cs

Abra el archivo Program.cs. El proyecto de consola estándar no escribe asincrónicamente en la salida de consola, por lo que vamos a agregarlo. Cambie el código por lo siguiente y guarde el archivo:

// See https://aka.ms/new-console-template for more information
await Console.Out.WriteAsync("Hello World with C#");

Ahora que creó el contenido de la plantilla, debe crear su configuración en la carpeta raíz de la plantilla.

Creación de la configuración de una plantilla

En este tutorial, la carpeta de la plantilla se encuentra en working\content\consoleasync.

.NET reconoce plantillas porque tienen una carpeta especial y un archivo de configuración en la raíz de la carpeta de plantilla.

En primer lugar, cree una subcarpeta con el nombre .template.config y entre en ella. Luego, cree un archivo denominado template.json. La estructura de la carpeta debe verse así:

working
└───content
    └───consoleasync
        └───.template.config
                template.json

Abra template.json con el editor de texto que prefiera, pegue el código JSON siguiente y guárdelo.

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Me",
  "classifications": [ "Common", "Console" ],
  "identity": "ExampleTemplate.AsyncProject",
  "name": "Example templates: async project",
  "shortName": "consoleasync",
  "sourceName":"consoleasync",
  "tags": {
    "language": "C#",
    "type": "project"
  }
}

Este archivo de configuración contiene todos los valores de la plantilla. Puede ver los valores básicos, como name y shortName, pero también hay un valor tags/type que está establecido en project. Esto clasifica la plantilla como una plantilla de "proyecto". No hay ninguna restricción en el tipo de plantilla que crea. Los valores item y project son nombres comunes que .NET recomienda para que los usuarios puedan filtrar fácilmente el tipo de plantilla que buscan.

El elemento sourceName es lo que se reemplaza cuando el usuario usa la plantilla. El valor de sourceName en el archivo de configuración se busca en cada nombre de archivo y contenido de archivo, y de forma predeterminada se reemplaza por el nombre de la carpeta actual. Cuando se pasa el parámetro -n o --name con el comando dotnet new, se usa el valor proporcionado en lugar del nombre de la carpeta actual. En el caso de esta plantilla, consoleasync se reemplaza en el nombre del archivo .csproj.

El elemento classifications representa la columna tags que ve cuando ejecuta dotnet new y obtiene una lista de plantillas. Los usuarios también pueden hacer una búsqueda según las etiquetas de clasificación. No confunda la propiedad tags del archivo template.json con la lista de etiquetas classifications. Son dos conceptos diferentes que desgraciadamente se denominan igual. El esquema completo del archivo template.json puede encontrarse en el Almacenamiento del esquema JSON y se describe en Referencia para template.json. Para más información sobre el archivo template.json, consulte la wiki de plantillas dotnet.

Ahora que tiene un archivo .template.config/template.json válido, la plantilla está lista para instalarla. Antes de instalar la plantilla, asegúrese de eliminar cualquier carpeta y archivo adicional que no quiere que se incluya en la plantilla, como las carpetas bin u obj. En el terminal, vaya a la carpeta consoleasync y ejecute dotnet new install .\ para instalar la plantilla ubicada en la carpeta actual. Si usa un sistema operativo Linux o macOS, use una barra diagonal: dotnet new install ./.

dotnet new install .\

Este comando genera una lista de las plantillas instaladas, que debería incluir la suya.

The following template packages will be installed:
   <root path>\working\content\consoleasync

Success: <root path>\working\content\consoleasync installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: async project                  consoleasync             [C#]              Common/Console

Prueba de la plantilla de proyecto

Ahora que tiene instalada una plantilla de proyecto, pruébela.

Vaya a la carpeta test.
Cree una aplicación de consola con el siguiente comando que genera un proyecto de trabajo que puede probar fácilmente con el comando dotnet run.
```
dotnet new consoleasync -n MyProject
```
Obtendrá la siguiente salida.
```
The template "Example templates: async project" was created successfully.
```
Ejecute el proyecto con el comando siguiente.
```
dotnet run
```
Obtendrá la siguiente salida.
```
Hello World with C#
```

¡Enhorabuena! Ha creado e implementado una plantilla de proyecto con .NET. Como preparación para la próxima parte de esta serie de tutoriales, desinstale la plantilla que creó. Asegúrese de eliminar también todos los archivos de la carpeta test. Esto le lleva a un estado limpio listo para la siguiente parte de esta serie de tutoriales.

Desinstalación de la plantilla

En el terminal, vaya a la carpeta consoleasync y ejecute el comando siguiente para desinstalar la plantilla ubicada en la carpeta actual:

En Windows: dotnet new uninstall .\
En Linux o macOS: dotnet new uninstall ./

Este comando genera una lista de las plantillas que se han desinstalado, que debería incluir la suya.

Success: <root path>\working\content\consoleasync was uninstalled.

En cualquier momento, puede usar dotnet new uninstall para ver una lista de los paquetes de plantillas instalados, incluido el comando de desinstalación para cada uno de ellos.

Pasos siguientes

En este tutorial creó una plantilla de proyecto. Para información sobre cómo empaquetar la plantilla de elemento y la de proyecto en un archivo fácil de usar, continúe con esta serie de tutoriales.

Creación de un paquete de plantillas

Share via