Modelos personalizados para o dotnet new

O SDK do .NET vem com muitos modelos já instalados e prontos para uso. O dotnet new comando não é apenas a maneira de usar um modelo, mas também como instalar e desinstalar modelos. Você pode criar seus próprios modelos personalizados para qualquer tipo de projeto, como um aplicativo, serviço, ferramenta ou biblioteca de classes. Você pode até mesmo criar um modelo que gera um ou mais arquivos independentes, como um arquivo de configuração.

Você pode instalar modelos personalizados de um pacote NuGet em qualquer feed do NuGet, fazendo referência diretamente a um arquivo .nupkg do NuGet ou especificando um diretório do sistema de arquivos que contém o modelo. O mecanismo de modelo oferece recursos que permitem substituir valores, incluir e excluir arquivos e executar operações de processamento personalizadas quando o modelo for usado.

O mecanismo de modelo é de software livre e o repositório de código online está em dotnet/templating no GitHub. Mais modelos, incluindo modelos de terceiros, podem ser encontrados usando dotnet new search. Para obter mais informações sobre como criar e usar modelos personalizados, consulte Como criar seus próprios modelos para o dotnet new e o wiki do repositório GitHub do dotnet/templating.

Para seguir um passo a passo e criar um modelo, confira o novo tutorial Criar um modelo personalizado para dotnet .

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

Um modelo é composto das 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 todos os arquivos e pastas que você deseja que o mecanismo de modelo use quando o dotnet new <TEMPLATE> comando for executado. O mecanismo de modelo foi projetado para usar projetos executáveis como código-fonte para produzir projetos. Isso tem várias vantagens:

• O mecanismo de modelo não exige que você insira tokens especiais no código-fonte do projeto.
• Os arquivos de código não são arquivos especiais ou modificados de forma alguma 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.
• Você cria, executa e depura seus projetos de modelo, assim como faz para qualquer um de seus outros projetos.
• Você pode criar rapidamente um modelo de um projeto existente apenas adicionando um arquivo de configuração ./.template.config/template.json ao projeto.

Arquivos e pastas armazenados no modelo não se limitam aos tipos formais de projeto do .NET. Arquivos e pastas de origem podem consistir em qualquer conteúdo que você deseja criar quando o modelo é usado, mesmo que o mecanismo de modelo produza apenas um arquivo como 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 passando opções para o dotnet new <TEMPLATE> comando. Um exemplo comum de lógica personalizada é fornecer um nome para uma classe ou variável no arquivo de código 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, o que é suficiente para criar um modelo funcional.

O esquema completo do arquivo template.json é encontrado no Repositório de Esquemas JSON. Para obter mais informações sobre o arquivo template.json, consulte o wiki de modelos do dotnet. Para obter exemplos mais profundos e informações sobre como tornar seus modelos visíveis no Visual Studio, confira os recursos que Sayed Hashimi criou.

Exemplo

Por exemplo, aqui está uma pasta de modelo que contém dois arquivos de conteúdo: console.cs e readme.txt. Há também a pasta necessária chamada .template.config que contém o arquivo template.json .

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

O arquivo template.json se parece com o seguinte:

{
  "$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 instalável. Depois que o pacote é instalado, o shortName poderá ser usado com o comando dotnet new. Por exemplo, dotnet new adatumconsole produziria os 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 for localizado para o idioma que corresponde à localidade atual, seus elementos aparecerão no mesmo idioma que a CLI. A localização é opcional ao criar novos modelos.

Os elementos localizáveis em um modelo são:

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

O JSON de localização consiste em 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 obter mais informações sobre como localizar modelos, consulte a página de localização do wiki de modelagem do dotnet.

Exemplo

Por exemplo, aqui está template.json arquivo 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 é empacotado com o comando dotnet pack e um arquivo .csproj . Como alternativa, o NuGet pode ser usado com o comando do pacote nuget junto com um arquivo .nuspec . No entanto, o NuGet requer o .NET Framework no Windows e 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 <PackageType> configuração é adicionada e definida como Template.
2. A <PackageVersion> configuração é adicionada e definida como um número de versão do NuGet válido.
3. A <PackageId> configuração é adicionada e definida como um identificador exclusivo. Esse identificador é usado para desinstalar o pacote de modelos e é usado por feeds do NuGet para registrar seu pacote de modelos.
4. As configurações de metadados genéricos devem ser definidas: <Title>, , <Authors>e <Description><PackageTags>.
5. A <TargetFramework> configuração deve ser definida, mesmo que o binário produzido pelo processo de modelo não seja usado. No exemplo abaixo, ele está definido como netstandard2.0.

Um pacote de modelo, na forma de um pacote NuGet .nupkg , requer que todos os modelos sejam armazenados na pasta de conteúdo 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 modelos:

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

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

Uma maneira fácil de estruturar seu pacote de modelos é colocar todos os modelos em pastas individuais e, em seguida, cada pasta de modelo dentro de uma pasta de modelos que está localizada no mesmo diretório que o 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 <ItemGroup> elemento, crie um <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> item.

Este é um exemplo de arquivo .csproj que segue todas essas diretrizes. Ele empacota a pasta filha de templates para a pasta do pacote content e exclui qualquer arquivo de código da compilação.

<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 arquivo e pasta do uso de um .csproj para criar um pacote de modelo. O arquivo MyDotnetTemplates.csproj e a pasta de modelos estão localizados na raiz de um diretório chamado project_folder. A pasta de modelos contém dois modelos, mytemplate1 e mytemplate2. Cada modelo tem arquivos de conteúdo e uma pasta .template.config com um arquivo de configuraçãotemplate.json .

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

Instalar um pacote de modelo

Use o comando dotnet new install para instalação de 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 a partir de uma fonte personalizada do NuGet

Forneça uma origem do NuGet personalizada (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 modelos a partir 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

Os modelos podem ser instalados a partir de uma pasta de modelo, como a pasta mytemplate1 do exemplo anterior. Especifique o caminho da pasta do .template.config . O caminho para o diretório de templates 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 instalados e 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 depois 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 os pacotes de modelo instalados por meio dotnet new install são mostrados na lista. Os pacotes de modelo integrados ao SDK do .NET não são mostrados.

Desinstalar um pacote de modelo

Use o novo comando de desinstalação do dotnet para desinstalar um pacote de modelo.

Se o pacote tiver sido 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 especificando um caminho para a pasta .template.config , use esse caminho para desinstalar o pacote. Você pode ver o caminho absoluto do pacote de modelo na saída fornecida pelo dotnet new uninstall comando. Para obter mais informações, consulte 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 for instalado, use o modelo executando o dotnet new <TEMPLATE> comando como faria com qualquer outro modelo pré-instalado. Você também pode especificar opções para o dotnet new comando, incluindo opções específicas do modelo que você configurou nas configurações do modelo. Forneça o nome curto do modelo diretamente para o comando:

dotnet new <TEMPLATE>

Consulte também

• Criar um modelo personalizado para o dotnet new (tutorial)
• Wiki do repositório GitHub dotnet/modelagem
• Exemplos de modelo
• Como criar seus próprios modelos para o dotnet new
• template.json esquema no Repositório de Esquemas JSON