Tutorial: Criar um modelo de item

Artigo
10/09/2023

Com o .NET, você pode criar e implantar modelos que geram projetos, arquivos e recursos. Este tutorial é a parte um de uma série que ensina como criar, instalar e desinstalar modelos para usar com o comando dotnet new.

Você pode exibir o modelo concluído no repositório GitHub de amostras do .NET.

Dica

Os modelos de item não são mostrados na caixa de diálogo Adicionar>Novo item do Visual Studio.

Nesta parte da série, você aprenderá a:

Crie uma classe para um modelo de item.
Crie a pasta e o arquivo de configuração do modelo.
Instale um modelo a partir de um caminho de arquivo.
Teste um modelo de item.
Desinstale um modelo de item.

Pré-requisitos

SDK do .NET 7.0.100 ou versão posterior.

O artigo de referência explica os conceitos básicos sobre modelos e como eles são agrupados. Algumas dessas informações são reiteradas aqui.
Abra um terminal e navegue até uma pasta onde você armazenará e testará os modelos.

Importante

Este artigo foi escrito para o .NET 7. No entanto, ele também se aplica ao .NET 6 e às versões anteriores, com uma diferença: a sintaxe dotnet new é diferente. Os subcomandos list, search, install e uninstall devem ser as opções --list, --search, --install e --uninstall, respectivamente.

Por exemplo, o comando dotnet new install no .NET 7 se torna dotnet new --install no .NET 6. Use o comando dotnet new --help para ver uma lista de todas as opções e subcomandos.

Criar as pastas obrigatórias

Esta série usa uma "pasta de trabalho" na qual sua fonte de modelo está contida e uma "pasta de teste" usada para testar seus modelos. A pasta de trabalho e a pasta de teste devem estar na mesma pasta pai.

Primeiro, crie a pasta pai, o nome não importa. Em seguida, crie duas subpastas chamadas working e test. Dentro da pasta working, crie uma subpasta chamada content.

A estrutura da pasta deve ser semelhante a esta.

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

Criar um modelo de item

Um modelo de item é um tipo específico de modelo que contém um ou mais arquivos. Esses tipos de modelos são úteis quando você já tem um projeto e deseja gerar outro arquivo, como um arquivo de configuração ou arquivo de código. Neste exemplo, você criará uma classe que adiciona um método de extensão ao tipo de cadeia de caracteres.

No terminal, navegue até a pasta working\content e crie uma nova subpasta chamada extensions.

working
└───content
    └───extensions

Navegue até a pasta extensions e crie um novo arquivo chamado StringExtensions.cs. Abra o arquivo em um editor de texto. Essa classe fornecerá um método de extensão chamado Reverse que reverterá o conteúdo de uma cadeia de caracteres. Cole no seguinte código e salve o arquivo:

namespace System;

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

Agora que o conteúdo do modelo foi concluído, a próxima etapa é criar a configuração do modelo.

Criar a configuração do modelo

Nesta parte do tutorial, sua pasta de modelo está localizada em working\content\extensions.

Os modelos são reconhecidos pelo .NET porque eles têm uma pasta especial e um arquivo de configuração que existem na raiz da pasta de modelo.

Primeiro, crie uma nova subpasta chamada .template.config e insira-a. Em seguida, crie um novo arquivo chamado template.json. A estrutura de pastas devem ter a seguinte aparência:

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

Abra o arquivo template.json com seu editor de texto favorito, cole o seguinte código JSON e salve-o.

{
    "$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"
      }
    }
  }

Esse arquivo de configuração contém todas as configurações do modelo. Você pode ver as configurações básicas, como name e shortName, mas também há um valor de tags/type definido como item. Isso categoriza seu modelo como um modelo de "item". Não há restrições quanto ao tipo do modelo criado. Os valores item e project são nomes comuns que o .NET recomenda para que os usuários possam filtrar facilmente o tipo de modelo que pesquisam.

O item classifications representa a coluna marcações que você vê quando executa dotnet new e obtém uma lista de modelos. Os usuários também podem pesquisar com base nas marcações de classificação. Não confunda a propriedade tags no arquivo template.json com a lista de marcas classifications. São dois conceitos diferentes que, infelizmente, são chamados da mesma forma. O esquema completo do arquivo template.json é encontrado no esquema de repositório JSON e é descrito em Referência para o template.json. Para saber mais sobre o arquivo template.json, veja o wiki de modelagem dotnet.

A parte symbols desse objeto JSON é usada para definir os parâmetros que podem ser utilizados no modelo. Nesse caso, há um parâmetro definido, ClassName. O parâmetro definido contém as seguintes configurações:

type - Esta é uma configuração obrigatória e deve ser definida como parameter.
description - A descrição do parâmetro, que é impressa na ajuda do modelo.
datatype - O tipo de dados do valor do parâmetro quando o parâmetro é usado.
replaces - Especifica um valor de texto que deve ser substituído em todos os arquivos de modelo pelo valor do parâmetro.
fileRename - Semelhante ao replaces, isso especifica um valor de texto que é substituído nos nomes de todos os arquivos de modelo pelo valor do parâmetro.
defaultValue - O valor padrão desse parâmetro quando o parâmetro não é especificado pelo usuário.

Quando o modelo é usado, o usuário pode fornecer um valor para o parâmetro ClassName e esse valor substitui todas as ocorrências de StringExtensions. Se um valor não for fornecido, o defaultValue será usado. Para esse modelo, há duas ocorrências de StringExtensions: o arquivo StringExtensions.cs e a classe StringExtensions. Como o defaultValue do parâmetro é StringExtensions, o nome do arquivo e o nome da classe permanecem inalterados se o parâmetro não for especificado ao usar o modelo. Quando um valor é especificado, por exemplo, dotnet new stringext -ClassName MyExts, o arquivo é renomeado MyExts.cs e a classe é renomeada para MyExts.

Para ver quais parâmetros estão disponíveis para um modelo, use o parâmetro -? com o nome do modelo:

dotnet new stringext -?

Que produz esta saída:

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

Agora que você já tem um arquivo .template.config/template.json válido, seu modelo está pronto para ser instalado. No terminal, acesse a pasta extensions e execute o seguinte comando para instalar o modelo localizado na pasta atual:

No Windows: dotnet new install .\
No Linux ou macOS: dotnet new install ./

Esse comando gera a lista de modelos instalados que deve incluir o seu.

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

Testar o modelo de item

Agora que você tem um modelo de item instalado, teste-o.

Navegue até a pasta test.

Crie um novo aplicativo de console com o dotnet new console, que gera um projeto de trabalho que você pode testar facilmente com o comando dotnet run.

dotnet new console

Você terá um resultado semelhante ao mostrado a seguir.

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.

Execute o projeto usando o seguinte comando.
```
dotnet run
```
Você obterá a saída a seguir.
```
Hello, World!
```
Execute dotnet new stringext para gerar o arquivo StringExtensions.cs a partir do modelo.
```
dotnet new stringext
```
Você obterá a saída a seguir.
```
The template "Example templates: string extensions" was created successfully.
```
Altere o código em Program.cs para inverter a cadeia de caracteres "Hello, World!" com o método de extensão fornecido pelo modelo.
```
Console.WriteLine("Hello, World!".Reverse());
```
Execute o programa novamente e veja que o resultado é revertido.
```
dotnet run
```
Você obterá a saída a seguir.
```
!dlroW ,olleH
```

Parabéns! Você criou e implantou um modelo de item com o .NET. Em preparação para a próxima parte desta série de tutoriais, desinstale o modelo que você criou. Certifique-se de excluir todos os arquivos e pastas na pasta test também. Isso leva você de volta a um estado limpo pronto para a próxima parte desta série de tutoriais.

Desinstalar o modelo

No terminal, acesse a pasta extensions e execute o seguinte comando para instalar os modelos localizados na pasta atual:

No Windows: dotnet new uninstall .\
No Linux ou macOS: dotnet new uninstall ./

Esse comando gera uma lista dos modelos que foram desinstalados, o que deve incluir o seu.

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

A qualquer momento, você pode usar dotnet new uninstall para ver uma lista de pacotes de modelos instalados, incluindo em cada pacote de modelo o comando para desinstalá-lo.

Próximas etapas

Neste tutorial, você criou um modelo de item. Para saber como criar um modelo de projeto, continue a ver essa série de tutoriais.

Criar um modelo de projeto

Compartilhar via