Tutorial: Creación de una plantilla de elemento
Con .NET, puede crear e implementar plantillas que generan proyectos, archivos e inclusos recursos. Este tutorial es el primero de una serie que enseña a crear, instalar y desinstalar plantillas para usarlas con el comando dotnet new.
En esta parte de la serie, aprenderá a:
- Crear una clase para una plantilla de elemento.
- 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
SDK de .NET 5.0 o una versión posterior.
Leer el artículo de referencia Plantillas personalizadas para dotnet new.
En el artículo de referencia se explican los aspectos básicos de las plantillas y cómo se unen. Parte de esta información se repetirá en este tutorial.
Abra un terminal y vaya a la carpeta working\templates.
Creación de las carpetas necesarias
Esta serie usa una "carpeta de trabajo", donde se encuentra el origen de la plantilla, y una "carpeta de prueba" que se usa para probar las plantillas. La carpeta de trabajo y la carpeta de prueba deben estar en la misma carpeta.
En primer lugar, cree la carpeta principal, no importa con qué nombre. Luego, cree una subcarpeta denominada working (trabajo). Dentro de la carpeta working, cree una subcarpeta con el nombre templates (plantillas).
A continuación, cree una carpeta dentro de la carpeta principal con el nombre test (prueba). La estructura de carpetas debe tener el siguiente aspecto.
parent_folder
├───test
└───working
└───templates
Creación de una plantilla de elemento
Una plantilla de elemento es un tipo de plantilla específico que contiene uno o varios archivos. Estos tipos de plantillas son útiles cuando se quiere generar algún contenido como un archivo de solución, código o configuración. En este ejemplo, creará una clase que agrega un método de extensión al tipo de cadena.
En el terminal, vaya a la carpeta working\templates y cree una subcarpeta llamada extensions. Entre a la carpeta.
working
└───templates
└───extensions
Cree un archivo nuevo denominado CommonExtensions.cs y ábralo con el editor de texto que prefiera. Esta clase proporcionará un método de extensión denominado Reverse que invierte el contenido de una cadena. Pegue el código siguiente y guarde el archivo:
using System;
namespace System
{
public static class StringExtensions
{
public static string Reverse(this string value)
{
var tempArray = value.ToCharArray();
Array.Reverse(tempArray);
return new string(tempArray);
}
}
}
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
Las plantillas se reconocen con una carpeta especial y un archivo de configuración que existen en la raíz de la plantilla. En este tutorial, la carpeta de la plantilla se encuentra en working\templates\extensions.
Cuando se crea una plantilla, todos los archivos y las carpetas de la carpeta de la plantilla se incluyen como parte de la plantilla, a excepción de la carpeta de configuración especial. Esta carpeta de configuración se denomina .template.config.
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
└───templates
└───extensions
└───.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", "Code" ],
"identity": "ExampleTemplate.StringExtensions",
"name": "Example templates: string extensions",
"shortName": "stringext",
"tags": {
"language": "C#",
"type": "item"
}
}
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 item. De este modo, la plantilla se clasifica como una plantilla de elemento. 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 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 *.json con la lista de etiquetas classifications. Lamentablemente, son dos elementos que tienen nombres similares. 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.
Ahora que tiene un archivo .template.config/template.json válido, la plantilla está lista para instalarla. En el terminal, vaya a la carpeta extensions y ejecute el comando siguiente para instalar la plantilla ubicada en la carpeta actual:
- En Windows:
dotnet new --install .\ - En Linux o macOS:
dotnet new --install ./
Este comando genera la lista de las plantillas instaladas, que debería incluir la suya.
The following template packages will be installed:
<root path>\working\templates\extensions
Success: <root path>\working\templates\extensions installed the following templates:
Templates Short Name Language Tags
-------------------------------------------- ------------------- ------------ ----------------------
Example templates: string extensions stringext [C#] Common/Code
Prueba de la plantilla de elemento
Ahora que tiene instalada una plantilla de elemento, pruébela. Vaya a la carpeta test/ y cree una aplicación de consola con dotnet new console. Esto genera un proyecto de trabajo que puede probar fácilmente con el comando dotnet run.
dotnet new console
Verá un resultado similar al siguiente.
The template "Console Application" was created successfully.
Processing post-creation actions...
Running 'dotnet restore' on C:\test\test.csproj...
Restore completed in 54.82 ms for C:\test\test.csproj.
Restore succeeded.
Ejecute el proyecto.
dotnet run
Obtendrá la siguiente salida.
Hello World!
Luego, ejecute dotnet new stringext para generar CommonExtensions.cs desde la plantilla.
dotnet new stringext
Obtendrá la siguiente salida.
The template "Example templates: string extensions" was created successfully.
Cambie el código en Program.cs para invertir la cadena "Hello World" con el método de extensión que se proporciona en la plantilla.
Console.WriteLine("Hello World!".Reverse());
Vuelva a ejecutar el programa y verá que el resultado se invirtió.
dotnet run
Obtendrá la siguiente salida.
!dlroW olleH
¡Enhorabuena! Ha creado e implementado una plantilla de elemento con .NET. Como preparación para la próxima parte de esta serie de tutoriales, debe desinstalar la plantilla que creó. Asegúrese de eliminar también todos los archivos de la carpeta test. Esto le permitirá volver a un estado limpio listo para la próxima sección importante de este tutorial.
Desinstalación de la plantilla
En el terminal, vaya a la carpeta extensions 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\templates\extensions 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 elemento. Para aprender a crear una plantilla de proyecto, siga con esta serie de tutoriales.