Compartilhar via

Tutorial: Criar um modelo de item

Com o .NET, você pode criar e implantar modelos que geram projetos, arquivos e recursos. Este tutorial é a primeira parte 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.

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 de um caminho de arquivo.
  • Teste um modelo de item.
  • Desinstale um modelo de item.

Pré-requisitos

  • .NET 9 ou uma versão posterior.

  • O artigo de referência explica os conceitos básicos sobre modelos e como eles são montados. Algumas dessas informações são reiteradas aqui.

  • Abra um terminal e navegue até uma pasta em que você armazenará e testará os modelos.

Criar as pastas necessárias

Esta série usa uma "pasta de trabalho" em que a origem do modelo está contida e uma "pasta de teste" usada para testar seus modelos. As pastas de trabalho e de teste devem estar dentro da mesma pasta pai.

Primeiro, crie a pasta principal, o nome não importa. Em seguida, crie duas subpastas nomeadas como trabalho e teste. Dentro da pasta de trabalho , crie uma subpasta chamada conteúdo.

A estrutura de pastas deve ser semelhante à seguinte.

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ê cria 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 extensões.

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 fornece um método de extensão chamado Reverse que inverte 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 foi concluído, crie a configuração do modelo.

Criar a configuração de template

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

Os modelos são reconhecidos pelo .NET porque 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.confige 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 o código JSON a seguir 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 tags/type valor definido como item. Isso categoriza seu modelo como um modelo de "item". Não há nenhuma restrição sobre o tipo de modelo que você cria. Os valores item e project são nomes comuns que o .NET recomenda para que os usuários filtrem facilmente o tipo de template que estão procurando.

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

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

  • type - Essa é 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 a replaces, 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 ClassName parâmetro e esse valor substitui todas as ocorrências de StringExtensions. Se um valor não for fornecido, ele defaultValue será usado. Para este modelo, há duas ocorrências de StringExtensions: o arquivo StringExtensions.cs e a classe StringExtensions. Como o defaultValue 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 -?

O 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:

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.

  1. Navegue até a pasta de teste .

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

    dotnet new console

    Você obtém um resultado parecido com o 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 comando a seguir.

    dotnet run

    Você verá o seguinte resultado.

    Hello, World!

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

    dotnet new stringext

    Você obtém a saída a seguir.

    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 se o resultado foi invertido.

    dotnet run

    Você tem o seguinte resultado.

    !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. Exclua todos os arquivos e pastas na pasta de teste também. Isso o leva de volta 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 ./

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 modelo instalados, incluindo para 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 esta série de tutoriais.

Criar um modelo de projeto

  • Last updated on