Modelos personalizados para 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 gere 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 a um arquivo .nupkg do NuGet diretamente ou especificando um diretório do 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 o modelo é usado.

O mecanismo de modelo é de código aberto e o repositório de código on-line está em dotnet/templating no GitHub. Mais modelos, incluindo modelos de terceiros, podem ser encontrados usando dotnet new searcho . Para obter mais informações sobre como criar e usar modelos personalizados, consulte Como criar seus próprios modelos para dotnet new e o dotnet/templating GitHub repo Wiki.

Nota

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 Criar um modelo personalizado para dotnet new .

Modelos padrão do .NET

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

dotnet new list

Configuração

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

• O mecanismo de modelo não exige que você injete tokens especiais no código-fonte do seu projeto.
• Os arquivos de código não são arquivos especiais ou modificados de qualquer forma para trabalhar com o mecanismo de modelo. Assim, as ferramentas que você normalmente usa ao trabalhar com projetos também funcionam com conteúdo de modelo.
• Você cria, executa e depura seus projetos de modelo da mesma forma que faz para qualquer um dos seus outros projetos.
• Você pode criar rapidamente um modelo a partir de um projeto existente apenas adicionando um arquivo de configuração ./.template.config/template.json ao projeto.

Os arquivos e pastas armazenados no modelo não estão limitados aos tipos formais de projeto .NET. Os 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 fornecidas 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.

Membro	Tipo	Description
$schema	URI	O esquema JSON para o arquivo template.json . Os editores que suportam esquemas JSON habilitam os recursos de edição JSON quando o esquema é especificado. Por exemplo, o Visual Studio Code requer esse membro para habilitar o IntelliSense. Use um valor de http://json.schemastore.org/template.
author	string	O autor do modelo.
classifications	matriz(string)	Zero ou mais características do modelo que um usuário pode usar para encontrar o modelo ao pesquisá-lo. As classificações também aparecem na coluna Marcas quando aparecem em uma lista de modelos produzidos usando o dotnet new list comando.
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 selecionar o modelo que se aplica a ambientes onde o nome do modelo é especificado pelo usuário, não selecionado por meio de uma GUI. Por exemplo, o nome curto é útil ao usar modelos de um prompt de comando com comandos da CLI.
sourceName	string	O nome na árvore de origem para substituir pelo nome especificado pelo usuário. O mecanismo de modelo procurará qualquer ocorrência do mencionado no arquivo de configuração e o substituirá em nomes de arquivo e conteúdo de sourceName arquivo. O valor a ser substituído pode ser dado usando as opções ou --name durante a -n execução de um modelo. Se nenhum nome for especificado, o diretório atual será usado.
preferNameDirectory	Boolean	Indica se um diretório para o modelo deve ser criado se o nome for especificado, mas um diretório de saída não estiver definido (em vez de criar o conteúdo diretamente no diretório atual). O valor predefinido é false.

O esquema completo para o arquivo template.json é encontrado no JSON Schema Store. Para obter mais informações sobre o arquivo template.json , consulte o wiki de modelos 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 tem a seguinte aparência:

{
  "$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. Uma vez que o pacote é instalado, o shortName pode ser usado com o dotnet new comando. Por exemplo, dotnet new adatumconsole enviaria os console.cs arquivos e readme.txt para a pasta atual.

Localização de modelos

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

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

• Nome
• Autor
• Description
• Símbolos
  • Description
  • Nome a Apresentar
  • Descrições e nome de exibição das opções para parâmetros de escolha
• Pós-ações
  • Description
  • 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 é: , onde lang code corresponde a uma das opções CultureInfo. templatestrings.<lang code>.json Todos os arquivos de localização devem estar dentro da .template-config\localize pasta.

O JSON de localização consiste em pares de valores de chave:

• A chave é a referência a um elemento de template.json a ser localizado. Se o elemento for um 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 a localização de modelos, consulte a página de localização do wiki de modelos 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 o português do Brasil. O nome do arquivo será templatestrings.pt-BR.json para corresponder à cultura, e seria parecido com:

{
  "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."
}

Embalar um modelo em um pacote NuGet (arquivo nupkg)

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

O arquivo .csproj é ligeiramente diferente de um arquivo .csproj de projeto de código tradicional. Tenha em conta as definições seguintes:

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 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 genéricas de metadados devem ser definidas: <Title>, <Authors>, <Description>e <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, 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 para adicionar a um arquivo .csproj para garantir que o .nupkg gerado possa ser instalado como um pacote de modelos:

1. A <IncludeContentInPack> configuração é 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 está definida como content. Isso garante que os arquivos definidos como conteúdo sejam armazenados na pasta de conteúdo do pacote NuGet. Esta 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 seu 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 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.

Aqui está um exemplo de arquivo .csproj que segue todas essas diretrizes. Ele empacota a pasta filho de modelos para a pasta do pacote de conteúdo e exclui qualquer arquivo de código de ser 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 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 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

Nota

Para garantir que o pacote de modelo apareça no dotnet new search resultado, defina o tipo de pacote NuGet como Template.

Instalar um pacote de modelo

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

Para instalar um pacote de modelo a partir de um pacote NuGet armazenado em nuget.org

Use o identificador de 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 NuGet personalizada

Forneça uma fonte 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 modelo 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 a partir de um diretório do 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 .template.config . O caminho para o diretório de modelos não precisa ser absoluto.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Obter uma lista de pacotes de modelos instalados

O comando install, sem quaisquer outros parâmetros, 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 é o caminho da pasta .template.config . Apenas os pacotes de modelo instalados via dotnet new install são mostrados na lista. Os pacotes de modelo que são incorporados no 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 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 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 abreviado do modelo diretamente para o comando:

dotnet new <TEMPLATE>

Consulte também

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