Delen via

Zelfstudie: Een sjabloonpakket maken

Met .NET kunt u sjablonen maken en implementeren waarmee projecten, bestanden en resources worden gegenereerd. Deze zelfstudie is deel drie van een reeks waarin u leert hoe u sjablonen maakt, installeert en verwijdert voor gebruik met de dotnet new opdracht.

U kunt de voltooide sjabloon bekijken in de GitHub-opslagplaats .NET Samples.

In dit deel van de serie leert u het volgende:

Vereiste voorwaarden

  • .NET 9 of een latere versie.

  • Voltooi deel 1 en deel 2 van deze reeks zelfstudies.

    In deze zelfstudie worden de twee sjablonen gebruikt die zijn gemaakt in de eerste twee onderdelen van deze reeks zelfstudies. U kunt een andere sjabloon gebruiken zolang u de sjabloon als map kopieert naar de map working\content .

  • Open een terminal en navigeer naar de werkmap .

  • Installeer de Microsoft.TemplateEngine.Authoring.Templates sjabloon vanuit de NuGet-pakketfeed.

    • Voer de opdracht uit vanuit de dotnet new install Microsoft.TemplateEngine.Authoring.Templates terminal.

Een sjabloonpakketproject maken

Een sjabloonpakket is een of meer sjablonen die zijn verpakt in een NuGet-pakket. Wanneer u een sjabloonpakket installeert of verwijdert, worden alle sjablonen in het pakket respectievelijk toegevoegd of verwijderd.

Sjabloonpakketten worden vertegenwoordigd door een NuGet-pakketbestand (.nupkg). En net als elk NuGet-pakket kunt u het sjabloonpakket uploaden naar een NuGet-feed. De dotnet new install opdracht ondersteunt het installeren van sjabloonpakketten vanuit een NuGet-pakketfeed, een .nupkg-bestand of een map met een sjabloon.

Normaal gesproken gebruikt u een C#-projectbestand om code te compileren en een binair bestand te produceren. Het project kan echter ook worden gebruikt om een sjabloonpakket te genereren. Door de instellingen van de .csproj te wijzigen, kunt u voorkomen dat er code wordt gemaakt en in plaats daarvan alle assets van uw sjablonen als resources worden opgenomen. Wanneer dit project is gebouwd, produceert het een NuGet-sjabloonpakket.

Het pakket dat u gaat genereren, bevat het item en de projectsjablonen die u eerder hebt gemaakt.

Het pakket Microsoft.TemplateEngine.Authoring.Templates bevat sjablonen die handig zijn voor het ontwerpen van sjablonen. Als u dit pakket wilt installeren, moet nuget.org beschikbaar zijn als NuGet-feed in de werkmap.

  1. Voer in de werkmap de volgende opdracht uit om het sjabloonpakket te maken:

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

    Met -n de parameter wordt de naam van het projectbestand ingesteld op AdatumCorporation.Utility.Templates.csproj. U zou een resultaat moeten zien dat vergelijkbaar is met de volgende uitvoer.

    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. Open vervolgens het bestand AdatumCorporation.Utility.Templates.csproj in een code-editor en vul het in volgens de hints in de sjabloon:

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

Beschrijving van de project-XML

De instellingen onder <PropertyGroup> in het XML-fragment worden onderverdeeld in twee groepen.

De eerste groep behandelt eigenschappen die vereist zijn voor een NuGet-pakket. De vier <Package*> instellingen hebben te maken met de NuGet-pakketeigenschappen om uw pakket op een NuGet-feed te identificeren. De <PackageId> waarde, terwijl deze wordt gebruikt door NuGet, wordt ook gebruikt om het sjabloonpakket te verwijderen. De overige instellingen, zoals <Title> en <PackageTags>, moeten te maken hebben met metagegevens die worden weergegeven in de NuGet-feed en .NET-pakketbeheer. Zie NuGet- en MSBuild-eigenschappen voor meer informatie over NuGet-instellingen.

Opmerking

Om ervoor te zorgen dat het sjabloonpakket in dotnet new search resultaten verschijnt, moet <PackageType> op Template worden ingesteld.

In de tweede groep zorgt de <TargetFramework> instelling ervoor dat MSBuild correct wordt uitgevoerd wanneer u de opdracht pack uitvoert om het project te compileren en in te pakken. De groep bevat ook instellingen die te maken hebben met het configureren van het project om de sjablonen op te nemen in de juiste map in het NuGet-pakket wanneer het wordt gemaakt:

  • De <NoWarn> instelling onderdrukt een waarschuwingsbericht dat niet van toepassing is op sjabloonpakketprojecten.

  • De <NoDefaultExcludes> instelling zorgt ervoor dat bestanden en mappen die beginnen met een . (zoals .gitignore) deel uitmaken van de sjabloon. Het standaardgedrag van NuGet-pakketten is het negeren van deze bestanden en mappen.

<ItemGroup> bevat twee items. Eerst bevat het <Content> item alles in de map sjablonen als inhoud. Het is ook ingesteld om een bin-map of obj-map uit te sluiten om te voorkomen dat gecompileerde code (als u uw sjablonen hebt getest en gecompileerd) wordt opgenomen. Ten tweede sluit het <Compile> item alle codebestanden uit van het compileren, ongeacht waar ze zich bevinden. Met deze instelling voorkomt u dat het project dat wordt gebruikt om het sjabloonpakket te maken, probeert de code te compileren in de sjablonen-maphiërarchie.

Aanbeveling

Zie Een sjabloon inpakken in een NuGet-pakket (nupkg-bestand) voor meer informatie over nuGet-metagegevensinstellingen.

Het gemaakte projectbestand bevat sjablooncreatie van MSBuild-taken en lokalisatie-instellingen.

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

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

Belangrijk

De inhoudsmap bevat een SampleTemplate-map . Verwijder deze map, omdat deze is toegevoegd aan de ontwerpsjabloon voor demonstratiedoeleinden.

Deze MSBuild-taken bieden sjabloonvalidatie en lokalisatie van de mogelijkheden van sjablonen . Lokalisatie is standaard uitgeschakeld. Als u het maken van lokalisatiebestanden wilt inschakelen, stelt u deze in op LocalizeTemplatestrue.

Inpakken en installeren

Sla het projectbestand op. Controleer voordat u het sjabloonpakket bouwt of de mapstructuur juist is. Elke sjabloon die u wilt inpakken, moet in de inhoudsmap worden geplaatst, in een eigen map. De mapstructuur moet er ongeveer uitzien zoals de volgende hiërarchie:

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

De inhoudsmap heeft twee mappen: extensies en consoleasync.

Voer in de terminal vanuit de werkmap de dotnet pack opdracht uit. Met deze opdracht wordt het project gebouwd en wordt een NuGet-pakket gemaakt in de map working\bin\Release , zoals aangegeven in de volgende uitvoer:

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

Installeer vervolgens het sjabloonpakket met de dotnet new install opdracht. In Windows:

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

In Linux of macOS:

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

U zou een uitvoer moeten zien die lijkt op het volgende:

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

Als u het NuGet-pakket hebt geüpload naar een NuGet-feed, kunt u de dotnet new install <PACKAGE_ID> opdracht gebruiken waar <PACKAGE_ID> dezelfde is als de <PackageId> instelling uit het .csproj-bestand .

Het sjabloonpakket verwijderen

Ongeacht hoe u het sjabloonpakket hebt geïnstalleerd, met het .nupkg-bestand rechtstreeks of door NuGet-feed, is het verwijderen van een sjabloonpakket hetzelfde. Gebruik de <PackageId> sjabloon die u wilt verwijderen. U kunt een lijst met sjablonen ophalen die zijn geïnstalleerd door de opdracht uit te dotnet new uninstall voeren.

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

Voer dotnet new uninstall AdatumCorporation.Utility.Templates uit om het sjabloonpakket te verwijderen. De opdracht voert informatie uit over welke sjabloonpakketten zijn verwijderd.

Gefeliciteerd! U hebt een sjabloonpakket geïnstalleerd en verwijderd.

Volgende stappen

Zie het nieuwe artikel Aangepaste sjablonen voor dotnet voor meer informatie over sjablonen, waarvan u de meeste al hebt geleerd.

  • Last updated on