Új dotnet egyéni sablonjai

Cikk
08/15/2023

A .NET SDK számos már telepített és használatra kész sablont tartalmaz. A dotnet new parancs nem csak a sablon használatának módja, hanem a sablonok telepítésének és eltávolításának módja is. Létrehozhat saját egyéni sablonokat bármilyen típusú projekthez, például alkalmazáshoz, szolgáltatáshoz, eszközhöz vagy osztálytárhoz. Létrehozhat olyan sablont is, amely egy vagy több független fájlt, például konfigurációs fájlt ad ki.

Egyéni sablonokat bármely NuGet-csatornán telepíthet Egy NuGet-csomagból, ha közvetlenül egy NuGet .nupkg-fájlra hivatkozik, vagy megadhatja a sablont tartalmazó fájlrendszerkönyvtárat. A sablonmotor olyan funkciókat kínál, amelyek lehetővé teszik az értékek cseréjét, a fájlok belefoglalását és kizárását, valamint egyéni feldolgozási műveletek végrehajtását a sablon használatakor.

A sablonmotor nyílt forráskód, az online kódtár pedig a GitHubon található dotnet/templating helyen található. További sablonokat, köztük harmadik felektől származó sablonokat is találhat a használatával dotnet new search. További információ az egyéni sablonok létrehozásáról és használatáról: Hogyan hozhat létre saját sablonokat a dotnet új és a dotnet/templating GitHub-adattár wikijéhez.

Feljegyzés

Sablonpéldák a dotnet/templating GitHub-adattárban érhetők el.

Az útmutató követéséhez és a sablon létrehozásához tekintse meg az új dotnet-oktatóanyag egyéni sablonjának létrehozását ismertető témakört.

.NET alapértelmezett sablonjai

A .NET SDK telepítésekor több mint egy tucat beépített sablont kap projektek és fájlok létrehozásához, beleértve a konzolalkalmazásokat, osztálytárakat, egységtesztelési projekteket, ASP.NET Core-alkalmazásokat (beleértve az Angular- és React-projekteket) és a konfigurációs fájlokat. A beépített sablonok listázásához futtassa a dotnet new list következő parancsot:

dotnet new list

Konfiguráció

A sablon a következő részekből áll:

Forrásfájlok és mappák.
Konfigurációs fájl (template.json).

Forrásfájlok és mappák

A forrásfájlok és mappák tartalmazzák azokat a fájlokat és mappákat, amelyeket a sablonmotor a parancs futtatásakor dotnet new <TEMPLATE> használni szeretne. A sablonmotor úgy lett kialakítva, hogy futtatható projekteket használjon forráskódként a projektek létrehozásához. Ennek számos előnye van:

A sablonmotor nem követeli meg, hogy speciális jogkivonatokat injektáljon a projekt forráskódjába.
A kódfájlok nem speciális fájlok, és semmilyen módon nem módosíthatók a sablonmotor használatához. Így a projektek használatakor általában használt eszközök sablontartalommal is működnek.
A sablonprojekteket ugyanúgy hozhatja létre, futtathatja és hibakeresést végezhet, mint bármely más projekt esetében.
Egy meglévő projektből gyorsan létrehozhat sablont, ha hozzáad egy ./.template.config/template.json konfigurációs fájlt a projekthez.

A sablonban tárolt fájlok és mappák nem korlátozódnak a formális .NET-projekttípusokra. A forrásfájlok és mappák bármilyen tartalomból állhatnak, amelyeket a sablon használatakor létre szeretne hozni, még akkor is, ha a sablonmotor csak egy fájlt állít elő kimenetként.

A sablon által létrehozott fájlok a template.json konfigurációs fájlban megadott logika és beállítások alapján módosíthatók. A felhasználó felülbírálhatja ezeket a beállításokat úgy, hogy átadja a beállításokat a dotnet new <TEMPLATE> parancsnak. Az egyéni logika gyakori példája egy osztály vagy változó neve a sablon által üzembe helyezett kódfájlban.

template.json

A template.json fájl a sablon gyökérkönyvtárában található .template.config mappába kerül. A fájl konfigurációs információkat biztosít a sablonmotornak. A minimális konfigurációhoz az alábbi táblázatban szereplő tagok szükségesek, ami elegendő egy funkcionális sablon létrehozásához.

Tag	Típus	Leírás
`$schema`	URI	A template.json fájl JSON-sémája. A JSON-sémákat támogató szerkesztők engedélyezik a JSON-szerkesztési funkciókat a séma megadásakor. A Visual Studio Code-nak például engedélyeznie kell az IntelliSense-t. A következő érték `http://json.schemastore.org/template`használata: .
`author`	húr	A sablon szerzője.
`classifications`	tömb(sztring)	A sablon nulla vagy több tulajdonsága, amellyel a felhasználó megkeresheti a sablont a keresés során. A besorolások akkor is megjelennek a Címkék oszlopban, ha a parancs használatával `dotnet new list` létrehozott sablonok listájában jelennek meg.
`identity`	húr	A sablon egyedi neve.
`name`	húr	A sablon neve, amelyet a felhasználóknak látniuk kell.
`shortName`	húr	Az alapértelmezett rövidített név a sablon kiválasztásához, amely olyan környezetekre vonatkozik, ahol a sablon nevét a felhasználó adja meg, és nem grafikus felhasználói felületen van kiválasztva. A rövid név például akkor hasznos, ha parancssori parancssorból származó sablonokat használ cli-parancsokkal.
`sourceName`	húr	A forrásfa azon neve, amely a felhasználó által megadott névre cserélendő. A sablonmotor megkeresi a `sourceName` konfigurációs fájlban említett előfordulásokat, és lecseréli a fájlnevekre és a fájl tartalmára. A lecserélni kívánt érték a sablon futtatásakor megadható a beállítások vagy `--name` lehetőségek `-n` használatával. Ha nincs megadva név, a rendszer az aktuális könyvtárat használja.
`preferNameDirectory`	Logikai	Azt jelzi, hogy létre szeretne-e hozni egy könyvtárat a sablonhoz, ha a név meg van adva, de nincs beállítva kimeneti könyvtár (ahelyett, hogy közvetlenül az aktuális könyvtárban hozná létre a tartalmat). Az alapértelmezett érték: hamis.

A template.json fájl teljes sémája a JSON sématárolóban található. A template.json fájlról további információt a dotnet templating wikijében talál. Ha részletesebb példákat és információkat szeretne megtudni arról, hogyan teheti láthatóvá sablonjait a Visual Studióban, tekintse meg a Sayed Hashimi által létrehozott erőforrásokat.

Példa

Íme például egy sablonmappa, amely két tartalomfájlt tartalmaz: console.cs és readme.txt. A szükséges .template.config nevű mappa is tartalmazza a template.json fájlt.

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

A template.json fájl a következőhöz hasonlóan néz ki:

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

A mytemplate mappa egy telepíthető sabloncsomag. A csomag telepítése után a shortName parancs használható dotnet new . Például dotnet new adatumconsole az aktuális mappába adhatja ki a fájlokat és readme.txt a console.cs fájlokat.

Sablon honosítása

A .NET-sablonok honosíthatók. Ha egy sablon az aktuális területi beállításnak megfelelő nyelvhez van honosítva, az elemei ugyanabban a nyelven jelennek meg, mint a parancssori felület. A honosítás nem kötelező új sablonok létrehozásakor.

A sablon honosítható elemei a következők:

Név
Szerző
Leírás
Szimbólumok
- Leírás
- Megjelenítendő név
- A választási paraméterek választási lehetőségeinek leírása és megjelenítendő neve
Műveletek közzététele
- Leírás
- Manuális utasítások

A honosítási fájlok JSON formátumúak, és kultúránként csak egy fájlnak kell léteznie. Az elnevezési konvenció a következő: templatestrings.<lang code>.jsonahol lang code a CultureInfo egyik lehetőségének felel meg. Minden honosítási fájlnak a .template-config\localize mappában kell lennie.

A honosítási JSON kulcsértékpárokból áll:

A kulcs a honosítandó elemre template.json mutató hivatkozás. Ha az elem gyermek, használja a teljes elérési utat egy / elválasztójellel.
Az érték a kulcs által megadott elem honosítási sztringje.

A sablonok honosításáról további információt a dotnet templating wiki honosítási oldalán talál.

Példa

Például az alábbi template.json fájl néhány honosítható mezővel:

{
  "$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."
    }
  }
}

És egyes mezőket a brazil portugál nyelvre kell honosítani. A fájlnév templatestrings.pt-BR.json a kulturális környezetnek felel meg, és a következőképpen fog kinézni:

{
  "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."
}

Sablon csomagolása NuGet-csomagba (nupkg-fájl)

Egy egyéni sablon tele van a dotnet pack paranccsal és egy .csproj fájllal. Másik lehetőségként a NuGet a nuget pack paranccsal és egy .nuspec fájllal is használható. A NuGethez azonban Windows és Mono rendszeren, Linuxon és macOS rendszeren is szükség van a .NET-keretrendszer.

A .csproj fájl kissé eltér a hagyományos code-project .csproj fájltól. Ügyeljen a következő beállításokra:

A <PackageType> beállítás hozzá lesz adva, és a következőre van Templateállítva: .
A <PackageVersion> beállítás hozzá lesz adva, és egy érvényes NuGet-verziószámra van állítva.
A <PackageId> beállítás hozzáadódik, és egyedi azonosítóra van állítva. Ez az azonosító a sabloncsomag eltávolítására szolgál, és a NuGet-hírcsatornák használják a sabloncsomag regisztrálásához.
Az általános metaadat-beállításokat be kell állítani: <Title>, <Authors>, <Description>és <PackageTags>.
A <TargetFramework> beállítást be kell állítani, annak ellenére, hogy a sablonfolyamat által létrehozott bináris fájl nincs használatban. Az alábbi példában a következőre netstandard2.0van állítva: .

A .nupkg NuGet-csomag formájában lévő sabloncsomaghoz minden sablont a csomag tartalommappájában kell tárolni. A .csproj-fájlhoz további beállításokat is hozzá kell adni, hogy a létrehozott .nupkg sabloncsomagként telepíthető legyen:

A <IncludeContentInPack> beállítás úgy van beállítva, hogy true a projektkészleteket tartalomként tartalmazza a NuGet-csomagban.
A <IncludeBuildOutput> beállítás úgy van beállítva, hogy false kizárja a fordító által létrehozott összes bináris fájlt a NuGet-csomagból.
A <ContentTargetFolders> beállítás a következőre contentvan állítva: . Ez biztosítja, hogy a tartalomként beállított fájlok a NuGet-csomag tartalommappájában legyenek tárolva. A NuGet-csomagban lévő mappát a dotnet-sablonrendszer elemzi.

A sablonprojekt minden kódfájlt egyszerűen kizárhat abból, ha a <Compile Remove="**\*" /> projektfájl elemét használja egy <ItemGroup> elemen belül.

A sabloncsomag felépítésének egyszerű módja, ha az összes sablont külön mappákba helyezi, majd a .csproj fájllal azonos könyvtárban található sablonok mappájában lévő sablonmappák mindegyikét. Így egyetlen projektelem használatával az összes fájlt és mappát tartalomként is belefoglalhatja a sablonokba. Elemen <ItemGroup> belül hozzon létre egy <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> elemet.

Íme egy példa .csproj fájlra, amely az alábbi irányelvek mindegyikét követi. A sablonok gyermekmappáját a tartalomcsomag mappájába csomagolja, és kizárja a kódfájl fordítását.

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

Az alábbi példa bemutatja a .csproj sabloncsomag létrehozásához használt fájl- és mappastruktúráját. A MyDotnetTemplates.csproj fájl és a sablonok mappa egyaránt egy project_folder nevű könyvtár gyökerében található. A sablonok mappa két sablont tartalmaz: mytemplate1 és mytemplate2. Minden sablon tartalmaz tartalomfájlokat és egy .template.config mappát egy template.json konfigurációs fájllal.

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

Feljegyzés

Annak érdekében, hogy a sabloncsomag eredményként dotnet new search jelenjen meg, állítsa a NuGet-csomag típusát a következőre Template: .

Sabloncsomag telepítése

Sabloncsomag telepítéséhez használja a dotnet új telepítési parancsát.

Sabloncsomag telepítése a nuget.org-ben tárolt NuGet-csomagból

Sabloncsomag telepítéséhez használja a NuGet-csomag azonosítót.

dotnet new install <NUGET_PACKAGE_ID>

Sabloncsomag telepítése egyéni NuGet-forrásból

Adjon meg egy egyéni NuGet-forrást (például https://api.my-custom-nuget.com/v3/index.json).

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

Sabloncsomag telepítése helyi nupkg-fájlból

Adja meg a .nupkg NuGet-csomagfájl elérési útját.

dotnet new install <PATH_TO_NUPKG_FILE>

Sabloncsomag telepítése fájlrendszerkönyvtárból

A sablonok sablonmappából telepíthetők, például az előző példában szereplő mytemplate1 mappából. Adja meg a .template.config mappa elérési útját. A sablonkönyvtár elérési útjának nem kell abszolútnak lennie.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Telepített sabloncsomagok listájának lekérése

Az eltávolítási parancs minden más paraméter nélkül felsorolja az összes telepített sabloncsomagot és a mellékelt sablonokat.

dotnet new uninstall

A parancs a következő kimenethez hasonló eredményt ad vissza:

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

A sabloncsomagok eltávolításához használt azonosítók után Currently installed items: az elemek első szintje. Az előző példában Microsoft.Azure.WebJobs.ProjectTemplates pedig megjelenik a lista. Ha a sabloncsomag fájlrendszer-elérési úttal lett telepítve, ez az azonosító a .template.config mappa elérési útja. A listában csak a telepített dotnet new install sabloncsomagok jelennek meg. A .NET SDK-ba beépített sabloncsomagok nem jelennek meg.

Sabloncsomag eltávolítása

Sabloncsomag eltávolításához használja a dotnet új eltávolítási parancsát.

Ha a csomagot egy NuGet-hírcsatorna vagy egy .nupkg-fájl telepítette közvetlenül, adja meg az azonosítót.

dotnet new uninstall <NUGET_PACKAGE_ID>

Ha a csomagot a .template.config mappa elérési útjának megadásával telepítette, az elérési úton távolíthatja el a csomagot. A sabloncsomag abszolút elérési útját a parancs által megadott kimenetben tekintheti meg dotnet new uninstall . További információ: A telepített sablonok listájának lekérése szakasz.

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Projekt létrehozása egyéni sablonnal

Miután telepített egy sablont, használja a sablont úgy, hogy végrehajtja a dotnet new <TEMPLATE> parancsot, ahogyan bármely más előre telepített sablon esetében tenné. A parancs beállításait is megadhatja, beleértve a dotnet new sablonbeállításokban konfigurált sablonspecifikus beállításokat is. Adja meg közvetlenül a parancsnak a sablon rövid nevét:

dotnet new <TEMPLATE>

Megosztás a következőn keresztül:

Új dotnet egyéni sablonjai

.NET alapértelmezett sablonjai

Konfiguráció

Forrásfájlok és mappák

template.json

Példa

Sablon honosítása

Példa

Sablon csomagolása NuGet-csomagba (nupkg-fájl)

Sabloncsomag telepítése

Sabloncsomag telepítése a nuget.org-ben tárolt NuGet-csomagból

Sabloncsomag telepítése egyéni NuGet-forrásból

Sabloncsomag telepítése helyi nupkg-fájlból

Sabloncsomag telepítése fájlrendszerkönyvtárból

Telepített sabloncsomagok listájának lekérése

Sabloncsomag eltávolítása

Projekt létrehozása egyéni sablonnal

Lásd még

További források