Självstudie: Skapa en objektmall

  • Artikel

Med .NET kan du skapa och distribuera mallar som genererar projekt, filer och resurser. Den här självstudien är en del av 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.

Dricks

Objektmallar visas inte i dialogrutan Lägg till>nytt objekt i Visual Studio.

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

  • Skapa en klass för en objektmall.
  • Skapa mallkonfigurationsmappen och -filen.
  • Installera en mall från en filsökväg.
  • Testa en objektmall.
  • Avinstallera en objektmall.

Förutsättningar

  • .NET SDK 7.0.100 eller en senare version.

    Referensartikeln beskriver grunderna om mallar och hur de sammanställs. En del av denna information upprepas här.

  • Öppna en terminal och navigera till en mapp där du ska lagra och testa mallarna.

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 de mappar som krävs

Den här serien använder en "arbetsmapp" där mallkällan finns och en "testmapp" som används för att testa dina mallar. Arbetsmappen och testmappen ska finnas under samma överordnade mapp.

Först skapar du den överordnade mappen, namnet spelar ingen roll. Skapa sedan två undermappar med namnet working and test. I arbetsmappen skapar du en undermapp med namnet innehåll.

Mappstrukturen bör se ut så här.

parent_folder
├───test
└───working
    └───content

Skapa en objektmall

En objektmall är en specifik typ av mall som innehåller en eller flera filer. Dessa typer av mallar är användbara när du redan har ett projekt och vill generera en annan fil, till exempel en konfigurationsfil eller kodfil. I det här exemplet skapar du en klass som lägger till en tilläggsmetod till strängtypen.

I terminalen går du till mappen working\content och skapar en ny undermapp med namnet extensions.

working
└───content
    └───extensions

Gå till mappen extensions och skapa en ny fil med namnet StringExtensions.cs. Öppna filen i en textredigerare. Den här klassen tillhandahåller en tilläggsmetod med namnet Reverse som vänder innehållet i en sträng. Klistra in följande kod och spara filen:

namespace System;

public static class StringExtensions
{
    public static string Reverse(this string value)
    {
        char[] tempArray = value.ToCharArray();
        Array.Reverse(tempArray);
        return new string(tempArray);
    }
}

Nu när innehållet i mallen är klart är nästa steg att skapa mallkonfigurationen.

Skapa mallkonfigurationen

I den här delen av självstudien finns mallmappen på working\content\extensions.

Mallar identifieras av .NET eftersom de har en särskild mapp och konfigurationsfil som finns i roten i mallmappen.

Skapa först en ny undermapp med namnet .template.config och ange den. Skapa sedan en ny fil med namnet template.json. Mappstrukturen bör se ut så här:

working
└───content
    └───extensions
        └───.template.config
                template.json

Öppna template.json med din favorittextredigerare och klistra in följande JSON-kod och spara den.

{
    "$schema": "http://json.schemastore.org/template",
    "author": "Me",
    "classifications": [ "Common", "Code" ],
    "identity": "ExampleTemplate.StringExtensions",
    "name": "Example templates: string extensions",
    "shortName": "stringext",
    "tags": {
      "language": "C#",
      "type": "item"
    },
    "symbols": {
      "ClassName":{
        "type": "parameter",
        "description": "The name of the code file and class.",
        "datatype": "text",
        "replaces": "StringExtensions",
        "fileRename": "StringExtensions",
        "defaultValue": "StringExtensions"
      }
    }
  }

Den här konfigurationsfilen innehåller alla inställningar för mallen. Du kan se de grundläggande inställningarna, till exempel name och shortName, men det finns också ett tags/type värde som är inställt på item. Detta kategoriserar mallen som en "objektmall". Det finns ingen begränsning för vilken typ av mall du skapar. Värdena item och project är vanliga namn som .NET rekommenderar så att användarna enkelt kan filtrera den typ av mall som de söker efter.

Objektet classifications representerar kolumnen taggar som du ser när du kör dotnet new och hämtar en lista med mallar. Användare kan också söka baserat på klassificeringstaggar. Blanda inte ihop tags egenskapen i filen template.json med listan med classifications taggar. Det är två olika begrepp som tyvärr kallas samma. Det fullständiga schemat för filen template.json finns i JSON Schema Store och beskrivs i Referens för template.json. Mer information om filen template.json finns i wikin för dotnet-mallning.

Den symbols del av det här JSON-objektet används för att definiera de parametrar som kan användas i mallen. I det här fallet finns det en definierad parameter, ClassName. Den definierade parametern innehåller följande inställningar:

  • type – Det här är en obligatorisk inställning och måste anges till parameter.
  • description – Beskrivningen av parametern, som skrivs ut i mallhjälpen.
  • datatype – Typen av data för parametervärdet när parametern används.
  • replaces – Anger ett textvärde som ska ersättas i alla mallfiler med värdet för parametern.
  • fileRename – På liknande sätt replacesanger detta ett textvärde som ersätts i namnen på alla mallfiler med värdet för parametern.
  • defaultValue – Standardvärdet för den här parametern när parametern inte anges av användaren.

När mallen används kan användaren ange ett värde för parametern ClassName och det här värdet ersätter alla förekomster av StringExtensions. Om ett värde inte anges används det defaultValue . För den här mallen finns det två förekomster av StringExtensions: filen StringExtensions.cs och klassen StringExtensions. defaultValue Eftersom parametern är förblir StringExtensionsfilnamnet och klassnamnet oförändrade om parametern inte anges när du använder mallen. När ett värde har angetts byter filen till exempel dotnet new stringext -ClassName MyExtsnamn på MyExts.cs och klassen har bytt namn till MyExts.

Om du vill se vilka parametrar som är tillgängliga för en mall använder du parametern -? med mallnamnet:

dotnet new stringext -?

Vilket ger följande utdata:

Example templates: string extensions (C#)
Author: Me

Usage:
  dotnet new stringext [options] [template options]

Options:
  -n, --name <name>       The name for the output being created. If no name is specified, the name of the output directory is used.
  -o, --output <output>   Location to place the generated output.
  --dry-run               Displays a summary of what would happen if the given command line were run if it would result in a template creation.
  --force                 Forces content to be generated even if it would change existing files.
  --no-update-check       Disables checking for the template package updates when instantiating a template.
  --project <project>     The project that should be used for context evaluation.
  -lang, --language <C#>  Specifies the template language to instantiate.
  --type <item>           Specifies the template type to instantiate.

Template options:
  -C, --ClassName <ClassName>  The name of the code file and class.
                               Type: text
                               Default: StringExtensions

Nu när du har en giltig .template.config/template.json-fil är mallen redo att installeras. I terminalen går du till mappen tillägg och kör följande kommando för att installera mallen som finns i den aktuella mappen:

  • I Windows: dotnet new install .\
  • I Linux eller macOS: dotnet new install ./

Det här kommandot matar ut listan över installerade mallar, som bör innehålla dina.

The following template packages will be installed:
   <root path>\working\content\extensions

Success: <root path>\working\content\extensions installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code

Testa objektmallen

Nu när du har installerat en objektmall testar du den.

  1. Gå till testmappen.

  2. Skapa ett nytt konsolprogram med dotnet new console, som genererar ett fungerande projekt som du enkelt kan testa med dotnet run kommandot .

    dotnet new console

    Du får utdata som liknar följande.

    The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on C:\test\test.csproj...
  Restore completed in 54.82 ms for C:\test\test.csproj.

Restore succeeded.

  3. Kör projektet med hjälp av följande kommando.

    dotnet run

    Du får följande utdata.

    Hello, World!

  4. Kör dotnet new stringext för att generera filen StringExtensions.cs från mallen.

    dotnet new stringext

    Du får följande utdata.

    The template "Example templates: string extensions" was created successfully.

  5. Ändra koden i Program.cs för att vända strängen "Hello, World!" med tilläggsmetoden som tillhandahålls av mallen.

    Console.WriteLine("Hello, World!".Reverse());

    Kör programmet igen och se att resultatet är omvänd.

    dotnet run

    Du får följande utdata.

    !dlroW ,olleH

Grattis! Du skapade och distribuerade en objektmall med .NET. Som förberedelse för nästa del av den här självstudieserien avinstallerar du mallen som du skapade. Se till att ta bort alla filer och mappar i testmappen också. På så sätt återgår du till ett rent tillstånd som är redo för nästa del av den här självstudieserien.

Avinstallera mallen

I terminalen går du till mappen tillägg och kör följande kommando för att avinstallera mallarna som finns i den aktuella mappen:

  • I Windows: dotnet new uninstall .\
  • I Linux eller macOS: dotnet new uninstall ./

Det här kommandot matar ut en lista över de mallar som har avinstallerats, vilket bör inkludera dina.

Success: <root path>\working\content\extensions was uninstalled.

När som helst kan du använda dotnet new uninstall för att se en lista över installerade mallpaket, inklusive för varje mallpaket kommandot för att avinstallera det.

Nästa steg

I den här självstudien skapade du en objektmall. Om du vill lära dig hur du skapar en projektmall fortsätter du den här självstudieserien.

Skapa en projektmall