Tutorial: Creación de una plantilla de elemento

Artículo
10/13/2023

Con .NET, puede crear e implementar plantillas que generan proyectos, archivos y 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.

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

Sugerencia

Las plantillas de elemento no se muestran en el cuadro de diálogo Agregar>Nuevo elemento de Visual Studio.

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 7.0.100 de .NET o una versión posterior.

En el artículo de referencia se explican los aspectos básicos de las plantillas y cómo se unen. Aquí se reitera parte de esta información.
Abra un terminal y vaya a una carpeta donde almacenará y probará las plantillas.

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 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. A continuación, cree dos subcarpetas denominadas working y test. Dentro de la carpeta working, cree una subcarpeta con el nombre content.

La estructura de carpetas debe tener el siguiente aspecto.

parent_folder
├───test
└───working
    └───content

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 ya tiene un proyecto y desea generar otro archivo, como un archivo de configuración o un archivo de código. 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\content y cree una subcarpeta denominada extensions.

working
└───content
    └───extensions

Vaya a la carpeta extensions y cree un nuevo archivo denominado StringExtensions.cs. Abra el archivo en un editor de texto. 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:

namespace System;

public static class StringExtensions
{
    public static string Reverse(this string value)
    {
        char[] tempArray = value.ToCharArray();
        Array.Reverse(tempArray);
        return new string(tempArray);
    }
}

Ahora que el contenido de la plantilla está terminado, el siguiente paso es crear la configuración de la plantilla.

Creación de la configuración de una plantilla

En esta parte del tutorial, la carpeta de plantilla se encuentra en working\content\extensions.

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

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
    └───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"
    },
    "symbols": {
      "ClassName":{
        "type": "parameter",
        "description": "The name of the code file and class.",
        "datatype": "text",
        "replaces": "StringExtensions",
        "fileRename": "StringExtensions",
        "defaultValue": "StringExtensions"
      }
    }
  }

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

La parte symbols de este objeto JSON se usa para definir los parámetros que se pueden usar en la plantilla. En este caso, hay un parámetro definido, ClassName. El parámetro definido contiene la siguiente configuración:

type: se trata de una configuración obligatoria y debe establecerse en parameter.
description: la descripción del parámetro, que se imprime en la ayuda de la plantilla.
datatype: el tipo de datos del valor del parámetro cuando se usa el parámetro.
replaces: especifica un valor de texto que se debe reemplazar en todos los archivos de plantilla por el valor del parámetro.
fileRename: similar a replaces, especifica un valor de texto que se reemplaza en los nombres de todos los archivos de plantilla por el valor del parámetro.
defaultValue: el valor predeterminado de este parámetro cuando el usuario no especifica el parámetro.

Cuando se usa la plantilla, el usuario puede proporcionar un valor para el parámetro ClassName y este valor reemplaza todas las apariciones de StringExtensions. Si no se proporciona un valor, se usa el defaultValue. Para esta plantilla, hay dos apariciones de StringExtensions: el archivo StringExtensions.cs y la clase StringExtensions. Dado que el defaultValue del parámetro es StringExtensions, el nombre de archivo y el nombre de clase permanecen sin cambios si el parámetro no se especifica al usar la plantilla. Cuando se especifica un valor, por ejemplo dotnet new stringext -ClassName MyExts, se cambia el nombre del archivo a MyExts.cs y el nombre de la clase a MyExts.

Para ver qué parámetros están disponibles para una plantilla, use el parámetro -? con el nombre de plantilla:

dotnet new stringext -?

Lo que genera el siguiente resultado:

Example templates: string extensions (C#)
Author: Me

Usage:
  dotnet new stringext [options] [template options]

Options:
  -n, --name <name>       The name for the output being created. If no name is specified, the name of the output directory is used.
  -o, --output <output>   Location to place the generated output.
  --dry-run               Displays a summary of what would happen if the given command line were run if it would result in a template creation.
  --force                 Forces content to be generated even if it would change existing files.
  --no-update-check       Disables checking for the template package updates when instantiating a template.
  --project <project>     The project that should be used for context evaluation.
  -lang, --language <C#>  Specifies the template language to instantiate.
  --type <item>           Specifies the template type to instantiate.

Template options:
  -C, --ClassName <ClassName>  The name of the code file and class.
                               Type: text
                               Default: StringExtensions

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\content\extensions

Success: <root path>\working\content\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.

Cree una aplicación de consola con dotnet new console, que 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 con el comando siguiente.
```
dotnet run
```
Obtendrá la siguiente salida.
```
Hello, World!
```
Ejecute dotnet new stringext para generar el archivo StringExtensions.cs a partir de 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 vea que el resultado se invierte.
```
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, desinstale la plantilla que creó. Asegúrese de eliminar también todos los archivos y carpetas 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 extensions y ejecute el comando siguiente para desinstalar las plantillas ubicadas 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\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.

Creación de una plantilla de proyecto