.NET sablonok szerzőknek

Sablonkészítőként .NET sablonokat hoz létre– tervrajzokat, amelyek projekteket, fájlokat vagy más erőforrásokat hoznak létre előre definiált struktúrából. A felhasználók futtatásakor dotnet new <shortName>a .NET sablonmotor beolvassa a sablont, és létrehozza a kimenetet az aktuális könyvtárban. Visual Studio Create a new project dialog is használja a .NET sablonmotort .NET projektsablonokhoz, így a parancssori felülethez készített sablonok Visual Studio is működnek.

A .NET SDK beépített sablonokkal rendelkezik a gyakori kiindulási pontokhoz, például konzolalkalmazásokhoz, osztálykódtárakhoz és ASP.NET projektekhez. A beépített sablonokon túl saját sablonokat is létrehozhat, és NuGet-csomagként terjesztheti őket.

Ez a cikk sablonkészítőknek szóló hivatkozás. Ismerteti a sablonok strukturálását, konfigurálását és terjesztését. A sablonok létrehozásának és csomagolásának részletes útmutatását a Kapcsolódó tartalom szakaszban találja.

Sablontípusok

A .NET sablonmotor három sablontípust támogat: elemsablonokat, projektsablonokat és megoldássablonokat.

  • Az elemsablonok egy vagy több fájlt, például kódfájlt, konfigurációs fájlt vagy más erőforrást hoznak létre anélkül, hogy teljes projektet hoznak létre körülötte. Előfordulhat például, hogy egy elemsablon olyan osztályfájlt hoz létre, amely bővítménymetelyeket ad hozzá, vagy egy olyan JSON-konfigurációs fájlt, amely a csapat által használt szokásos elrendezést követi. Az elemsablonok létrehozásának módjáról az Oktatóanyag: Elemsablon létrehozása című témakörben olvashat.

  • Project sablonok teljes project struktúrát hoznak létre. A beépített konzolprojektsablon például létrehoz egy .csproj fájlt, egy Program.cs fájlt és minden más fájlt, amely a projektet alkotja. Projektsablon készítése, ha a felhasználók számára az egyes fájlok helyett teljes projektkezdetet szeretne adni. A projektsablonok létrehozásának módjáról a következő oktatóanyagban olvashat: Projektsablon létrehozása.

  • A megoldássablonok egy vagy több projekttel rendelkező megoldást hoznak létre. A megoldássablonok például egyetlen lépésben hozhatnak létre egy tesztprojekttel párosított API-projektet.

Saját sablon létrehozásakor deklarálja annak típusát a tags.typetemplate.json konfigurációs fájl mezője alapján. Az érvényes értékek a következők: "project", "item"és "solution". Ezek az értékek lehetővé teszik a felhasználók számára az eredmények szűrését, amikor sablonokat keresnek vagy dotnet new searchdotnet new list.

Tip

Project és megoldássablonok jelennek meg az Visual Studio Új project létrehozása párbeszédpanelen, de az elemsablonok nem jelennek meg azÚj elemhozzáadása> párbeszédpanelen. A felhasználók a parancssori felületről érhetik el az dotnet new elemsablonokat.

Sablonstruktúra

A sablon egy lemezen lévő mappa, amely két dolgot tartalmaz: a sablon forrásfájljait és egy speciális .template.config almappát. Amikor egy felhasználó fut dotnet new <shortName>, a sablonmotor átmásolja a forrásfájlokat a kimeneti helyre, és alkalmazza a sablonhoz definiált konfigurációkat.

mytemplate/
├── console.cs
├── readme.txt
└── .template.config/
    ├── template.json
    └── icon.png

A forrásfájlok bármilyen típusú fájl lehetnek. A sablonmotor nem követeli meg, hogy speciális jogkivonatokat vagy jelölőket szúrjon be a forráskódba. A as-isfájlokat használja, ami azt jelenti, hogy a sablon forrásprojektjét pontosan úgy hozhatja létre, futtathatja és hibakereséssel végezheti el, mint egy normál .NET projektet. Ha egy meglévő projektet sablonná szeretne alakítani, adjon hozzá egy .template.config/template.json fájlt a projekt gyökeréhez.

A sablonparaméterekhez (szimbólumokhoz) kötődő helyettesítő jogkivonatokat is beszúrhatja közvetlenül a sablonforrásfájlokba és fájlnevekbe. Ha a jogkivonatok nem érvényes forráskódok, sablonként való üzembe helyezés előtt nem lehet létrehozni, futtatni vagy hibakeresést végezni a forrásprojektben. A jogkivonatok nem érintik a felhasználók által az üzembe helyezett sablonból létrehozott projekteket, mert a sablonmotor lecseréli őket a projekt létrehozása során.

Az egyetlen szükséges fájl az .template.config .template.json Ez a fájl mindent elmond a sablonmotornak, amire szüksége van: a sablon nevét, rövid nevét, szerzőjét, besorolásait és minden paramétert, amelyet a felhasználók átadhatnak a sablonból való létrehozáskor. A fájlokat icon.png a .template.config mappába is elhelyezheti. A terminál nem jelenít meg ikonokat, de Visual Studio az új projekt létrehozása párbeszédpanelen a sablon melletti ikont jeleníti meg. A 128×128 PNG jól működik.

A template.json fájl

A template.json fájl az egyetlen szükséges konfigurációelem a sablonban. A mappa belsejében .template.config található, és közli a sablonmotorral, hogyan jelenítheti meg és dolgozhatja fel a sablont. Az alábbi táblázat a gyakori kötelező és nem kötelező mezőket ismerteti:

Field Típus Kötelező Description
$schema URI Nem A JSON-séma a következőhöz template.json: . Úgy van beállítva, hogy https://json.schemastore.org/template engedélyezze az IntelliSense-t olyan szerkesztőkben, mint a Visual Studio Code.
author karakterlánc Nem A sablon szerzője.
classifications tömb(karakterlánc) Nem Címkék, amellyel a felhasználók megkereshetik a sablont a következővel dotnet new search : vagy dotnet new list. Ezek az értékek a sablonlista Címkék oszlopában jelennek meg.
description karakterlánc Nem A sablon létrehozásának leírása.
identity karakterlánc Igen A sablon egyedi azonosítója.
name karakterlánc Igen A felhasználók számára megjelenített sablon neve.
shortName karakterlánc Igen A felhasználók által a sablonból létrehozandó dotnet new rövid név, például console vagy classlib.
sourceName karakterlánc Nem A forrásfájlok és fájlnevek sztringje, amelyet a sablonmotor a felhasználó által megadott névre cserél.-n--name Ha a felhasználó nem ad meg nevet, a motor az aktuális könyvtárnevet használja.
preferNameDirectory boolean Nem Amikor true a felhasználó megad egy nevet, de nincs kimeneti könyvtár, a sablonmotor új könyvtárat hoz létre ezzel a névvel ahelyett, hogy fájlokat ír az aktuális könyvtárba. Az alapértelmezett érték a false.
tags objektum Nem Olyan tulajdonságokat azonosító metaadatok, mint a sablon nyelve és típusa. A tags.language nyelv tags.typeprojectés a , itemvagy solution.

Két mező külön figyelmet érdemel. A sourceName mező az, ahogyan a sablonok kezelik az elnevezést: állítsa be egy sztringre, amely megjelenik a fájlnevekben és a forráskódban (például MyTemplate), és a sablonmotor minden előfordulást lecserél bármilyen névre, amelyet a felhasználó a sablon létrehozásakor átad. A classifications mező szabályozza a felderíthetőséget; válasszon olyan címkéket, amelyek pontosan írják le a sablon célját, hogy a felhasználók megtalálhassák a keresés során.

Íme egy minimális template.json konzolsablon:

{
  "$schema": "https://json.schemastore.org/template",
  "author": "Your Name",
  "classifications": [ "Common", "Console" ],
  "description": "Creates a console application.",
  "identity": "MyCompany.ConsoleTemplate.CSharp",
  "name": "My Console App",
  "shortName": "myconsole",
  "sourceName": "MyConsoleApp",
  "tags": {
    "language": "C#",
    "type": "project"
  }
}

A teljes séma elérhető a JSON sématárolójában. Az olyan speciális konfigurációs beállításokat, mint a feltételes fájlbefoglalás, a létrehozás utáni műveletek és a többprojektes sablonok, tekintse meg a dotnet/templating GitHub wikit.

Sablonparaméterek (szimbólumok)

A symbols szakasz template.json meghatározza, hogy a felhasználók milyen paramétereket adhatnak át a sablonból való létrehozáskor. Minden szimbólum parancssori dotnet new <shortName>felületi beállítássá válik, így egy elnevezett ClassName szimbólum lesz --ClassName (vagy -C ha rövid nevet ad meg).

Minden szimbólumbejegyzés a következő gyakori beállításokat támogatja:

Setting Description
type A felhasználó által használt paramétereknek kell lenniük "parameter" .
description A sablon súgókimenete a felhasználók futtatásakor jelenik meg dotnet new <shortName> -?.
datatype A várt adattípus, például "text": , "bool"vagy "choice".
replaces A forrásfájl tartalmának egy sztringje, amelyet a sablonmotor a paraméterértékre cserél.
fileRename A forrásfájlnevek egyik sztringje, amelyet a sablonmotor a paraméterértékre cserél.
defaultValue Az az érték, amelyet akkor használunk, ha a felhasználó nem adja meg a paramétert.

A replaces szimbólumok és fileRename a beállítások a helyettesítést hajtó szimbólumok. Amikor egy felhasználó megad egy értéket, a sablonmotor lecseréli a sztring minden előfordulását a replaces fájl tartalmában, és a sztring minden előfordulását a fileRename fájlnevekben. Ha a felhasználó nem ad meg értéket, akkor a rendszer ezt defaultValue használja.

Az alábbi szimbólum például lehetővé teszi, hogy a felhasználók beállítják az osztály nevét, amikor a sablonból jönnek létre. A fájl átnevezve lesz, és a benne lévő osztály a következőnek megfelelően frissül:

"symbols": {
  "ClassName": {
    "type": "parameter",
    "description": "The name of the code file and class.",
    "datatype": "text",
    "replaces": "StringExtensions",
    "fileRename": "StringExtensions",
    "defaultValue": "StringExtensions"
  }
}

Ezzel a szimbólummal a felhasználó futtathat dotnet new <shortName> --ClassName MyHelpers egy olyan fájlt MyHelpers.cs , amely egy nevesített MyHelpersosztályt tartalmaz. A jelölő nélkül a fájl és az osztály megtartja az alapértelmezett nevet StringExtensions.

A sablon által megjelenített paraméterek ellenőrzéséhez a telepítés után adja meg -? a rövid nevét:

dotnet new <shortName> -?

Sabloncsomagok

A sabloncsomagok olyan NuGet-fájlok,.nupkg amelyek egy vagy több sablont kötenek össze. Amikor egy felhasználó telepíti a sabloncsomagot, a .NET sablonmotor egyszerre regisztrálja benne az összes sablont. A csomagok a sablonok terjesztésének szabványos módjai. Egyetlen csomag közzététele NuGet.org vagy privát NuGet-hírcsatornában, vagy helyi .nupkg fájl megosztása, és a felhasználók egyetlen paranccsal kapják meg a teljes gyűjteményt.

Sabloncsomag létrehozásához használjon egy C#-projektfájlt (.csproj), amely úgy van konfigurálva, hogy csomagolási projektként működjön, nem fordítási projektként. A következő kulcsbeállítások teszik ezt a munkát:

Setting Érték Alkalmazás célja
PackageType Template A csomagot sabloncsomagként jelöli meg, így megjelenik az eredmények között dotnet new search .
IncludeContentInPack true Tartalomfájlokat tartalmaz a NuGet-csomagban.
IncludeBuildOutput false Megakadályozza, hogy a lefordított bináris fájlok hozzá legyenek adva a csomaghoz.
ContentTargetFolders content A sablonmappákat a content NuGet-csomag mappájába helyezi, ahol a sablonmotor várhatóan megtalálja őket.

A templatepack projektsablon a csomagolási projekt létrehozásának legegyszerűbb módja:

  1. Telepítse a Microsoft. TemplateEngine.Authoring.Templates NuGet-csomag:

    dotnet new install Microsoft.TemplateEngine.Authoring.Templates

  2. Hozza létre a csomagolási projektet:

    dotnet new templatepack -n <PackageName>

A létrehozott projekt tartalmazza a megfelelő .csproj beállításokat, a content sablonok mappáját, valamint az MSBuild-feladatokat a sablonérvényesítéshez és az opcionális honosításhoz.

A sabloncsomagok létrehozásának, csomagolásának és közzétételének teljes útmutatóját a következő oktatóanyagban találja: Sabloncsomag létrehozása.

A sablon helyi tesztelése

A sablonfejlesztés során telepítse a sablont közvetlenül a mappájából, hogy a csomagot anélkül tesztelje, hogy először létrehozná a csomagot. Adja meg a mappát tartalmazó .template.config könyvtár elérési útját:

dotnet new install ./mytemplate/

Ha meg szeretné tekinteni az összes telepített sabloncsomagot és az egyes példányok eltávolítására vonatkozó pontos parancsot, futtassa dotnet new uninstall argumentumok nélkül:

dotnet new uninstall

A címtárból telepített sablon eltávolításához adja meg ugyanazt a könyvtár elérési útját, amelyet a telepítéshez használt:

dotnet new uninstall ./mytemplate/

Miután készen áll a sablon megosztására, csomagolja nuGet-csomagként (lásd a sabloncsomagokat), és ossza el. A felhasználók a közzétett sablont az alábbi forrásargumentumok egyikével dotnet new install telepítik:

  • Egy NuGet-csomagazonosító, amely az aktuális könyvtárhoz konfigurált NuGet-forrásokból telepíti a legújabb stabil verziót:

    dotnet new install AdatumCorporation.ConsoleTemplate.CSharp

  • Egyéni hírcsatorna URL-címével rendelkező NuGet-csomagazonosító. A --nuget-source beállítás a megadott hírcsatornát használja a konfigurált NuGet-forrásokon kívül csak az adott telepítéshez:

    dotnet new install AdatumCorporation.ConsoleTemplate.CSharp --nuget-source https://mynugetfeed.example.com/v3/index.json

  • Egy helyi .nupkg fájl elérési útja:

    dotnet new install ./AdatumCorporation.ConsoleTemplate.CSharp.1.0.0.nupkg

Warning

A sablonok msbuild feladatokat és tetszőleges kódot futtathatnak a projekt létrehozása során. Csak megbízható forrásokból telepítsen sablonokat.

NuGet-forrásból vagy helyi .nupkg fájlból telepített csomag eltávolításához használja a NuGet-csomag azonosítóját:

dotnet new uninstall AdatumCorporation.ConsoleTemplate.CSharp

A beépített SDK-sablonok nem jelennek meg az eltávolítási listában, és nem távolíthatók el.dotnet new uninstall

Sablon honosítása

A .NET sablonmotor támogatja a sablon metaadatainak opcionális honosítását. Ha honosítási fájlokat ad meg, az olyan gazdagépek, mint például dotnet new a Visual Studio Új Project párbeszédpanel, a sablon nevét, leírását és szimbólumadatait a felhasználó nyelvén jelenítik meg az eredeti, szerzői nyelv helyett.

A következő sablonmezők támogatják a honosítást:

  • name
  • author
  • description
  • Szimbólum description és displayName
  • Az egyes választási lehetőségek leírása és megjelenítendő neve egy választási paraméterben
  • Művelet description közzététele és manualInstructions

Honosítás hozzáadásához hozzon létre egy almappát localize , .template.config és adjon hozzá nyelvenként egy JSON-fájlt. Nevezze el az egyes fájlokat templatestrings.<lang-code>.json, ahol <lang-code> egy érvényes CultureInfo név egyezik, például pt-BR: , zh-Hansvagy de. Minden fájl kulcs-érték párokat tartalmaz, ahol a kulcs a beágyazott mezők elválasztójaként használható / elem template.jsonelérési útja.

Például a következő tartalommal:template.json

{
  "$schema": "https://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."
    }
  }
}

Egy brazil portugál honosítási fájl neve templatestrings.pt-BR.json így nézne ki:

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

A sablonmotor elemzi ezeket a fájlokat, amikor betölti a sabloninformációkat, és automatikusan visszaadja a honosított értékeket az aktuális felhasználói felületi kultúra alapján – a felhasználónak nincs szükség további lépésekre.

A honosítás nem kötelező. Ha nem tartalmaz honosítási fájlokat, a sablon normál módon működik, és mindig megjeleníti a forrás értékeit template.json. További információt a dotnet/templating wiki honosítási oldalán talál.

Visual Studio-integráció

Visual Studio Új projekt létrehozása párbeszédpanel a .NET sablonmotort használja .NET projektsablonokhoz. dotnet new A Visual Studio-ban is készített sablonokat további konfiguráció nélkül. Amikor egy felhasználó telepíti a sabloncsomagotdotnet new install, Visual Studio automatikusan észleli és felfedi ezeket a sablonokat a párbeszédpanelen.

Project és megoldássablonok jelennek meg az Új project létrehozása párbeszédpanelen a beépített SDK-sablonok mellett. A felhasználók a sablon fájljának mezőjében classifications név, nyelv vagy címkék alapján találhatnak template.json sablonokat. A pontos besorolások segítik a sablon felületét a megfelelő szűrőkategóriákban, ezért gondosan válassza ki őket. Ha fényes megjelenést szeretne adni a sablonnak a párbeszédpanelen, vegyen fel egy icon.png újat a .template.config mappába – Visual Studio a sablon neve mellett jeleníti meg.

Az Elemsablonok jelenleg nem jelennek meg azÚj elemhozzáadása> párbeszédpanelen. A felhasználók továbbra is használhatnak elemsablonokat a dotnet new terminál parancsával.

Ha azt szeretné, hogy a sablon felderíthető legyen Visual Studio olyan felhasználók számára, akik még nem telepítették, tegye közzé a sabloncsomagot nuget.org. Az Új projekt létrehozása párbeszédpanel tartalmaz egy További sablonok telepítése lehetőséget az online keresési lehetőségből, amely nuget.org keres sabloncsomagokat. Amikor egy felhasználó ezen a beállításon keresztül telepíti a csomagot, Visual Studio ugyanazt a telepítési mechanizmust használja, mint dotnet new installa .

A Visual Studio-specifikus integrációval kapcsolatos részletesebb útmutatásért ( például a sablon rendezési sorrendjének szabályozásához és a további IDE-specifikus beállítások konfigurálásához ) lásd: Sayed Hashimi sablonminta-adattára.

Kapcsolódó tartalom

  • Last updated on