Tutorial: criar um pacote de modelos

Artigo
10/13/2023

Com o .NET, você pode criar e implantar modelos que geram projetos, arquivos e, até mesmo, recursos. Este tutorial é a parte três de uma série que ensina como criar, instalar e desinstalar modelos para usar com o comando dotnet new.

Você pode exibir o modelo concluído no repositório GitHub de amostras do .NET.

Nesta parte da série, você aprenderá a:

Crie um pacote de modelos usando o pacote NuGet Microsoft.TemplateEngine.Authoring.Templates.
Instale um pacote de modelo a partir de um arquivo de pacote NuGet.
Desinstale um pacote de modelo por ID do pacote.

Crie um projeto *.csproj para compilar um pacote de modelo.
Configure o arquivo de projeto para empacotamento.
Instale um pacote de modelo a partir de um arquivo de pacote NuGet.
Desinstale um pacote de modelo por ID do pacote.

Pré-requisitos

Conclua a parte 1 e a parte 2 desta série de tutoriais.

Este tutorial usa os dois modelos criados nas duas primeiras partes desta série de tutoriais. Você pode usar um modelo diferente, contanto que você copie o modelo, como uma pasta, para a pasta working\content.
Abra um terminal e navegue até a pasta working.

Instale .NET 8 Preview.
Instale o modelo Microsoft.TemplateEngine.Authoring.Templates a partir de um feed de pacote NuGet.
- Execute o comando dotnet new install Microsoft.TemplateEngine.Authoring.Templates a partir de seu terminal.

Importante

Este artigo foi escrito para o .NET 7. No entanto, ele também se aplica ao .NET 6 e às versões anteriores, com uma diferença: a sintaxe dotnet new é diferente. Os subcomandos list, search, install e uninstall devem ser as opções --list, --search, --install e --uninstall, respectivamente.

Por exemplo, o comando dotnet new install no .NET 7 se torna dotnet new --install no .NET 6. Use o comando dotnet new --help para ver uma lista de todas as opções e subcomandos.

Criar um projeto de pacote de modelos

Um pacote de modelos é formado por um ou mais modelos empacotados em um arquivo NuGet. Quando você instala ou desinstala um pacote de modelos, todos os modelos contidos no pacote são adicionados ou removidos, respectivamente.

Os pacotes de modelos são representados por um arquivo de pacote NuGet (.nupkg) . Como qualquer pacote NuGet, você pode carregar o pacote de modelos em um feed do NuGet. O comando dotnet new install dá suporte à instalação de pacotes de modelos a partir de um feed de pacote NuGet, um arquivo .nupkg, ou um diretório com um modelo.

Normalmente você usa um arquivo de projeto C# para compilar o código e produzir um binário. No entanto, o projeto também pode ser usado para gerar um pacote de modelos. Com a alteração das configurações do .csproj, você pode evitar que ele compile códigos e, em vez disso, inclua todos os recursos dos modelos como recursos. Quando esse projeto é compilado, ele produz um pacote NuGet de pacote de modelos.

O pacote que você vai gerar incluirá os modelos [item] e (cli-templates-create-item-template.md) e project criados anteriormente.

O pacote Microsoft.TemplateEngine.Authoring.Templates contém modelos úteis para a criação de modelos. Para instalar esse pacote, nuget.org deve estar disponível como feed do NuGet no diretório de trabalho.

Na pasta working, execute o seguinte comando para criar o pacote de modelo:

dotnet new templatepack -n "AdatumCorporation.Utility.Templates"

O parâmetro -n define o nome do arquivo de projeto como AdatumCorporation.Utility.Templates.csproj. Você verá um resultado semelhante à seguinte saída.

The template "Template Package" was created successfully.

Processing post-creation actions...
Description: Manual actions required
Manual instructions: Open *.csproj in the editor and complete the package metadata configuration. Copy the templates to _content_ folder. Fill in README.md.

Em seguida, abra o arquivo AdatumCorporation.Utility.Templates.csproj em um editor de código e preencha-o de acordo com as dicas no modelo:

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

  <PropertyGroup>
    <!-- The package metadata. Fill in the properties marked as TODO below -->
    <!-- Follow the instructions on https://learn.microsoft.com/nuget/create-packages/package-authoring-best-practices -->
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <PackageVersion>1.0</PackageVersion>
    <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>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>net8.0</TargetFramework>
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
    ... cut for brevity ...

Na pasta working, execute o seguinte comando para criar o pacote de modelo:

dotnet new console -n AdatumCorporation.Utility.Templates

O parâmetro -n define o nome do arquivo de projeto como AdatumCorporation.Utility.Templates.csproj. Você verá um resultado semelhante à seguinte saída.

The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on .\AdatumCorporation.Utility.Templates.csproj...
  Restore completed in 52.38 ms for C:\code\working\AdatumCorporation.Utility.Templates.csproj.

Restore succeeded.

Exclua o arquivo Program.cs. O novo modelo de projeto gera esse arquivo, mas ele não é usado pelo mecanismo de modelos.

Em seguida, abra o arquivo AdatumCorporation.Utility.Template.csproj em seu editor favorito e substitua o conteúdo pelo seguinte XML:

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

  <PropertyGroup>    
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <PackageVersion>1.0</PackageVersion>
    <Title>AdatumCorporation Templates</Title>
    <Authors>Me</Authors>
    <Description>Templates to use when creating an application for Adatum Corporation.</Description>
    <PackageTags>dotnet-new;templates;adatum</PackageTags>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>netstandard2.0</TargetFramework>    
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
  </PropertyGroup>

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

</Project>

Descrição do projeto XML

As configurações em <PropertyGroup> no snippet de XML estão divididas em dois grupos.

O primeiro grupo lida com as propriedades necessárias para um pacote NuGet. As quatro configurações de <Package*> têm a ver com as propriedades do pacote NuGet para identificar seu pacote em um feed de NuGet. O valor <PackageId>, embora usado pelo NuGet, também é usado para desinstalar o pacote de modelo. As configurações restantes, tais como <Title> e <PackageTags>, têm a ver com os metadados exibidos no feed de NuGet e com o gerenciador de pacotes .NET. Para saber mais sobre as configurações do NuGet, confira Propriedades do NuGet e do MSBuild.

Observação

Para garantir que o pacote de modelo apareça nos resultados dotnet new search, <PackageType> deve ser definido como Template.

No segundo grupo, a configuração <TargetFramework> garante que o MSBuild seja executado corretamente quando você executar o comando pack para compilar e empacotar o projeto. O grupo inclui configurações que têm a ver com a configuração correta do projeto para incluir os modelos na pasta apropriada no pacote NuGet quando ele é criado:

A configuração <NoWarn> suprime uma mensagem de aviso que não se aplica a projetos de pacote de modelo.
A configuração <NoDefaultExcludes> garante que arquivos e pastas que começam com um . (como .gitignore) façam parte do modelo. O comportamento padrão dos pacotes NuGet é ignorar esses arquivos e pastas.

<ItemGroup> contém dois itens. Primeiro, o item <Content> inclui tudo que se encontra na pasta templates como conteúdo. Ele também é configurado para excluir a pasta bin ou obj para evitar que qualquer código compilado (se você testou e compilou seus modelos) seja incluído. Segundo, a configuração <Compile> exclui todos os arquivos de código da compilação, independentemente de onde eles estejam localizados. Essa configuração impede que o projeto usado para criar um pacote de modelos tente compilar o código na hierarquia de pastas templates.

Dica

Para obter mais informações sobre as configurações de metadados do NuGet, consulte Empacotar um modelo em um pacote do NuGet (arquivo nupkg).

O arquivo de projeto criado inclui tarefas de criação de modelos do MSBuild e configurações de localização.

  <PropertyGroup>
    <LocalizeTemplates>false</LocalizeTemplates>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.TemplateEngine.Tasks" Version="*" PrivateAssets="all" IsImplicitlyDefined="true"/>
  </ItemGroup>

Importante

A pasta de conteúdo content contém uma pasta SampleTemplate. Exclua essa pasta, pois ela foi adicionada ao modelo de criação para fins de demonstração.

Essas tarefas do MSBuild fornecem validação de modelo e funcionalidades de localização de modelos . A localização está desabilitada por padrão. Para habilitar a criação de arquivos de localização, defina LocalizeTemplates como true.

Empacotar e instalar

Salve o arquivo de projeto. Antes de compilar o pacote de modelo, verifique se a estrutura da pasta está correta. Qualquer modelo que você deseja empacotar deve ser colocado na pasta de modelos, em sua própria pasta. A estrutura de pastas deve ser semelhante à hierarquia a seguir:

working
│   AdatumCorporation.Utility.Templates.csproj
└───content
    ├───extensions
    │   └───.template.config
    │           template.json
    └───consoleasync
        └───.template.config
                template.json

A pasta conteúdo tem duas pastas: extensões e consoleasync.

No terminal, na pasta de trabalho, execute o comando dotnet pack. Esse comando compila o projeto e cria um pacote NuGet na pasta working\bin\Debug, conforme indicado pela seguinte saída:

MSBuild version 17.8.0-preview-23367-03+0ff2a83e9 for .NET
  Determining projects to restore...
  Restored C:\code\working\AdatumCorporation.Utility.Templates.csproj (in 1.16 sec).

  AdatumCorporation.Utility.Templates -> C:\code\working\bin\Release\net8.0\AdatumCorporation.Utility.Templates.dll
  Successfully created package 'C:\code\working\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg'.

Em seguida, instale o pacote de modelos com o comando dotnet new install. No Windows:

dotnet new install .\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

No Linux ou no macOS:

dotnet new install bin/Release/AdatumCorporation.Utility.Templates.1.0.0.nupkg

Será exibida uma saída semelhante à seguinte:

The following template packages will be installed:
   C:\code\working\AdatumCorporation.Utility.Templates\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

Success: AdatumCorporation.Utility.Templates::1.0.0 installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code
Example templates: async project                  consoleasync             [C#]              Common/Console/C#9

Se você baixou o pacote NuGet para um feed do NuGet, é possível usar o comando dotnet new install <PACKAGE_ID>, em que <PACKAGE_ID> é igual à configuração <PackageId> do arquivo .csproj.

Desinstalar o pacote de modelos

Não importa como você instalou o pacote de modelos, seja com o arquivo .nupkg diretamente ou com o feed do NuGet; a remoção do pacote de modelos é feita da mesma forma. Use o <PackageId> do modelo que você deseja desinstalar. Você pode obter uma lista de modelos instalados executando o comando dotnet new uninstall.

C:\working> dotnet new uninstall
Currently installed items:
... cut to save space ...

  AdatumCorporation.Utility.Templates
    Details:
      NuGetPackageId: AdatumCorporation.Utility.Templates
      Version: 1.0.0
      Author: Me
    Templates:
      Example templates: async project (consoleasync) C#
      Example templates: string extensions (stringext) C#
    Uninstall Command:
      dotnet new uninstall AdatumCorporation.Utility.Templates

Para desinstalar o pacote de modelo, execute dotnet new uninstall AdatumCorporation.Utility.Templates. O comando fornece informações sobre quais pacotes de modelo foram desinstalados.

Parabéns! Você instalou e desinstalou um pacote de modelos.

Próximas etapas

Para saber mais sobre modelos, a maioria dos quais você já aprendeu, confira o artigo Modelos personalizados para o dotnet new.