Tutorial: Criar um modelo de projeto

  • Artigo

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

Dica

Os modelos oficiais do .NET que são enviados com o SDK do .NET podem ser encontrados nos seguintes repositórios:

Modelos Repositório
Console, biblioteca de classes e modelos de item comuns dotnet/sdk
Modelos ASP.NET e Blazor dotnet/aspnetcore
Modelos de Aplicativo de Página Única do ASP.NET dotnet/spa-templates
Modelos do WPF dotnet/wpf
Modelos do Windows Forms dotnet/winforms
Modelos de teste dotnet/test-templates
Modelos MAUI dotnet/maui

Você pode exibir os modelos instalados no computador executando o comando dotnet new list.

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

  • Crie os recursos de um modelo de projeto.
  • 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

  • Conclua a parte 1 desta série de tutoriais.
  • Abra um terminal e navegue até a pasta working\content.

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 um modelo de projeto

Os modelos de projeto produzem projetos prontos para execução que ajudam os usuários a começar com um conjunto de códigos de trabalho. O .NET Core inclui alguns modelos de projeto, como um aplicativo de console ou uma biblioteca de classes. Neste exemplo, você cria um novo projeto de aplicativo de console que substitui a saída padrão do console Olá, Mundo por uma que é executada de forma assíncrona.

Em seu terminal, navegue até a pasta working\content e crie uma nova subpasta chamada consoleasync. Insira a subpasta e execute dotnet new console para gerar o aplicativo de console padrão. Você editará os arquivos produzidos por este modelo para criar um novo modelo.

working
└───content
    └───consoleasync
            consoleasync.csproj
            Program.cs

Modificar o Program.cs

Abra o arquivo Program.cs. O projeto de console padrão não grava de forma assíncrona na saída do console, portanto, vamos adicioná-lo. Altere seu código para o seguinte e salve o arquivo:

// See https://aka.ms/new-console-template for more information
await Console.Out.WriteAsync("Hello World with C#");

Agora que você tem o conteúdo do modelo criado, é necessário criar a configuração do modelo na pasta raiz do modelo.

Criar a configuração do modelo

Neste tutorial, sua pasta de modelos está localizada em working\content\consoleasync.

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

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

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

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

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Me",
  "classifications": [ "Common", "Console" ],
  "identity": "ExampleTemplate.AsyncProject",
  "name": "Example templates: async project",
  "shortName": "consoleasync",
  "sourceName":"ExampleTemplate.AsyncProject",
  "tags": {
    "language": "C#",
    "type": "project"
  }
}

Esse arquivo de configuração contém todas as configurações do modelo. Você pode ver as configurações básicas, tais como name e shortName, mas também há um valor de tags/type definido como project. Isso categoriza seu modelo como um modelo "project". 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 sourceName é o que é substituído quando o usuário usa o modelo. O valor de sourceName no arquivo de configuração é pesquisado em todos os nomes de e conteúdo de arquivos e, por padrão, é substituído pelo nome da pasta atual. Quando o parâmetro -n ou --name passar com o comando dotnet new, o valor fornecido é usado em vez do nome da pasta atual. No caso desse modelo, consoleasync é substituído no nome do arquivo .csproj.

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. Elas são dois conceitos diferentes que, infelizmente, são chamados da mesma forma. O esquema completo do arquivo template.json é encontrado em 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.

Agora que você já tem um arquivo .template.config/template.json válido, seu modelo está pronto para ser instalado. Antes de instalar o modelo, exclua todas as pastas extras que você não deseja incluir no modelo, como as pastas bin ou obj. No terminal, navegue até a pasta consoleasync e execute dotnet new install .\ para instalar o modelo localizado na pasta atual. Se você estiver usando um sistema operacional Linux ou MacOS, use uma barra invertida: dotnet new install ./.

dotnet new install .\

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

The following template packages will be installed:
   <root path>\working\content\consoleasync

Success: <root path>\working\content\consoleasync installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: async project                  consoleasync             [C#]              Common/Console

Testar o modelo do projeto

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

  1. Navegue até a pasta test.

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

    dotnet new consoleasync -n MyProject

    Você obterá a saída a seguir.

    The template "Example templates: async project" was created successfully.

  3. Execute o projeto usando o seguinte comando.

    dotnet run

    Você obterá a saída a seguir.

    Hello World with C#

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

Desinstalar o modelo

No terminal, acesse a pasta consoleasync e execute o seguinte comando para instalar o modelo localizado 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\consoleasync 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 projeto. Para aprender como empacotar os modelos de item e projeto em um arquivo simples, continue a ver esta série de tutoriais.

Criar um pacote de modelos