Partilhar via

Tutorial: Criar um pacote de modelo

  • Artigo

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

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

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

Pré-requisitos

  • Conclua parte 1 e 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 working\content.

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

  • Instale o .NET 8 ou o .NET 9.

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

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

Criar um projeto de pacote 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 para um feed do NuGet. O comando suporta a instalação de pacotes de modelo a partir 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 código e produzir um binário. No entanto, o projeto também pode ser usado para gerar um pacote de modelo. 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 este projeto é criado, ele produz um pacote de modelo NuGet.

O pacote que vais gerar incluirá o item e os modelos de projeto criados anteriormente.

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

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

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

    O parâmetro -n define o nome do arquivo de projeto como AdatumCorporation.Utility.Templates.csproj. Você deve ver um resultado semelhante ao seguinte.

    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 projeto XML

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

O primeiro grupo trata das propriedades necessárias para um pacote NuGet. As quatro configurações <Package*> têm a ver com as propriedades do pacote NuGet para identificar seu pacote em um feed do NuGet. O valor <PackageId>, 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 do 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 template apareça em dotnet new search resultados, <PackageType> deve ser definido como Template.

No segundo grupo, a configuração <TargetFramework> garante que o MSBuild seja executado corretamente quando você executa o comando pack para compilar e empacotar o projeto. O grupo também inclui configurações que têm a ver com a configuração 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 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 item <Content> inclui tudo na pasta de modelos como conteúdo. Foi configurado também para excluir qualquer pasta bin ou pasta obj para impedir que qualquer código compilado (se tiveres testado e compilado os teus templates) seja incluído. Em segundo lugar, o item <Compile> exclui todos os arquivos de código da compilação, não importa onde eles estejam localizados. Esta configuração impede que o projeto usado para criar o pacote de modelos tente compilar o código na hierarquia de pastas dos 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 modelo de criação de tarefas 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

Na pasta de conteúdo há uma pasta SampleTemplate. Excluir esta 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 modelos recursos. A localização está desativada por padrão. Para habilitar a criação de arquivos de localização, defina LocalizeTemplates como true.

Embalar e instalar

Salve o arquivo de projeto. Antes de criar o pacote de modelos, verifique se a estrutura de pastas está correta. Qualquer modelo que se queira agrupar deve ser colocado na pasta de modelos , 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 contém duas pastas: extensões e consoleasync.

No seu terminal, a partir da pasta de trabalho, execute o comando . Este comando cria 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 comando dotnet new install. 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

Você deve ver 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 tiveste carregado o pacote NuGet para um feed do NuGet, podes usar o comando dotnet new install <PACKAGE_ID> onde <PACKAGE_ID> é o mesmo que a configuração <PackageId> do ficheiro .csproj de .

Desinstale o pacote de modelo

Não importa como instalaste o pacote de modelo, seja com o ficheiro .nupkg diretamente ou pelo feed do NuGet, remover um pacote de modelo é igual. Use a <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

Execute dotnet new uninstall AdatumCorporation.Utility.Templates para desinstalar o pacote de modelo. O comando produz informações sobre quais pacotes de modelo foram desinstalados.

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

Próximos passos

Para saber mais sobre modelos, a maioria dos quais você já aprendeu, consulte o artigo Custom templates for dotnet new.