Anpassade mallar för dotnet new

Artikel
08/15/2023

.NET SDK levereras med många mallar som redan är installerade och redo att användas. Kommandot dotnet new är inte bara ett sätt att använda en mall, utan även hur du installerar och avinstallerar mallar. Du kan skapa egna anpassade mallar för alla typer av projekt, till exempel en app, tjänst, ett verktyg eller ett klassbibliotek. Du kan till och med skapa en mall som matar ut en eller flera oberoende filer, till exempel en konfigurationsfil.

Du kan installera anpassade mallar från ett NuGet-paket i valfri NuGet-feed, genom att referera till en NuGet .nupkg-fil direkt eller genom att ange en filsystemkatalog som innehåller mallen. Mallmotorn erbjuder funktioner som gör att du kan ersätta värden, inkludera och exkludera filer och köra anpassade bearbetningsåtgärder när mallen används.

Mallmotorn är öppen källkod och onlinekodlagringsplatsen finns på dotnet/templating på GitHub. Fler mallar, inklusive mallar från tredje part, finns med hjälp av dotnet new search. Mer information om hur du skapar och använder anpassade mallar finns i Skapa egna mallar för dotnet new och dotnet/templating GitHub-lagringsplatsen Wiki.

Kommentar

Mallexempel är tillgängliga på GitHub-lagringsplatsen dotnet/templating .

Om du vill följa en genomgång och skapa en mall kan du läsa självstudien Skapa en anpassad mall för dotnet new .

.NET-standardmallar

När du installerar .NET SDK får du över ett dussin inbyggda mallar för att skapa projekt och filer, inklusive konsolappar, klassbibliotek, enhetstestprojekt, ASP.NET Core-appar (inklusive Angular - och React-projekt ) och konfigurationsfiler. Kör kommandot för dotnet new list att lista de inbyggda mallarna:

dotnet new list

Konfiguration

En mall består av följande delar:

Källfiler och mappar.
En konfigurationsfil (template.json).

Källfiler och mappar

Källfilerna och mapparna innehåller de filer och mappar som du vill att mallmotorn ska använda när dotnet new <TEMPLATE> kommandot körs. Mallmotorn är utformad för att använda körbara projekt som källkod för att skapa projekt. Detta har flera fördelar:

Mallmotorn kräver inte att du matar in särskilda token i projektets källkod.
Kodfilerna är inte särskilda filer eller ändras på något sätt för att fungera med mallmotorn. Därför fungerar de verktyg som du normalt använder när du arbetar med projekt också med mallinnehåll.
Du skapar, kör och felsöker dina mallprojekt precis som du gör för något av dina andra projekt.
Du kan snabbt skapa en mall från ett befintligt projekt genom att lägga till en ./.template.config/template.json konfigurationsfil i projektet.

Filer och mappar som lagras i mallen är inte begränsade till formella .NET-projekttyper. Källfiler och mappar kan bestå av allt innehåll som du vill skapa när mallen används, även om mallmotorn bara skapar en fil som utdata.

Filer som genereras av mallen kan ändras baserat på logik och inställningar som du har angett i template.json konfigurationsfilen. Användaren kan åsidosätta de här inställningarna genom att skicka alternativ till dotnet new <TEMPLATE> kommandot. Ett vanligt exempel på anpassad logik är att ange ett namn för en klass eller variabel i kodfilen som distribueras av en mall.

template.json

Filen template.json placeras i mappen .template.config i mallens rotkatalog. Filen innehåller konfigurationsinformation till mallmotorn. Den minsta konfigurationen kräver de medlemmar som visas i följande tabell, vilket är tillräckligt för att skapa en funktionell mall.

Medlem	Typ	Beskrivning
`$schema`	URI	JSON-schemat för template.json-filen. Redigerare som stöder JSON-scheman aktiverar JSON-redigeringsfunktioner när schemat anges. Visual Studio Code kräver till exempel att den här medlemmen aktiverar IntelliSense. Använd värdet `http://json.schemastore.org/template`.
`author`	sträng	Mallens författare.
`classifications`	array(string)	Noll eller fler egenskaper för mallen som en användare kan använda för att hitta mallen när de söker efter den. Klassificeringarna visas också i kolumnen Taggar när den visas i en lista över mallar som skapas med hjälp `dotnet new list` av kommandot .
`identity`	sträng	Ett unikt namn för den här mallen.
`name`	sträng	Namnet på mallen som användarna bör se.
`shortName`	sträng	Ett standardnamn för shorthand för att välja den mall som gäller för miljöer där mallnamnet anges av användaren, inte valt via ett GUI. Det korta namnet är till exempel användbart när du använder mallar från en kommandotolk med CLI-kommandon.
`sourceName`	sträng	Namnet i källträdet som ska ersättas med det namn som användaren anger. Mallmotorn söker efter alla förekomster av den `sourceName` som nämns i konfigurationsfilen och ersätter den i filnamn och filinnehåll. Värdet som ska ersättas med kan anges med hjälp av `-n` alternativen eller `--name` när du kör en mall. Om inget namn anges används den aktuella katalogen.
`preferNameDirectory`	Booleskt	Anger om du vill skapa en katalog för mallen om namnet anges men en utdatakatalog inte har angetts (i stället för att skapa innehållet direkt i den aktuella katalogen). Standardvärdet är "false".

Det fullständiga schemat för template.json-filen finns i JSON-schemaarkivet. Mer information om template.json-filen finns i wikin för dotnet-mallning. Mer information om hur du gör mallarna synliga i Visual Studio finns i de resurser som Sayed Hashimi har skapat.

Exempel

Här är till exempel en mallmapp som innehåller två innehållsfiler: console.cs och readme.txt. Det finns också den nödvändiga mappen med namnet .template.config som innehåller filen template.json .

└───mytemplate
    │   console.cs
    │   readme.txt
    │
    └───.template.config
            template.json

Filen template.json ser ut så här:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Travis Chau",
  "classifications": [ "Common", "Console" ],
  "identity": "AdatumCorporation.ConsoleTemplate.CSharp",
  "name": "Adatum Corporation Console Application",
  "shortName": "adatumconsole"
}

Mappen mytemplate är ett installationsbart mallpaket. När paketet har installerats shortName kan det användas med dotnet new kommandot . Skulle till exempel dotnet new adatumconsole mata ut console.cs filerna och readme.txt till den aktuella mappen.

Lokalisering av mallar

.NET-mallarna kan lokaliseras. Om en mall är lokaliserad för det språk som matchar det aktuella språket visas dess element på samma språk som CLI. Lokalisering är valfritt när du skapar nya mallar.

De lokala elementen i en mall är:

Name
Författare
beskrivning
Symboler
- beskrivning
- Visningsnamn
- Beskrivningar och visningsnamn för alternativ för alternativparametrar
Publicera åtgärder
- beskrivning
- Manuella instruktioner

Lokaliseringsfiler har ett JSON-format och bara en fil per kultur bör finnas. Namngivningskonventionen är: templatestrings.<lang code>.json, där lang code motsvarar något av CultureInfo-alternativen . Alla lokaliseringsfiler ska finnas i .template-config\localize mappen.

JSON för lokalisering består av nyckelvärdepar:

Nyckeln är referensen till ett element i template.json som ska lokaliseras. Om elementet är underordnat använder du den fullständiga sökvägen med en / avgränsare.
Värdet är lokaliseringssträngen för elementet som anges av nyckeln.

Mer information om hur du lokaliserar mallar finns på wikins lokaliseringssida för dotnet-mallar.

Exempel

Här är till exempel template.json fil med några lokala fält:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Microsoft",
  "classifications": "Config",
  "name": "EditorConfig file",
  "description": "Creates an .editorconfig file for configuring code style preferences.",
  "symbols": {
    "Empty": {
      "type": "parameter",
      "datatype": "bool",
      "defaultValue": "false",
      "displayName": "Empty",
      "description": "Creates empty .editorconfig instead of the defaults for .NET."
    }
  }
}

Och vissa fält ska lokaliseras till brasilianska portugisiska. Filnamnet kommer att matcha templatestrings.pt-BR.json kulturen och det skulle se ut så här:

{
  "author": "Microsoft",
  "name": "Arquivo EditorConfig",
  "description": "Cria um arquivo .editorconfig para configurar as preferências de estilo de código.",
  "symbols/Empty/displayName": "Vazio",
  "symbols/Empty/description": "Cria .editorconfig vazio em vez dos padrões para .NET."
}

Packa en mall i ett NuGet-paket (nupkg-fil)

En anpassad mall är fullspäckad med dotnet pack-kommandot och en .csproj-fil . Du kan också använda NuGet med nuget pack-kommandot tillsammans med en .nuspec-fil . NuGet kräver dock .NET Framework i Windows och Mono på Linux och macOS.

.csproj-filen skiljer sig något från en traditionell csproj-fil för kodprojektet. Notera följande inställningar:

Inställningen <PackageType> läggs till och anges till Template.
Inställningen <PackageVersion> läggs till och anges till ett giltigt NuGet-versionsnummer.
Inställningen <PackageId> läggs till och anges till en unik identifierare. Den här identifieraren används för att avinstallera mallpaketet och används av NuGet-feeds för att registrera ditt mallpaket.
Allmänna metadatainställningar ska anges: <Title>, <Authors>, <Description>och <PackageTags>.
Inställningen <TargetFramework> måste anges, även om binärfilen som skapas av mallprocessen inte används. I exemplet nedan är det inställt på netstandard2.0.

Ett mallpaket i form av ett .nupkg NuGet-paket kräver att alla mallar lagras i innehållsmappen i paketet. Det finns några fler inställningar att lägga till i en .csproj-fil för att säkerställa att den genererade .nupkg kan installeras som ett mallpaket:

Inställningen <IncludeContentInPack> är inställd på att true inkludera alla filer som projektet anger som innehåll i NuGet-paketet.
Inställningen <IncludeBuildOutput> är inställd på att false undanta alla binärfiler som genereras av kompilatorn från NuGet-paketet.
Inställningen <ContentTargetFolders> är inställd på content. Detta säkerställer att filerna som anges som innehåll lagras i innehållsmappeni NuGet-paketet. Den här mappen i NuGet-paketet parsas av dotnet-mallsystemet.

Ett enkelt sätt att undanta alla kodfiler från att kompileras av mallprojektet är att använda <Compile Remove="**\*" /> objektet i projektfilen i ett <ItemGroup> element.

Ett enkelt sätt att strukturera mallpaketet är att placera alla mallar i enskilda mappar och sedan varje mallmapp i en mallmapp som finns i samma katalog som . csproj-filen . På så sätt kan du använda ett enda projektobjekt för att inkludera alla filer och mappar i mallarna som innehåll. Skapa ett <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> objekt i ett <ItemGroup> element.

Här är ett exempel på en .csproj-fil som följer alla dessa riktlinjer. Den packar den underordnade mappen mallar till innehållspaketmappen och undantar alla kodfiler från att kompileras.

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

  <PropertyGroup>
    <PackageType>Template</PackageType>
    <PackageVersion>1.0</PackageVersion>
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <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>
    <TargetFramework>netstandard2.0</TargetFramework>

    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
  </PropertyGroup>

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

</Project>

I följande exempel visas fil- och mappstrukturen för att använda en .csproj för att skapa ett mallpaket. Mappen MyDotnetTemplates.csproj och mallar finns båda i roten för en katalog med namnet project_folder. Mappen templates innehåller två mallar, mytemplate1 och mytemplate2. Varje mall har innehållsfiler och en .template.config-mapp med en template.json konfigurationsfil.

project_folder
│   MyDotnetTemplates.csproj
│
└───templates
    ├───mytemplate1
    │   │   console.cs
    │   │   readme.txt
    │   │
    │   └───.template.config
    │           template.json
    │
    └───mytemplate2
        │   otherfile.cs
        │
        └───.template.config
                template.json

Kommentar

För att säkerställa att mallpaketet visas som dotnet new search resultat anger du NuGet-pakettypen till Template.

Installera ett mallpaket

Använd det nya installationskommandot dotnet för att installera ett mallpaket.

Så här installerar du ett mallpaket från ett NuGet-paket som lagras på nuget.org

Använd NuGet-paketidentifieraren för att installera ett mallpaket.

dotnet new install <NUGET_PACKAGE_ID>

Så här installerar du ett mallpaket från en anpassad NuGet-källa

Ange en anpassad NuGet-källa (till exempel https://api.my-custom-nuget.com/v3/index.json).

dotnet new --install <NUGET_PACKAGE_ID> --nuget-source <SOURCE>

Så här installerar du ett mallpaket från en lokal nupkg-fil

Ange sökvägen till en .nupkg NuGet-paketfil.

dotnet new install <PATH_TO_NUPKG_FILE>

Så här installerar du ett mallpaket från en filsystemkatalog

Mallar kan installeras från en mallmapp, till exempel mappen mytemplate1 från föregående exempel. Ange mappsökvägen för mappen .template.config . Sökvägen till mallkatalogen behöver inte vara absolut.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Hämta en lista över installerade mallpaket

Avinstallationskommandot, utan några andra parametrar, visar en lista över alla installerade mallpaket och inkluderade mallar.

dotnet new uninstall

Kommandot returnerar något som liknar följande utdata:

Currently installed items:
   Microsoft.Azure.WebJobs.ProjectTemplates
      Version: 4.0.1942
      Details:
         Author: Microsoft
         NuGetSource: https://api.nuget.org/v3/index.json
      Templates:
         Azure Functions (func) C#
         Azure Functions (func) F#
      Uninstall Command:
         dotnet new uninstall Microsoft.Azure.WebJobs.ProjectTemplates
...

Den första nivån av objekt efter Currently installed items: är de identifierare som används för att avinstallera ett mallpaket. Och i föregående exempel Microsoft.Azure.WebJobs.ProjectTemplates visas. Om mallpaketet installerades med hjälp av en filsystemsökväg är den här identifieraren mappsökvägen till mappen .template.config . Endast de mallpaket som installeras via dotnet new install visas i listan. De mallpaket som är inbyggda i .NET SDK visas inte.

Avinstallera ett mallpaket

Använd det nya avinstallationskommandot dotnet för att avinstallera ett mallpaket.

Om paketet har installerats av antingen en NuGet-feed eller av en .nupkg-fil direkt anger du identifieraren.

dotnet new uninstall <NUGET_PACKAGE_ID>

Om paketet installerades genom att ange en sökväg till mappen .template.config använder du den sökvägen för att avinstallera paketet. Du kan se den absoluta sökvägen för mallpaketet i utdata som tillhandahålls av dotnet new uninstall kommandot. Mer information finns i avsnittet Hämta en lista över installerade mallar .

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Skapa ett projekt med en anpassad mall

När en mall har installerats använder du mallen genom att köra kommandot på samma dotnet new <TEMPLATE> sätt som med andra förinstallerade mallar. Du kan också ange alternativ för dotnet new kommandot, inklusive mallspecifika alternativ som du har konfigurerat i mallinställningarna. Ange mallens korta namn direkt till kommandot:

dotnet new <TEMPLATE>

Anpassade mallar för dotnet new

.NET-standardmallar

Konfiguration

Källfiler och mappar

template.json

Exempel

Lokalisering av mallar

Exempel

Packa en mall i ett NuGet-paket (nupkg-fil)

Installera ett mallpaket

Så här installerar du ett mallpaket från ett NuGet-paket som lagras på nuget.org

Så här installerar du ett mallpaket från en anpassad NuGet-källa

Så här installerar du ett mallpaket från en lokal nupkg-fil

Så här installerar du ett mallpaket från en filsystemkatalog

Hämta en lista över installerade mallpaket

Avinstallera ett mallpaket

Skapa ett projekt med en anpassad mall

Se även

Feedback

Ytterligare resurser