Tutorial: Criar um modelo de projeto

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.

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

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

  • Criar os recursos de um modelo de projeto
  • Criar a pasta e o arquivo de configuração do modelo
  • Instalar um modelo a partir de um caminho de arquivos
  • Testar um modelo de item
  • Desinstalar um modelo de item

Pré-requisitos

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

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ê criará um novo projeto de console que substitui a saída de console padrão "Hello, World" por uma que é executada de forma assíncrona.

No terminal, navegue até a pasta working\templates 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
└───templates
    └───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:

await Console.Out.WriteAsync("Hello World with C#");

Compilar o projeto

Antes de concluir um modelo de projeto, você deve testá-lo para garantir que ele seja compilado e executado corretamente.

Em seu terminal, execute o seguinte comando:

dotnet run

Você obterá a saída a seguir.

Hello World with C#

Você pode excluir as pastas obj e bin criadas usando dotnet run. A exclusão desses arquivos garante que o modelo inclua apenas os arquivos relacionados ao modelo e não os arquivos resultantes de uma ação de compilação.

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

Os modelos são reconhecidos no .NET por uma pasta especial e um arquivo de configuração que está na raiz do modelo. Neste tutorial, a pasta de modelos está localizada em working\templates\consoleasync.

Quando você cria um modelo, todos os arquivos e pastas na pasta de modelos são incluídos como parte do modelo, exceto a pasta de configuração especial. Esta pasta de configuração chama-se .template.config.

Primeiro, crie uma nova subpasta chamada .template.config, insira-a. Em seguida, crie um novo arquivo chamado template.json. A estrutura da pasta deve ter a seguinte aparência.

working
└───templates
    └───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",
  "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, como name e shortName, mas também há um valor tags/type que é definido como project. Isso designa seu modelo como um modelo de projeto. 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 json com a lista de marcações classifications. São duas coisas diferentes, mas, infelizmente, nomeadas da mesma forma. O esquema completo do arquivo template.json é encontrado no Repositório de Esquema 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\templates\consoleasync

Success: <root path>\working\templates\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
    

    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. Para se preparar para a próxima parte desta série de tutoriais, você deverá desinstalar o modelo criado. Lembre-se de também excluir todos os arquivos da pasta test. Isso levará você de volta a um estado limpo, pronto para a próxima seção principal deste tutorial.

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\templates\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.