modelos de .NET para autores

Como autor de modelo, você cria modelos de .NET – blueprints que geram projetos, arquivos ou outros recursos de uma estrutura predefinida. Quando os usuários são executadosdotnet new <shortName>, o mecanismo de modelo .NET lê o modelo e produz a saída no diretório atual. A caixa de diálogo Criar um novo projeto do Visual Studio também usa o mecanismo de modelo .NET para modelos de projeto .NET, portanto, os modelos criados para a CLI também funcionam em Visual Studio.

O SDK do .NET é fornecido com modelos internos para pontos de partida comuns, como aplicativos de console, bibliotecas de classes e projetos de ASP.NET. Além desses modelos internos, você pode criar seus próprios modelos e distribuí-los como pacotes NuGet.

Este artigo é uma referência para autores de modelo. Ele aborda como os modelos são estruturados, configurados e distribuídos. Para obter instruções passo a passo para criar e empacotar modelos, consulte a seção Conteúdo relacionado .

Tipos de modelo

O mecanismo de modelo .NET dá suporte a três tipos de modelos: modelos de item, modelos de projeto e modelos de solução.

  • Os modelos de item geram um ou mais arquivos, como um arquivo de código, um arquivo de configuração ou outro recurso, sem gerar um projeto inteiro ao seu redor. Por exemplo, um modelo de item pode produzir um arquivo de classe que adiciona um conjunto de métodos de extensão ou um arquivo de configuração JSON que segue um layout padrão que sua equipe usa. Para saber como criar um modelo de item, consulte Tutorial: Criar um modelo de item.

  • Project modelos geram uma estrutura de project completa. O modelo de projeto de console interno, por exemplo, produz um .csproj arquivo, um Program.cs arquivo e quaisquer outros arquivos que compõem o projeto. Crie um modelo de projeto quando quiser dar aos usuários um ponto de partida completo do projeto em vez de arquivos individuais. Para saber como criar um modelo de projeto, consulte 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 de API emparelhado com um projeto de teste em uma única etapa.

Ao criar seu próprio modelo, você declara seu tipo usando o tags.type campo no template.json arquivo de configuração. Os valores válidos são "project", "item"e "solution". Esses valores permitem que os usuários filtrem resultados quando pesquisam modelos com dotnet new search ou dotnet new list.

Dica

Project e modelos de solução aparecem na caixa de diálogo Visual Studio Criar um novo project, mas os modelos de item não aparecem na caixa de diálogo Adicionar>Novo Item. Os usuários podem acessar modelos de item da dotnet new CLI.

Estrutura do modelo

Um modelo é uma pasta no disco que contém duas coisas: os arquivos de origem do modelo e uma subpasta especial .template.config . Quando um usuário é executado dotnet new <shortName>, o mecanismo de modelo copia os arquivos de origem para o local de saída e aplica qualquer configuração definida para o modelo.

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

Os arquivos de origem podem ser qualquer tipo de arquivo. O mecanismo de modelo não exige que você insira tokens ou marcadores especiais no código-fonte. Ele usa os arquivos as-is, o que significa que você pode criar, executar e depurar o projeto de origem de um modelo exatamente como um projeto de .NET normal. Para transformar um projeto existente em um modelo, adicione um .template.config/template.json arquivo à raiz do projeto.

Opcionalmente, você pode injetar tokens de substituição vinculados a parâmetros de modelo (símbolos) diretamente em arquivos de origem de modelo e nomes de arquivo. Se os tokens não forem código-fonte válido, você não poderá compilar, executar ou depurar o projeto de origem antes de implantá-lo como um modelo. Os tokens não afetam projetos que os usuários criam com base no modelo implantado porque o mecanismo de modelo os substitui durante a criação do projeto.

O único arquivo necessário dentro .template.config é template.json. Esse arquivo informa ao mecanismo de modelo tudo o que ele precisa: o nome do modelo, o nome curto, o autor, as classificações e todos os parâmetros que os usuários podem passar quando criam a partir do modelo. Você também pode colocar um icon.png arquivo na .template.config pasta. O terminal não exibe ícones, mas Visual Studio mostra o ícone ao lado do modelo na caixa de diálogo Criar um novo projeto. Um PNG 128×128 funciona bem.

O arquivo template.json

O template.json arquivo é a única parte necessária de configuração em um modelo. Ele reside dentro da .template.config pasta e informa ao mecanismo de modelo como apresentar e processar seu modelo. A tabela a seguir 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 habilitar o IntelliSense em editores como Visual Studio Code.
author cadeia Não O autor do modelo.
classifications array(string) Não Marcas que os usuários podem usar para localizar o modelo com dotnet new search ou dotnet new list. Esses valores aparecem na coluna Marcas da lista de modelos .
description cadeia Não Uma descrição do que o modelo cria.
identity cadeia Sim Um identificador exclusivo para o modelo.
name cadeia Sim O nome de exibição do modelo mostrado aos usuários.
shortName cadeia Sim Os usuários de nome curto passam para dotnet new criar a partir do modelo, como console ou classlib.
sourceName cadeia Não Uma cadeia de caracteres em seus arquivos de origem e nomes de arquivo que o mecanismo de modelo substitui pelo nome que o usuário fornece por meio -n ou --name. Se o usuário não fornecer um nome, o mecanismo usará o nome do diretório atual.
preferNameDirectory booleano Não Quando true e o usuário fornece um nome, mas nenhum diretório de saída, o mecanismo de modelo cria um novo diretório com esse nome em vez de gravar arquivos no diretório atual. O padrão é false.
tags objeto Não Metadados que identificam propriedades como a linguagem e o tipo de modelo. Use tags.language para o idioma e tags.type para project, itemou solution.

Dois campos merecem atenção extra. O sourceName campo é como os modelos lidam com a nomenclatura: defina-a como uma cadeia de caracteres que aparece em seus nomes de arquivo e código-fonte (como MyTemplate), e o mecanismo de modelo substitui todas as ocorrências por qualquer nome que o usuário passe ao criar o modelo. O classifications campo controla a capacidade de descoberta; escolha marcas que descrevem com precisão a finalidade do modelo para que os usuários possam encontrá-lo ao pesquisar.

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

{
  "$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 no Repositório de Esquemas JSON. Para obter opções avançadas de configuração, como inclusão condicional de arquivo, ações pós-criação e modelos de vários projetos, consulte o wiki GitHub dotnet/templating.

Parâmetros de modelo (símbolos)

A symbols seção em define os parâmetros que os usuários podem passar ao criar com base em template.json seu modelo. Cada símbolo se torna uma opção da CLI, dotnet new <shortName>portanto, um símbolo nomeado ClassName se torna --ClassName (ou -C se você definir um nome curto).

Cada entrada de símbolo dá suporte às seguintes configurações comuns:

Setting Description
type Deve ser "parameter" para parâmetros voltados para o usuário.
description Mostrado na saída da ajuda do modelo quando os usuários são executados dotnet new <shortName> -?.
datatype O tipo de dados esperado, como "text", "bool"ou "choice".
replaces Uma cadeia de caracteres no conteúdo do arquivo de origem que o mecanismo de modelo substitui pelo valor do parâmetro.
fileRename Uma cadeia de caracteres em seus nomes de arquivo de origem que o mecanismo de modelo substitui pelo valor do parâmetro.
defaultValue O valor usado quando o usuário não fornece o parâmetro.

As replaces configurações e fileRename os símbolos são como a substituição da unidade de símbolos. Quando um usuário fornece um valor, o mecanismo de modelo substitui todas as ocorrências da cadeia de caracteres dentro do replaces conteúdo do arquivo e todas as ocorrências da cadeia de fileRename caracteres em nomes de arquivo. Se o usuário não fornecer um valor, ele defaultValue será usado.

Por exemplo, o símbolo a seguir permite que os usuários definam o nome da classe quando eles criam a partir do modelo. O arquivo é renomeado e a classe dentro dele é atualizada para corresponder:

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

Com esse símbolo definido, um usuário pode ser executado dotnet new <shortName> --ClassName MyHelpers para produzir um arquivo nomeado MyHelpers.cs contendo uma classe chamada MyHelpers. Sem o sinalizador, o arquivo e a classe mantêm o nome StringExtensionspadrão.

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

dotnet new <shortName> -?

Pacotes de modelo

Um pacote de modelo é um arquivo NuGet (.nupkg) que agrupa um ou mais modelos. Quando um usuário instala seu pacote de modelo, o mecanismo de modelo .NET registra todos os modelos dentro dele de uma só vez. Os pacotes são a maneira padrão de distribuir modelos. Publique um único pacote para NuGet.org ou um feed NuGet privado ou compartilhe um arquivo local .nupkg , e os usuários obtêm toda a coleção com um comando.

Para criar um pacote de modelo, use um arquivo de projeto C# (.csproj) configurado para atuar como um projeto de empacotamento em vez de um projeto de compilação. As principais configurações que fazem isso funcionar são:

Setting Valor Purpose
PackageType Template Marca o pacote como um pacote de modelo para que ele apareça nos dotnet new search resultados.
IncludeContentInPack true Inclui arquivos de conteúdo no pacote NuGet.
IncludeBuildOutput false Impede que binários compilados sejam adicionados ao pacote.
ContentTargetFolders content Coloca suas pastas de modelo dentro da content pasta do pacote NuGet, que é onde o mecanismo de modelo espera encontrá-las.

O templatepack modelo de projeto fornece a maneira mais fácil de criar um projeto de empacotamento:

  1. Instale o Microsoft. Pacote NuGet TemplateEngine.Authoring.Templates:

    dotnet new install Microsoft.TemplateEngine.Authoring.Templates

  2. Crie o projeto de empacotamento:

    dotnet new templatepack -n <PackageName>

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

Para obter um passo a passo completo sobre como criar, empacotar e publicar um pacote de modelo, consulte Tutorial: Criar um pacote de modelo.

Testar seu modelo localmente

Durante o desenvolvimento do modelo, instale seu modelo diretamente de sua pasta para testá-lo sem criar um pacote primeiro. Passe o caminho para o diretório que contém a .template.config pasta:

dotnet new install ./mytemplate/

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

dotnet new uninstall

Para desinstalar um modelo instalado de um diretório, passe o mesmo caminho de diretório usado para instalá-lo:

dotnet new uninstall ./mytemplate/

Depois de estar pronto para compartilhar seu modelo, empacote-o como um pacote NuGet (consulte pacotes de modelo) e distribua-o. Os usuários instalam seu modelo publicado e dotnet new install um dos seguintes argumentos de origem:

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

    dotnet new install AdatumCorporation.ConsoleTemplate.CSharp

  • Uma ID do pacote NuGet com uma URL de feed personalizada. A --nuget-source opção usa o feed especificado, além das fontes do NuGet configuradas, somente para essa instalação:

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

  • Um caminho para um arquivo local .nupkg :

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

Warning

Os modelos podem executar tarefas do MSBuild e código arbitrário durante a criação do projeto. Instale somente modelos de fontes em que você confia.

Para desinstalar um pacote instalado de uma origem do NuGet ou de um arquivo local .nupkg , use a ID do pacote NuGet:

dotnet new uninstall AdatumCorporation.ConsoleTemplate.CSharp

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

Localização de modelo

O mecanismo de modelo .NET dá suporte à localização opcional de metadados de modelo. Quando você fornece arquivos de localização, hosts como dotnet new e a caixa de diálogo Visual Studio Novo Project exibem o nome, a descrição e as informações de símbolo do modelo no idioma do usuário em vez do idioma original criado.

Os seguintes campos de modelo dão suporte à localização:

  • name
  • author
  • description
  • Símbolo description e displayName
  • Descrição e nome de exibição para cada opção em um parâmetro de escolha
  • Pós-ação description e manualInstructions

Para adicionar a localização, crie uma localize subpasta dentro .template.config e adicione um arquivo JSON por idioma. Nomeie cada arquivo templatestrings.<lang-code>.json, em que <lang-code> corresponde a um nome válido CultureInfo , como pt-BR, zh-Hansou de. Cada arquivo contém pares chave-valor em que a chave é um caminho para o elemento, template.jsonusando / 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 arquivo de localização português brasileiro nomeado templatestrings.pt-BR.json teria esta 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."
}

O mecanismo de modelo analisa esses arquivos quando carrega informações de modelo e retorna valores localizados automaticamente com base na cultura da interface do usuário atual. Nenhuma etapa extra é necessária do usuário.

A localização é opcional. Se você não incluir arquivos de localização, o modelo funcionará normalmente e sempre exibirá os valores de template.json. Para obter mais informações, consulte a página de localização wiki dotnet/modelagem.

Integração do Visual Studio

Visual Studio's Create a new project dialog uses the .NET template engine for .NET project templates. Modelos criados para dotnet new trabalhar em Visual Studio também, sem nenhuma configuração extra. Quando um usuário instala seu pacote de modelo com dotnet new install, Visual Studio detecta e exibe automaticamente esses modelos na caixa de diálogo.

Project e modelos de solução aparecem na caixa de diálogo Criar um novo project junto com os modelos internos do SDK. Os usuários podem encontrar modelos por nome, idioma ou marcas do classifications campo no arquivo do template.json modelo. Classificações precisas ajudam seu modelo a aparecer nas categorias de filtro corretas, portanto, escolha-as com cuidado. Para dar ao modelo uma aparência polida na caixa de diálogo, adicione uma icon.png à .template.config pasta Visual Studio a exibe ao lado do nome do modelo.

Atualmente, os modelos de item não aparecem na caixa de diálogo Adicionar>Novo Item . Os usuários ainda podem usar modelos de item com o dotnet new comando no terminal.

Para tornar seu modelo detectável para Visual Studio usuários que ainda não o instalaram, publique seu pacote de modelo para nuget.org. A caixa de diálogo Criar um novo projeto inclui uma opção Instalar mais modelos da opção de pesquisa online que pesquisa nuget.org pacotes de modelo. Quando um usuário instala seu pacote por meio dessa opção, Visual Studio usa o mesmo mecanismo de instalação que dotnet new install.

Para obter orientações mais profundas sobre Visual Studio integração específica, como controlar a ordem de classificação de modelo e configurar opções adicionais específicas do IDE, consulte o repositório de exemplo de modelo de Sayed Hashimi.

Conteúdo relacionado

  • Last updated on