Compartilhar via

Tutorial: Criar um pacote de modelos

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

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

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

Pré-requisitos

  • .NET 9 ou uma versão posterior.

  • 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, desde que copie o modelo, como uma pasta, para a pasta de trabalho\conteúdo .

  • Abra um terminal e navegue até a pasta de trabalho .

  • Instale o Microsoft.TemplateEngine.Authoring.Templates modelo do feed de pacotes NuGet.

    • Execute o dotnet new install Microsoft.TemplateEngine.Authoring.Templates comando do seu terminal.

Criar um projeto de pacote de modelo

Um pacote de modelo é um ou mais modelos empacotados em um pacote 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 modelo são representados por um arquivo de pacote NuGet (.nupkg). E, como qualquer pacote NuGet, você pode carregar o pacote de modelo em um feed NuGet. O dotnet new install comando dá suporte à instalação de pacotes de modelo de um feed de pacotes 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. Ao alterar as configurações do .csproj, você pode impedir que ele compile qualquer código e, em vez disso, incluir todos os ativos de seus modelos como recursos. Quando esse projeto é criado, ele produz um pacote NuGet de pacote de modelos.

O pacote que você vai gerar inclui os modelos de item e de projeto 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 NuGet no diretório de trabalho.

  1. Na pasta de trabalho , execute o seguinte comando para criar o pacote de modelos:

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

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

    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.

  2. 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 ...

Descrição do XML do projeto

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

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

Observação

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

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

  • A <NoWarn> configuração suprime uma mensagem de aviso que não se aplica a projetos de pacote de modelos.

  • A <NoDefaultExcludes> configuração garante que os 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 <Content> item inclui tudo na pasta de modelos como conteúdo. Ele também está configurado para excluir qualquer pasta bin ou pasta obj para evitar que qualquer código compilado (se você testou e compilou seus modelos) seja incluído. Em segundo lugar, o <Compile> item exclui todos os arquivos de código da compilação, independentemente de onde estejam localizados. Essa configuração impede que o projeto usado para criar o pacote de modelos tente compilar o código na hierarquia de pastas de modelos .

Dica

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

O arquivo de projeto criado inclui tarefas de criação de modelo 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 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 localização dos recursos de modelos . A localização está desabilitada por padrão. Para habilitar a criação de arquivos de localização, defina LocalizeTemplates como true.

Embale e instale

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

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

A pasta de conteúdo tem duas pastas: extensions e consoleasync.

No terminal, na pasta de trabalho , execute o dotnet pack comando. Esse comando compila o projeto e cria um pacote NuGet na pasta working\bin\Release , 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 modelo com o dotnet new install comando. No Windows:

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

No Linux ou 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ê carregou o pacote NuGet em um feed NuGet, poderá usar o dotnet new install <PACKAGE_ID> comando where <PACKAGE_ID> is same to <PackageId> the setting from the .csproj file.

Desinstalar o pacote de modelos

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

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

Execute dotnet new uninstall AdatumCorporation.Utility.Templates para desinstalar o pacote de modelos. O comando gera 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, consulte o artigo Modelos personalizados para dotnet new .

  • Last updated on