Modelos .NET para autores

Como autor de templates, cria templates .NET — blueprints que geram projetos, ficheiros ou outros recursos a partir de uma estrutura pré-definida. Quando os utilizadores executam dotnet new <shortName>, o motor de templates .NET lê o template e produz a saída no diretório atual. O diálogo Criar um novo projeto do Visual Studio também usa o motor de templates .NET para templates de projeto .NET, por isso os templates que crias para a CLI também funcionam no Visual Studio.

O SDK .NET vem com templates incorporados para pontos de partida comuns, como aplicações de consola, bibliotecas de classes e projetos ASP.NET. Para além desses modelos incorporados, pode criar os seus próprios modelos e distribuí-los como pacotes NuGet.

Este artigo é uma referência para autores de modelos. Cobre como os templates são estruturados, configurados e distribuídos. Para instruções passo a passo para criar e empacotar modelos, consulte a secção de Conteúdos Relacionados .

Tipos de modelo

O motor de templates .NET suporta três tipos de templates: templates de itens, templates de projeto e templates de solução.

  • Os templates de itens geram um ou mais ficheiros, como um ficheiro de código, ficheiro de configuração ou outro recurso, sem gerar um projeto inteiro à volta deles. Por exemplo, um template de item pode produzir um ficheiro de classe que adiciona um conjunto de métodos de extensão, ou um ficheiro de configuração JSON que segue um layout padrão que a sua equipa utiliza. Para aprender a construir um modelo de item, veja Tutorial: Criar um modelo de item.

  • Os templates de Project geram uma estrutura completa de project. O modelo de projeto de consola incorporado, por exemplo, produz um .csproj ficheiro, um Program.cs ficheiro e quaisquer outros ficheiros que compõem o projeto. Crie um modelo de projeto quando quiser dar aos utilizadores um ponto de partida completo do projeto em vez de ficheiros individuais. Para aprender a construir um modelo de projeto, consulte o Tutorial: Criar um modelo de projeto.

  • Os modelos de solução geram uma solução com um ou mais projetos. Por exemplo, um modelo de solução pode criar um projeto API emparelhado com um projeto de teste numa única etapa.

Quando crias o teu próprio modelo, declaras o seu tipo usando o tags.type campo no template.json ficheiro de configuração. Os valores válidos são "project", "item"e "solution". Estes valores permitem aos utilizadores filtrar resultados quando procuram modelos com dotnet new search ou dotnet new list.

Tip

Modelos de Project e solução aparecem no diálogo Criar um novo project do Visual Studio, mas os modelos de itens não aparecem no diálogo Adicionar>Novo Item. Os utilizadores podem aceder a modelos de itens a partir da dotnet new CLI.

Estrutura do modelo

Um template é uma pasta no disco que contém duas coisas: os ficheiros fonte do template e uma subpasta especial .template.config . Quando um utilizador executa dotnet new <shortName>, o motor de templates copia os ficheiros fonte para a localização de saída e aplica qualquer configuração que tenha definido para o template.

mytemplate/
├── console.cs
├── readme.txt
└── .template.config/
    ├── template.json
    └── icon.png

Os ficheiros fonte podem ser de qualquer tipo de ficheiro. O motor de templates não exige que injetes tokens ou marcadores especiais no código-fonte. Utiliza os ficheiros as-is, o que significa que podes construir, executar e depurar o projeto fonte de um template exatamente como um projeto .NET normal. Para transformar um projeto existente num modelo, adicione um .template.config/template.json ficheiro à raiz do projeto.

Pode, opcionalmente, injetar tokens de substituição ligados a parâmetros do template (símbolos) diretamente em ficheiros fonte e nomes de ficheiros template. Se os tokens não forem código-fonte válido, não podes construir, executar ou depurar o projeto fonte antes de o implementares como modelo. Os tokens não afetam os projetos que os utilizadores criam a partir do template implementado porque o motor de templates substitui-os durante a criação do projeto.

O único ficheiro obrigatório dentro .template.config é template.json. Esse ficheiro diz ao motor de templates tudo o que precisa: o nome do template, nome curto, autor, classificações e quaisquer parâmetros que os utilizadores possam passar ao criar a partir do template. Também podes colocar um icon.png ficheiro na .template.config pasta. O terminal não mostra ícones, mas o Visual Studio mostra o ícone ao lado do modelo no diálogo Criar um novo projeto. Uma PNG 128×128 funciona bem.

O ficheiro template.json

O template.json ficheiro é a única configuração necessária num modelo. Fica dentro da .template.config pasta e indica ao motor de templates como apresentar e processar o seu modelo. A tabela seguinte descreve campos comuns obrigatórios e opcionais:

Campo Tipo Obrigatório Description
$schema URI Não O esquema JSON para template.json. Definido para https://json.schemastore.org/template ativar o IntelliSense em editores como o Visual Studio Code.
author cadeia (de caracteres) Não O autor do modelo.
classifications matriz de strings Não Etiquetas que os utilizadores podem usar para encontrar o modelo com dotnet new search ou dotnet new list. Estes valores aparecem na coluna Etiquetas da lista de modelos.
description cadeia (de caracteres) Não Uma descrição do que o modelo cria.
identity cadeia (de caracteres) Sim Um identificador único para o modelo.
name cadeia (de caracteres) Sim O nome de exibição do modelo é mostrado aos utilizadores.
shortName cadeia (de caracteres) Sim O nome curto que os utilizadores passam para dotnet new para criar a partir do modelo, como console ou classlib.
sourceName cadeia (de caracteres) Não Uma cadeia nos seus ficheiros de origem e nomes de ficheiros que o motor de templates substitui pelo nome que o utilizador fornece via -n ou --name. Se o utilizador não fornecer um nome, o motor usa o nome atual do diretório.
preferNameDirectory Booleano Não Quando true e o utilizador fornece um nome mas não um diretório de saída, o motor de templates cria um novo diretório com esse nome em vez de escrever ficheiros no diretório atual. A predefinição é false.
tags objecto Não Metadados que identificam propriedades como a linguagem do modelo e o tipo. Use tags.language para a linguagem e tags.type para project, item, ou solution.

Dois campos merecem atenção extra. O sourceName campo é como os templates tratam da nomeação: define-o para uma string que aparece nos nomes dos ficheiros e código-fonte (como MyTemplate), e o motor de templates substitui cada ocorrência pelo nome que o utilizador passa ao criar o modelo. O classifications campo controla a descoberta; escolha etiquetas que descrevam com precisão o propósito do seu modelo para que os utilizadores possam encontrá-lo durante a pesquisa.

Aqui está um mínimo template.json para um modelo de consola:

{
  "$schema": "https://json.schemastore.org/template",
  "author": "Your Name",
  "classifications": [ "Common", "Console" ],
  "description": "Creates a console application.",
  "identity": "MyCompany.ConsoleTemplate.CSharp",
  "name": "My Console App",
  "shortName": "myconsole",
  "sourceName": "MyConsoleApp",
  "tags": {
    "language": "C#",
    "type": "project"
  }
}

O esquema completo está disponível na JSON Schema Store. Para opções avançadas de configuração como inclusão condicional de ficheiros, ações pós-criação e modelos multi-projeto, consulte a wiki do GitHub dotnet/templating.

Parâmetros do modelo (símbolos)

A symbols secção em template.json define os parâmetros que os utilizadores podem passar ao criar a partir do seu modelo. Cada símbolo torna-se uma opção CLI em dotnet new <shortName>, por isso um símbolo com nome ClassName torna-se --ClassName (ou -C se definires um nome curto).

Cada entrada de símbolo suporta as seguintes definições comuns:

Configuração Description
type Deve ser "parameter" para parâmetros direcionados ao utilizador.
description Mostrado no modelo de ajuda quando os utilizadores executam dotnet new <shortName> -?.
datatype O tipo de dado esperado, como "text", "bool", ou "choice".
replaces Uma cadeia no conteúdo do teu ficheiro fonte que o motor template substitui pelo valor do parâmetro.
fileRename Uma cadeia no teu ficheiro de origem nomeia que o motor de templates substitui pelo valor do parâmetro.
defaultValue O valor usado quando o utilizador não fornece o parâmetro.

As replaces definições e fileRename são como os símbolos influenciam a substituição. Quando um utilizador fornece um valor, o motor de templates substitui todas as ocorrências da replaces cadeia dentro do conteúdo dos ficheiros e todas as ocorrências da fileRename cadeia nos nomes dos ficheiros. Se o utilizador não fornecer um valor, defaultValue o é usado em vez disso.

Por exemplo, o símbolo seguinte permite aos utilizadores definir o nome da classe quando criam a partir do modelo. O ficheiro é renomeado e a classe dentro dele é atualizada para corresponder a:

"symbols": {
  "ClassName": {
    "type": "parameter",
    "description": "The name of the code file and class.",
    "datatype": "text",
    "replaces": "StringExtensions",
    "fileRename": "StringExtensions",
    "defaultValue": "StringExtensions"
  }
}

Com este símbolo definido, um utilizador pode executar dotnet new <shortName> --ClassName MyHelpers para produzir um ficheiro nomeado MyHelpers.cs contendo uma classe chamada MyHelpers. Sem a flag, o ficheiro e a classe mantêm o nome StringExtensionspadrão .

Para verificar os parâmetros que o seu modelo expõe, passe -? para o seu nome curto depois de o instalar:

dotnet new <shortName> -?

Pacotes de modelos

Um pacote de templates é um ficheiro NuGet (.nupkg) que agrupa um ou mais dos seus templates. Quando um utilizador instala o seu pacote de templates, o motor de templates .NET regista todos os templates dentro dele de uma vez. Os pacotes são a forma padrão de distribuir modelos. Publique um único pacote para NuGet.org ou um feed privado do NuGet, ou partilhe um ficheiro local .nupkg , e os utilizadores obtêm toda a coleção com um único comando.

Para construir um pacote template, use um ficheiro de projeto C# (.csproj) configurado para funcionar como um projeto de empacotamento em vez de um projeto de compilação. As definições principais que fazem isto funcionar são:

Configuração valor Purpose
PackageType Template Marca o pacote como um modelo para que apareça nos dotnet new search resultados.
IncludeContentInPack true Inclui ficheiros de conteúdo no pacote NuGet.
IncludeBuildOutput false Impede que binários compilados sejam adicionados ao pacote.
ContentTargetFolders content Coloca as tuas pastas de templates dentro da content pasta do pacote NuGet, que é onde o motor de templates espera encontrá-las.

O templatepack modelo de projeto fornece a forma mais fácil de criar um projeto de embalagem:

  1. Instala a Microsoft. Pacote NuGet TemplateEngine.Authoring.Templates:

    dotnet new install Microsoft.TemplateEngine.Authoring.Templates

  2. Crie o projeto de embalagem:

    dotnet new templatepack -n <PackageName>

O projeto gerado inclui as definições corretas .csproj , uma content pasta para os seus modelos e tarefas do MSBuild para validação de modelos e localização opcional.

Para um guia completo de criação, embalagem e publicação de um pacote modelo, veja Tutorial: Criar um pacote modelo.

Teste o seu modelo localmente

Durante o desenvolvimento do modelo, instala o teu modelo diretamente da pasta para o testar sem antes construir um pacote. Passe o caminho para o diretório que contém a .template.config pasta:

dotnet new install ./mytemplate/

Para ver todos os pacotes de templates instalados e o comando exato para desinstalar cada um, execute dotnet new uninstall sem argumentos:

dotnet new uninstall

Para desinstalar um modelo instalado a partir de um diretório, passe pelo mesmo caminho de diretório que usou para o instalar:

dotnet new uninstall ./mytemplate/

Quando estiveres pronto para partilhar o teu modelo, embala-o como um pacote NuGet (ver pacotes de modelos) e distribui-o. Os utilizadores instalam o seu modelo publicado com dotnet new install um dos seguintes argumentos de fonte:

  • Um ID de pacote NuGet, que instala a versão estável mais recente a partir das fontes NuGet configuradas para o diretório atual:

    dotnet new install AdatumCorporation.ConsoleTemplate.CSharp

  • Um ID de pacote NuGet com um URL de feed personalizado. A --nuget-source opção utiliza o feed especificado, além das fontes NuGet configuradas, apenas para essa instalação:

    dotnet new install AdatumCorporation.ConsoleTemplate.CSharp --nuget-source https://mynugetfeed.example.com/v3/index.json

  • Um caminho para um ficheiro local .nupkg :

    dotnet new install ./AdatumCorporation.ConsoleTemplate.CSharp.1.0.0.nupkg

Warning

Os templates podem executar tarefas do MSBuild e código arbitrário durante a criação do projeto. Instala apenas modelos de fontes de confiança.

Para desinstalar um pacote instalado a partir de uma fonte NuGet ou de um ficheiro local .nupkg , use o ID do pacote NuGet:

dotnet new uninstall AdatumCorporation.ConsoleTemplate.CSharp

Os templates do SDK incorporados não aparecem na lista de desinstalação e não podem ser removidos com dotnet new uninstall.

Localização de modelos

O motor de templates .NET suporta a localização opcional dos metadados dos templates. Quando fornece ficheiros de localização, hosts como dotnet new e o diálogo Visual Studio New Project mostram o nome do modelo, a descrição e a informação do símbolo na língua do utilizador em vez da língua original.

Os seguintes campos modelo suportam localização:

  • name
  • author
  • description
  • Símbolo description e displayName
  • Descrição e nome de exibição para cada escolha num parâmetro de escolha
  • Após a ação description e manualInstructions

Para adicionar localização, cria uma localize subpasta dentro .template.config e adiciona um ficheiro JSON por língua. Nomeie cada ficheiro templatestrings.<lang-code>.json, onde <lang-code> corresponde a um nome válido CultureInfo , como pt-BR, zh-Hans, ou de. Cada ficheiro contém pares-chave-valor onde a chave é um caminho para o elemento em template.json, usado / como delimitador para campos aninhados.

Por exemplo, dado um template.json com o seguinte conteúdo:

{
  "$schema": "https://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."
    }
  }
}

Um ficheiro de localização em português brasileiro com o nome templatestrings.pt-BR.json seria assim:

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

O motor de templates analisa estes ficheiros quando carrega a informação do template e devolve automaticamente valores localizados com base na cultura atual da interface—não são necessários passos adicionais ao utilizador.

A localização é opcional. Se não incluir ficheiros de localização, o template funciona normalmente e mostra sempre os valores de template.json. Para mais informações, consulte a página de localização da wiki dotnet/templating.

Integração com Visual Studio

O diálogo Criar um novo projeto do Visual Studio utiliza o motor de templates .NET para templates de projeto .NET. Modelos que crias para dotnet new trabalhos no Visual Studio também, sem qualquer configuração extra. Quando um utilizador instala o seu pacote de templates com dotnet new install, o Visual Studio deteta automaticamente e apresenta esses templates no diálogo.

Os modelos de Project e solução aparecem no diálogo Criar um novo project juntamente com os templates SDK incorporados. Os utilizadores podem encontrar modelos por nome, língua ou etiquetas a partir do classifications campo no ficheiro do template.json modelo. Classificações precisas ajudam o seu modelo a surgir nas categorias de filtro corretas, por isso escolha-as com cuidado. Para dar ao seu modelo um aspeto polido no diálogo, adicione um icon.png à .template.config pasta — o Visual Studio mostra-o ao lado do nome do seu modelo.

Os modelos de itens não aparecem atualmente no diálogo Adicionar>Novo Item . Os utilizadores ainda podem usar modelos de itens com o dotnet new comando no terminal.

Para tornar o seu modelo acessível a Visual Studio utilizadores que ainda não o instalaram, publique o seu pacote de modelos na nuget.org. A janela de diálogo Criar um novo projeto inclui uma opção Instalar mais modelos na opção de pesquisa online que pesquisa nuget.org pacotes de modelos. Quando um utilizador instala o seu pacote através dessa opção, o Visual Studio utiliza o mesmo mecanismo de instalação que dotnet new installo .

Para orientações mais profundas sobre integração específica do Visual Studio — como controlar a ordem de ordenação dos templates e configurar opções adicionais específicas do IDE — consulte o repositório de templates e samples da Sayed Hashimi.

Conteúdo relacionado

  • Last updated on