Självstudie: Skapa ett mallpaket

Artikel
10/07/2023

Med .NET kan du skapa och distribuera mallar som genererar projekt, filer och till och med resurser. Den här självstudien är del tre i en serie som lär dig hur du skapar, installerar och avinstallerar mallar för användning med dotnet new kommandot .

Du kan visa den färdiga mallen på GitHub-lagringsplatsen för .NET-exempel.

I den här delen av serien får du lära dig att:

Skapa ett mallpaket med hjälp av NuGet-paketet Microsoft.TemplateEngine.Authoring.Templates .
Installera ett mallpaket från en NuGet-paketfil.
Avinstallera ett mallpaket efter paket-ID.

Skapa ett *.csproj-projekt för att skapa ett mallpaket.
Konfigurera projektfilen för packning.
Installera ett mallpaket från en NuGet-paketfil.
Avinstallera ett mallpaket efter paket-ID.

Förutsättningar

Slutför del 1 och del 2 i den här självstudieserien.

I den här självstudien används de två mallar som skapades i de två första delarna av den här självstudieserien. Du kan använda en annan mall så länge du kopierar mallen, som en mapp, till mappen working\content .
Öppna en terminal och gå till arbetsmappen.

Installera .NET 8.
Installera mallen Microsoft.TemplateEngine.Authoring.Templates från NuGet-paketflödet.
- dotnet new install Microsoft.TemplateEngine.Authoring.Templates Kör kommandot från terminalen.

Viktigt!

Den här artikeln är skriven för .NET 7. Det gäller dock även för .NET 6 och tidigare versioner, med en skillnad: Syntaxen dotnet new är annorlunda. Underkommandona list, search, installoch uninstall bör vara --list, --search, --installoch --uninstall respektive alternativ.

Kommandot i .NET 7 blir dotnet new --install till exempel dotnet new install i .NET 6. dotnet new --help Använd kommandot för att se en lista över alla alternativ och underkommandon.

Skapa ett mallpaketprojekt

Ett mallpaket är en eller flera mallar som är packade i ett NuGet-paket. När du installerar eller avinstallerar ett mallpaket läggs alla mallar som ingår i paketet till eller tas bort.

Mallpaket representeras av en NuGet-paketfil (.nupkg). Precis som alla NuGet-paket kan du ladda upp mallpaketet till en NuGet-feed. Kommandot dotnet new install stöder installation av mallpaket från en NuGet-paketfeed, en .nupkg-fil eller en katalog med en mall.

Normalt använder du en C#-projektfil för att kompilera kod och skapa en binär fil. Projektet kan dock också användas för att generera ett mallpaket. Genom att ändra inställningarna för .csproj kan du förhindra att den kompilerar någon kod och i stället inkludera alla tillgångar i dina mallar som resurser. När det här projektet skapas skapar det ett nuget-mallpaket.

Paketet som du ska generera innehåller de [objekt] och (cli-templates-create-item-template.md) och projektmallar som du skapade tidigare.

Paketet Microsoft.TemplateEngine.Authoring.Templates innehåller mallar som är användbara för mallredigering. Om du vill installera det här paketet bör nuget.org vara tillgängligt som NuGet-feed i arbetskatalogen.

I arbetsmappen kör du följande kommando för att skapa mallpaketet:

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

Parametern -n anger projektfilens namn till AdatumCorporation.Utility.Templates.csproj. Du bör se ett resultat som liknar följande utdata.

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.

Öppna sedan filen AdatumCorporation.Utility.Templates.csproj i en kodredigerare och fyll i den enligt tipsen i mallen:

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

I arbetsmappen kör du följande kommando för att skapa mallpaketet:

dotnet new console -n AdatumCorporation.Utility.Templates

Parametern -n anger projektfilens namn till AdatumCorporation.Utility.Templates.csproj. Du bör se ett resultat som liknar följande utdata.

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.

Ta bort filen Program.cs. Den nya projektmallen genererar den här filen, men den används inte av mallmotorn.

Öppna sedan filen AdatumCorporation.Utility.Templates.csproj i din favoritredigerare och ersätt innehållet med följande 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>

Beskrivning av projektets XML

Inställningarna under <PropertyGroup> i XML-kodfragmentet är uppdelade i två grupper.

Den första gruppen behandlar egenskaper som krävs för ett NuGet-paket. De fyra <Package*> inställningarna har att göra med NuGet-paketegenskaperna för att identifiera ditt paket i en NuGet-feed. Värdet <PackageId> , som används av NuGet, används också för att avinstallera mallpaketet. De återstående inställningarna, till exempel och <PackageTags>, har att göra med metadata som <Title> visas i NuGet-feeden och .NET-pakethanteraren. Mer information om NuGet-inställningar finns i NuGet- och MSBuild-egenskaper.

Kommentar

För att säkerställa att mallpaketet visas i dotnet new search resultat<PackageType> måste vara inställt på Template.

I den andra gruppen <TargetFramework> ser inställningen till att MSBuild körs korrekt när du kör packkommandot för att kompilera och packa projektet. Gruppen innehåller också inställningar som har att göra med att konfigurera projektet för att inkludera mallarna i lämplig mapp i NuGet-paketet när det skapas:

Inställningen <NoWarn> utelämnar ett varningsmeddelande som inte gäller för mallpaketprojekt.
Inställningen <NoDefaultExcludes> ser till att filer och mappar som börjar med en . (som .gitignore) är en del av mallen. Standardbeteendet för NuGet-paket är att ignorera dessa filer och mappar.

<ItemGroup> innehåller två objekt. <Content> Först innehåller objektet allt i mallmappen som innehåll. Den är också inställd på att undanta alla lagerplatsmappar eller obj-mappar för att förhindra att kompilerad kod (om du har testat och kompilerat dina mallar) inkluderas. <Compile> För det andra utesluter objektet alla kodfiler från kompilering oavsett var de finns. Den här inställningen förhindrar att det projekt som används för att skapa mallpaketet försöker kompilera koden i mapphierarkin för mallar .

Dricks

Mer information om NuGet-metadatainställningar finns i Packa en mall i ett NuGet-paket (nupkg-fil).

Den skapade projektfilen innehåller mallredigering av MSBuild-uppgifter och lokaliseringsinställningar.

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

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

Viktigt!

Innehållsinnehållsmappen innehåller en SampleTemplate-mapp. Ta bort den här mappen eftersom den lades till i redigeringsmallen i demonstrationssyfte.

Dessa MSBuild-uppgifter tillhandahåller mallverifiering och lokalisering av mallfunktionerna . Lokalisering är inaktiverat som standard. Om du vill aktivera skapande av lokaliseringsfiler anger du LocalizeTemplates till true.

Packa och installera

Spara projektfilen. Kontrollera att mappstrukturen är korrekt innan du skapar mallpaketet. Alla mallar som du vill packa ska placeras i mallmappen i en egen mapp. Mappstrukturen bör se ut ungefär så här:

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

Innehållsmappen har två mappar: tillägg och consoleasync.

Kör kommandot från arbetsmappen i terminalendotnet pack. Det här kommandot skapar projektet och skapar ett NuGet-paket i mappen working\bin\Debug , enligt följande utdata:

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

Installera sedan mallpaketet med dotnet new install kommandot . I Windows:

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

I Linux eller macOS:

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

Du bör se utdata som liknar följande:

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

Om du laddade upp NuGet-paketet till en NuGet-feed kan du använda dotnet new install <PACKAGE_ID> kommandot där <PACKAGE_ID> är samma som <PackageId> inställningen från .csproj-filen .

Avinstallera mallpaketet

Oavsett hur du har installerat mallpaketet, antingen med .nupkg-filen direkt eller via NuGet-feed, är det samma sak att ta bort ett mallpaket. Använd mallen <PackageId> som du vill avinstallera. Du kan hämta en lista över mallar som installeras genom att köra dotnet new uninstall kommandot .

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

Kör dotnet new uninstall AdatumCorporation.Utility.Templates för att avinstallera mallpaketet. Kommandot matar ut information om vilka mallpaket som har avinstallerats.

Gratulerar! Du har installerat och avinstallerat ett mallpaket.

Nästa steg

Mer information om mallar, varav de flesta redan har lärt dig, finns i artikeln Anpassade mallar för dotnet new .

Dela via