Compartir vía

Tutorial: Creación de una plantilla de elemento

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

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:

  • Cree una clase para una plantilla de elemento.
  • Cree la carpeta y el archivo de configuración de plantilla.
  • Instale una plantilla desde una ruta de archivo.
  • Pruebe una plantilla de elemento.
  • Desinstale una plantilla de elemento.

Prerrequisitos

  • .NET 9 o una versión posterior.

  • En el artículo de referencia se explican los conceptos básicos sobre las plantillas y cómo se reúnen. Aquí se reitera parte de esta información.

  • Abra un terminal y vaya a una carpeta donde almacenará y probará las plantillas.

Creación de las carpetas necesarias

Esta serie usa una "carpeta de trabajo" donde se incluye 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 pruebas deben estar en la misma carpeta primaria.

En primer lugar, cree la carpeta primaria, el nombre no importa. A continuación, cree dos subcarpetas denominadas working y test. Dentro de la carpeta de trabajo , cree una subcarpeta denominada content.

La estructura de carpetas debe ser similar a la siguiente.

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

Creación de una plantilla de elemento

Una plantilla de elemento es un tipo específico de plantilla 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 proporciona 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 finaliza el contenido de la plantilla, cree la configuración de la plantilla.

Creación de la configuración de 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 la carpeta de plantilla.

En primer lugar, cree una subcarpeta denominada .template.configy escríbala. A continuación, cree un nuevo archivo denominado template.json. La estructura de carpetas debe tener este aspecto:

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

Abra el template.json con su editor de texto favorito y pegue el siguiente código JSON 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 todas las opciones de configuración de la plantilla. Puede ver la configuración básica, como name y shortName, pero también hay un valor de tags/type que está establecido en item. Esto clasifica la plantilla como una plantilla de "elemento". No hay ninguna restricción en el tipo de plantilla que cree. Los item valores y project son nombres comunes que .NET recomienda para que los usuarios puedan filtrar fácilmente el tipo de plantilla que están buscando.

El classifications elemento representa la columna de etiquetas que ve al ejecutar dotnet new y obtener una lista de plantillas. Los usuarios también pueden buscar en función de las etiquetas de clasificación. No confunda la tags propiedad en el archivo template.json con la classifications lista de etiquetas. Son dos conceptos diferentes que, por desgracia, se denominan iguales. El esquema completo del archivo template.json se encuentra en el almacén de esquemas JSON y se describe en Referencia para template.json. Para obtener más información sobre el archivo template.json , consulte la wiki de plantillas de dotnet.

La symbols parte 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 está impresa 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 ClassName parámetro y este valor reemplaza todas las apariciones de StringExtensions. Si no se proporciona un valor, defaultValue se usa . 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 MyExts.cs y se cambia 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 la plantilla:

dotnet new stringext -?

Que genera la siguiente salida:

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.configotemplate.json válido, la plantilla está lista para instalarse. En el terminal, vaya a la carpeta extensions y ejecute el siguiente comando 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 plantillas instaladas, que deben 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.

  1. Vaya a la carpeta de prueba .

  2. Cree una nueva aplicación de consola con dotnet new console, que genera un proyecto de trabajo que puede probar fácilmente con el dotnet run comando .

    dotnet new console

    Recibirás 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.

  3. Ejecute el proyecto con el siguiente comando.

    dotnet run

    Obtendrá la siguiente salida.

    Hello, World!

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

  5. Cambie el código de Program.cs para invertir la "Hello, World!" cadena con el método de extensión proporcionado por la plantilla.

    Console.WriteLine("Hello, World!".Reverse());

    Vuelva a ejecutar el programa y vea que el resultado se invierte.

    dotnet run

    Usted obtiene el siguiente resultado.

    !dlroW ,olleH

¡Felicidades! Ha creado e implementado una plantilla de elemento con .NET. En preparación para la siguiente 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 de prueba . Esto le devuelve a un estado inicial limpio, listo para la siguiente parte de la serie de tutoriales.

Desinstalación de la plantilla

En el terminal, vaya a la carpeta extensions y ejecute el siguiente comando 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 desinstalaron, que deben incluir las suyas.

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

En cualquier momento, puede usar dotnet new uninstall para ver una lista de paquetes de plantilla instalados, incluido para cada paquete de plantilla el comando para desinstalarlo.

Pasos siguientes

En este tutorial, ha creado una plantilla de elemento. Para obtener información sobre cómo crear una plantilla de proyecto, continúe con esta serie de tutoriales.

Creación de una plantilla de proyecto

  • Last updated on