Tutorial: Criar um modelo de item

  • Artigo

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

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

Gorjeta

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

  • .NET SDK 7.0.100 ou uma versão posterior.

    O artigo de referência explica as noções básicas sobre modelos e como eles são montados. 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 .NET 7. No entanto, ele também se aplica ao .NET 6 e versões anteriores, com uma diferença: a dotnet new sintaxe é diferente. Os listsubcomandos , , , e devem ser --list, , --installe --uninstall opções, uninstallsearchinstall--searchrespectivamente.

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

Crie as pastas necessárias

Esta série usa uma "pasta de trabalho" onde a fonte do 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 trabalho e teste. Dentro da pasta de trabalho , crie uma subpasta chamada content.

A estrutura de pastas deve ter a seguinte aparência.

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 um 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 de extensões 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 reverte o conteúdo de uma cadeia de caracteres. Cole o 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 está 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 sua pasta de modelo.

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

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

Abra o template.json com seu editor de texto favorito e cole no 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"
      }
    }
  }

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

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

A symbols parte desse objeto JSON é usada para definir os parâmetros que podem ser usados no modelo. Neste 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 está impresso 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 deste 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 ClassName parâmetro, e esse valor substitui todas as ocorrências de StringExtensions. Se um valor não for fornecido, o defaultValue será usado. Para este modelo, há duas ocorrências de StringExtensions: o arquivo StringExtensions.cs e a classe StringExtensions. Como o 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 defaultValue 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 a seguinte 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ê tem um arquivo .template.config/template.json válido, seu modelo está pronto para ser instalado. No terminal, navegue até a pasta de extensões 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 ./

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

  1. Navegue até a pasta de teste .

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

    dotnet new console

    Você obtém uma saída semelhante à seguinte.

    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. Execute o projeto usando o seguinte comando.

    dotnet run

    Você obtém a seguinte saída.

    Hello, World!

  4. Execute dotnet new stringext para gerar o arquivo StringExtensions.cs a partir do modelo.

    dotnet new stringext

    Você obtém a seguinte saída.

    The template "Example templates: string extensions" was created successfully.

  5. Altere o código em Program.cs para reverter a "Hello, World!" cadeia de caracteres com o método de extensão fornecido pelo modelo.

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

    Execute o programa novamente e veja que o resultado é invertido.

    dotnet run

    Você obtém a seguinte saída.

    !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 de teste também. Isso faz com que você volte a um estado limpo pronto para a próxima parte desta série de tutoriais.

Desinstalar o modelo

No terminal, navegue até a pasta de extensões e execute o seguinte comando para desinstalar os modelos localizados na pasta atual:

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

Este comando gera uma lista dos modelos que foram desinstalados, 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 modelo instalados, incluindo para cada pacote de modelo o comando para desinstalá-lo.

Próximos passos

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

Criar um modelo de projeto