Modelos personalizados para dotnet new

  • Artigo

O SDK do .NET apresenta muitos modelos já instalados e prontos para uso. O comando dotnet new não é apenas sobre como usar um modelo, mas também como instalar e desinstalar os modelos. Você pode criar seus próprios modelos personalizados para qualquer tipo de projeto, como um aplicativo, um serviço, uma ferramenta ou uma biblioteca de classes. É possível, inclusive, criar um modelo que gere um ou mais arquivos independentes, como um arquivo de configuração.

É possível instalar modelos personalizados a partir de um pacote NuGet em qualquer feed do NuGet, bastando para isso fazer referência a um arquivo .nupkg do NuGet diretamente ou especificando um diretório de sistema de arquivos que contenha o modelo. O mecanismo de modelo oferece recursos que permitem substituir valores, incluir e excluir arquivos e executar operações de processamento personalizadas quando seu modelo é usado.

O mecanismo de modelo é um software livre e o repositório de código online fica em dotnet/modelagem no GitHub. Mais modelos, incluindo modelos de terceiros, podem ser encontrados usando dotnet new search. Para obter mais informações sobre a criação e o uso de modelos personalizados, consulte How to create your own templates for dotnet new (Como criar seus próprios modelos para dotnet new) e o Wiki do repositório GitHub dotnet/modelagem.

Observação

Os exemplos de modelos estão disponíveis no repositório dotnet/templating do GitHub.

Para seguir um passo a passo e criar um modelo, consulte o tutorial Create a custom template for dotnet new (Criar um modelo personalizado para dotnet new).

Modelos padrão do .NET

Ao instalar o SDK do .NET, você recebe dezenas de modelos internos para criar projetos e arquivos, incluindo aplicativos de console, bibliotecas de classes, projetos de teste de unidade, aplicativos ASP.NET Core (incluindo projetos Angular e React) e arquivos de configuração. Para listar os modelos internos, execute o comando dotnet new list:

dotnet new list

Configuração

O modelo é composto pelas seguintes partes:

  • Arquivos e pastas de origem.
  • Um arquivo de configuração (template.json).

Arquivos e pastas de origem

Os arquivos e pastas de origem incluem os arquivos e pastas que você desejar que o mecanismo de modelo use quando o comando dotnet new <TEMPLATE> for executado. O mecanismo de modelo foi desenvolvido para usar projetos executáveis como código-fonte para produzir os projetos. Isso tem várias vantagens:

  • O mecanismo de modelo não exige que você insira tokens especiais no código-fonte do seu projeto.
  • Os arquivos de código não são arquivos especiais nem modificados de nenhuma maneira para trabalhar com o mecanismo de modelo. Portanto, as ferramentas que você normalmente usa ao trabalhar com projetos também funcionam com o conteúdo do modelo.
  • Compile, execute e depurar seus projetos de modelo assim como você faz com quaisquer outros projetos.
  • É possível criar rapidamente um modelo com base em um projeto existente simplesmente adicionando um arquivo de configuração ./.template.config/template.json ao projeto.

Os arquivos e pastas armazenados no modelo não são limitados aos tipos de projeto .NET formais. Os arquivos e pastas de origem podem ser compostos por qualquer conteúdo que você queira criar quando o modelo é usado, mesmo se o mecanismo do modelo produzir apenas um arquivo para sua saída.

Os arquivos gerados pelo modelo podem ser modificados com base na lógica e nas configurações que você forneceu no arquivo de configuração template.json. O usuário pode substituir essas configurações transmitindo opções para o comando dotnet new <TEMPLATE>. Um exemplo comum de lógica personalizada é fornecer o nome de uma classe ou variável no arquivo de código que é implantado por um modelo.

template.json

O arquivo template.json é colocado em uma pasta .template.config no diretório raiz do modelo. O arquivo fornece informações de configuração para o mecanismo de modelo. A configuração mínima requer os membros mostrados na tabela a seguir, suficiente para criar um modelo funcional.

Membro Type Descrição
$schema URI O esquema JSON do arquivo template.json. Os editores que dão suporte a esquemas JSON habilitam recursos de edição de JSON quando o esquema é especificado. Por exemplo, o Visual Studio Code requer que esse membro habilite o IntelliSense. Use um valor de http://json.schemastore.org/template.
author string O autor do modelo.
classifications array(string) Zero ou mais características do modelo que um usuário pode usar para localizá-lo ao procurá-lo. As classificações também são exibidas na coluna Marcas quando ela é exibida em uma lista de modelos produzida usando o comando dotnet new list.
identity string Um nome exclusivo para este modelo.
name string O nome do modelo que os usuários devem ver.
shortName string Um nome abreviado padrão para seleção do modelo aplicável aos ambientes em que o nome do modelo é especificado pelo usuário, não selecionado por uma GUI. Por exemplo, o nome curto é útil ao usar os modelos em um prompt de comando com comandos CLI.
sourceName string O nome na árvore de origem a ser substituído pelo nome especificado pelo usuário. O mecanismo de modelo vai procurar qualquer ocorrência do sourceName mencionado no arquivo de configuração e substituí-lo em nomes de arquivo e conteúdos de arquivo. O valor a ser substituído pode ser fornecido usando as opções -n ou --name durante a execução de um modelo. Se nenhum nome for especificado, o diretório atual será usado.
preferNameDirectory Boolean Indica se um diretório deverá ser criado para o modelo se o nome for especificado, mas não houver um diretório de saída definido (em vez de criar o conteúdo diretamente no diretório atual). O valor padrão é false.

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. Para obter exemplos mais detalhados e informações de como deixar os modelos visíveis no Visual Studio, confira os recursos que Sayed Hashimi criou.

Exemplo

Este é um exemplo de pasta de modelo que contém dois arquivos de conteúdo: console.cs e readme.txt. Há ainda uma pasta obrigatória chamada .template.config que contém o arquivo template.json.

└───mytemplate
    │   console.cs
    │   readme.txt
    │
    └───.template.config
            template.json

O arquivo template.json será parecido com este:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Travis Chau",
  "classifications": [ "Common", "Console" ],
  "identity": "AdatumCorporation.ConsoleTemplate.CSharp",
  "name": "Adatum Corporation Console Application",
  "shortName": "adatumconsole"
}

A pasta mytemplate é um pacote de modelo que pode ser instalado. Depois que o pacote estiver instalado, o shortName poderá ser usado com o comando dotnet new. Por exemplo, dotnet new adatumconsole resultaria nos arquivos console.cs e readme.txt para a pasta atual.

Localização de modelo

Os modelos do .NET são localizáveis. Se um modelo estiver localizado para o idioma correspondente à localidade atual, os elementos dele aparecerão no mesmo idioma que a CLI. A localização é opcional ao criar modelos.

Estes são os elementos localizáveis em um modelo:

  • Nome
  • Autor
  • Descrição
  • Símbolos
    • Descrição
    • Nome de exibição
    • Descrições e nome de exibição das opções dos parâmetros de escolha
  • Ações de postagem
    • Descrição
    • Instruções manuais

Os arquivos de localização têm formato JSON e deve existir apenas um arquivo por cultura. A convenção de nomenclatura é: templatestrings.<lang code>.json, em que lang code corresponde a uma das opções de CultureInfo. Todos os arquivos de localização devem estar dentro da pasta .template-config\localize.

O JSON de localização é composto por pares chave-valor:

  • A chave é a referência a um elemento de template.json a ser localizado. Se o elemento for filho, use o caminho completo com um delimitador /.
  • O valor é a cadeia de caracteres de localização do elemento fornecido pela chave.

Para saber mais sobre como localizar modelos, consulte a página de localização da wiki de modelagem de dotnet.

Exemplo

Por exemplo, este é um arquivo template.json com alguns campos localizáveis:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Microsoft",
  "classifications": "Config",
  "name": "EditorConfig file",
  "description": "Creates an .editorconfig file for configuring code style preferences.",
  "symbols": {
    "Empty": {
      "type": "parameter",
      "datatype": "bool",
      "defaultValue": "false",
      "displayName": "Empty",
      "description": "Creates empty .editorconfig instead of the defaults for .NET."
    }
  }
}

E alguns campos devem ser localizados para português brasileiro. O nome do arquivo será templatestrings.pt-BR.json, para corresponder à cultura, e terá a seguinte aparência:

{
  "author": "Microsoft",
  "name": "Arquivo EditorConfig",
  "description": "Cria um arquivo .editorconfig para configurar as preferências de estilo de código.",
  "symbols/Empty/displayName": "Vazio",
  "symbols/Empty/description": "Cria .editorconfig vazio em vez dos padrões para .NET."
}

Empacotar um modelo em um pacote NuGet (arquivo nupkg)

Um modelo personalizado é fornecido com o comando dotnet pack e um arquivo csproj. Como alternativa, NuGet pode ser usado com o comando nuget pack com um arquivo .nuspec. No entanto, o NuGet requer o .NET Framework no Windows e o Mono no Linux e no macOS.

O arquivo .csproj é ligeiramente diferente de um arquivo .csproj de projeto de código tradicional. Observe as seguintes configurações:

  1. A configuração <PackageType> é adicionada e definida como Template.
  2. A configuração <PackageVersion> é adicionada e definida como um número de versão do NuGet válido.
  3. A configuração <PackageId> é adicionada e definida como um identificador exclusivo. Esse identificador é usado para desinstalar o pacote de modelo e também pelos feeds do NuGet para registrar seu pacote de modelo.
  4. As configurações genéricas de metadados devem ser definidas: <Title>, <Authors>, <Description> e <PackageTags>.
  5. A configuração <TargetFramework> deve ser definida, mesmo que o binário produzido pelo processo de modelo não seja usado. No exemplo abaixo, ela é definida como netstandard2.0.

Um pacote de modelo, na forma de um pacote NuGet .nupkg, requer que todos os modelos sejam armazenados na pasta content dentro do pacote. Há mais algumas configurações a serem adicionadas a um arquivo .csproj para garantir que o .nupkg gerado possa ser instalado como um pacote de modelo:

  1. A configuração <IncludeContentInPack> é definida como true para incluir qualquer arquivo de projeto defina como conteúdo no pacote NuGet.
  2. A configuração <IncludeBuildOutput> é definida como false para excluir todos os binários gerados pelo compilador do pacote NuGet.
  3. A configuração <ContentTargetFolders> é definida como content. Isso garante que os arquivos definidos como conteúdo sejam armazenadas na pasta content do pacote NuGet. Essa pasta no pacote NuGet é analisada pelo sistema de modelo do dotnet.

Uma maneira fácil de impedir que todos os arquivos de código sejam compilados pelo seu projeto de modelo é usar o item <Compile Remove="**\*" /> em seu arquivo de projeto, dentro de um elemento <ItemGroup>.

Uma maneira fácil de estruturar seu pacote de modelo é colocar todos os modelos em pastas individuais e, em seguida, cada pasta de modelo dentro de uma pasta templates que está localizada no mesmo diretório que seu arquivo .csproj. Dessa forma, você pode usar um único item de projeto para incluir todos os arquivos e pastas nos modelos como conteúdo. Dentro de um elemento <ItemGroup>, crie um item <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />.

Veja a seguir um exemplo de arquivo .csproj que segue todas essas diretrizes. Ele empacota a pasta filho templates na pasta do pacote content e impede que qualquer arquivo de código seja compilado.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <PackageType>Template</PackageType>
    <PackageVersion>1.0</PackageVersion>
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <Title>AdatumCorporation Templates</Title>
    <Authors>Me</Authors>
    <Description>Templates to use when creating an application for Adatum Corporation.</Description>
    <PackageTags>dotnet-new;templates;contoso</PackageTags>
    <TargetFramework>netstandard2.0</TargetFramework>

    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />
    <Compile Remove="**\*" />
  </ItemGroup>

</Project>

O exemplo a seguir demonstra a estrutura de arquivos e pastas ao usar um .csproj para criar um pacote de modelo. O arquivo MyDotnetTemplates.csproj e a pasta templates estão localizados na raiz de um diretório chamado project_folder. A pasta templates contém dois modelos, mytemplate1 e mytemplate2. Cada modelo tem arquivos de conteúdo e uma pasta .template.config com um arquivo de configuração template.json.

project_folder
│   MyDotnetTemplates.csproj
│
└───templates
    ├───mytemplate1
    │   │   console.cs
    │   │   readme.txt
    │   │
    │   └───.template.config
    │           template.json
    │
    └───mytemplate2
        │   otherfile.cs
        │
        └───.template.config
                template.json

Observação

Para garantir que o pacote de modelo seja exibido no resultado dotnet new search, defina o tipo de pacote NuGet como Template.

Instalar um pacote de modelo

Use o comando dotnet new install para instalar um pacote de modelo.

Para instalar um pacote de modelo por meio de um pacote NuGet armazenado em nuget.org

Use o identificador do pacote NuGet para instalar um pacote de modelo.

dotnet new install <NUGET_PACKAGE_ID>

Para instalar um pacote de modelo de uma fonte personalizada do NuGet

Forneça uma fonte personalizada do NuGet (por exemplo, https://api.my-custom-nuget.com/v3/index.json).

dotnet new --install <NUGET_PACKAGE_ID> --nuget-source <SOURCE>

Para instalar um pacote de modelo por meio de um arquivo nupkg local

Forneça o caminho para um arquivo de pacote NuGet .nupkg.

dotnet new install <PATH_TO_NUPKG_FILE>

Para instalar um pacote de modelo por meio de um diretório de sistema de arquivos

Modelos podem ser instalados de uma pasta de modelo, como a pasta mytemplate1 do exemplo acima. Especifique o caminho da pasta .template.config. O caminho para o diretório de modelo não precisa ser absoluto.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Obter uma lista de pacotes de modelo instalados

O comando de desinstalação, sem nenhum outro parâmetro, lista todos os pacotes de modelos e os modelos incluídos.

dotnet new uninstall

Esse comando retorna algo semelhante à seguinte saída:

Currently installed items:
   Microsoft.Azure.WebJobs.ProjectTemplates
      Version: 4.0.1942
      Details:
         Author: Microsoft
         NuGetSource: https://api.nuget.org/v3/index.json
      Templates:
         Azure Functions (func) C#
         Azure Functions (func) F#
      Uninstall Command:
         dotnet new uninstall Microsoft.Azure.WebJobs.ProjectTemplates
...

O primeiro nível de itens após Currently installed items: são os identificadores usados na desinstalação de um pacote de modelo. E, no exemplo anterior, Microsoft.Azure.WebJobs.ProjectTemplates está listado. Se o pacote de modelo foi instalado usando um caminho do sistema de arquivos, esse identificador será o caminho da pasta .template.config. Somente pacotes de modelo instalados por meio de dotnet new install são mostrados na lista. Pacotes de modelo integrados ao SDK do .NET não são mostrados.

Desinstalar um pacote de modelo

Use o comando dotnet new uninstall para desinstalar um pacote de modelo.

Se o pacote foi instalado por um feed do NuGet ou por um arquivo .nupkg diretamente, forneça o identificador.

dotnet new uninstall <NUGET_PACKAGE_ID>

Se o pacote foi instalado por meio da especificação de um caminho para a pasta .template.config, use esse caminho para desinstalá-lo. Veja o caminho absoluto do pacote de modelo na saída fornecida pelo comando dotnet new uninstall. Para saber mais, confira a seção Obter uma lista de modelos instalados.

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Criar um projeto usando um modelo personalizado

Depois que um modelo é instalado, use o modelo executando o comando dotnet new <TEMPLATE> como você faria com qualquer outro modelo pré-instalado. Também é possível especificar opções para o comando dotnet new, incluindo opções específicas do modelo definidas nas configurações de modelo. Forneça o nome curto do modelo diretamente no comando:

dotnet new <TEMPLATE>

Confira também