Yazarlar için .NET şablonları

Şablon yazarı olarak önceden tanımlanmış bir yapıdan proje, dosya veya başka kaynaklar oluşturan şemalar gibi .NET şablonları oluşturursunuz. Kullanıcılar çalıştırdığındadotnet new <shortName>, .NET şablon altyapısı şablonu okur ve çıktıyı geçerli dizinde üretir. Visual Studio Yeni proje oluştur iletişim kutusunda .NET proje şablonları için .NET şablon altyapısı da kullanılır; böylece CLI için oluşturduğunuz şablonlar da Visual Studio'de çalışır.

.NET SDK'sı konsol uygulamaları, sınıf kitaplıkları ve ASP.NET projeleri gibi yaygın başlangıç noktaları için yerleşik şablonlarla birlikte gönderilir. Bu yerleşik şablonların ötesinde kendi şablonlarınızı yazabilir ve bunları NuGet paketleri olarak dağıtabilirsiniz.

Bu makale, şablon yazarları için bir başvurudur. Şablonların nasıl yapılandırıldığını, yapılandırıldığını ve dağıtıldığını kapsar. Şablon oluşturma ve paketlemeye yönelik adım adım yönergeler için İlgili içerik bölümüne bakın.

Şablon türleri

.NET şablon altyapısı üç şablon türünü destekler: öğe şablonları, proje şablonları ve çözüm şablonları.

  • Öğe şablonları , çevresinde projenin tamamını oluşturmadan kod dosyası, yapılandırma dosyası veya başka bir kaynak gibi bir veya daha fazla dosya oluşturur. Örneğin, bir öğe şablonu bir uzantı yöntemleri kümesi ekleyen bir sınıf dosyası veya ekibinizin kullandığı standart düzeni izleyen bir JSON yapılandırma dosyası üretebilir. Öğe şablonu oluşturmayı öğrenmek için bkz . Öğretici: Öğe şablonu oluşturma.

  • Project şablonları eksiksiz bir project yapısı oluşturur. Örneğin, yerleşik konsol projesi şablonu bir .csproj dosya, dosya Program.cs ve projeyi oluşturan diğer dosyaları oluşturur. Kullanıcılara tek tek dosyalar yerine tam proje başlangıç noktası vermek istediğinizde bir proje şablonu yazın. Proje şablonu oluşturmayı öğrenmek için bkz . Öğretici: Proje şablonu oluşturma.

  • Çözüm şablonları bir veya daha fazla proje içeren bir çözüm oluşturur. Örneğin, bir çözüm şablonu tek adımda bir test projesiyle eşleştirilmiş bir API projesi oluşturabilir.

Kendi şablonunuzu oluşturduğunuzda, yapılandırma dosyasındaki tags.typetemplate.json alanı kullanarak türünü bildirirsiniz. Geçerli değerler "project", "item"ve "solution". Bu değerler, kullanıcıların veya dotnet new listile dotnet new search şablon ararken sonuçları filtrelemesine olanak sağlar.

Tip

yeni project oluştur iletişim Visual Studio Project ve çözüm şablonları görüntülenir, ancak öğe şablonlarıYeni ÖğeEkle> iletişim kutusunda görünmez. Kullanıcılar CLI'dan öğe şablonlarına dotnet new erişebilir.

Şablon yapısı

Şablon, diskte iki öğe içeren bir klasördür: şablon kaynak dosyaları ve özel .template.config bir alt klasör. Kullanıcı çalıştırdığında dotnet new <shortName>, şablon altyapısı kaynak dosyaları çıkış konumuna kopyalar ve şablon için tanımladığınız tüm yapılandırmaları uygular.

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

Kaynak dosyalar herhangi bir dosya türü olabilir. Şablon altyapısı, kaynak koda özel belirteçler veya işaretçiler eklemenizi gerektirmez. as-isdosyalarını kullanır; başka bir deyişle, şablonun kaynak projesini tam olarak normal bir .NET projesi gibi derleyebilir, çalıştırabilir ve hatalarını ayıklayabilirsiniz. Var olan bir projeyi şablona dönüştürmek için proje köküne bir .template.config/template.json dosya ekleyin.

İsteğe bağlı olarak şablon parametrelerine (simgeler) bağlı değiştirme belirteçlerini doğrudan şablon kaynak dosyalarına ve dosya adlarına ekleyebilirsiniz. Belirteçler geçerli bir kaynak kodu değilse, şablon olarak dağıtmadan önce kaynak projeyi oluşturamaz, çalıştıramaz veya hatalarını ayıklayamazsınız. Belirteçler, kullanıcıların dağıtılan şablondan oluşturduğu projeleri etkilemez çünkü şablon altyapısı proje oluşturma sırasında bunların yerini alır.

içindeki .template.config tek gerekli dosyadır template.json. Bu dosya şablon altyapısına gereken her şeyi söyler: şablonun adı, kısa adı, yazarı, sınıflandırmaları ve kullanıcıların şablondan oluşturduklarında geçirebileceği parametreler. Klasöre bir icon.png dosya .template.config da yerleştirebilirsiniz. Terminal simgeleri görüntülemez, ancak Visual Studio yeni proje oluştur iletişim kutusundaki şablonun yanındaki simgeyi gösterir. A 128×128 PNG iyi çalışır.

template.json dosyası

Dosya template.json , şablondaki tek gerekli yapılandırma parçasıdır. Klasörün içinde yer alır .template.config ve şablon altyapısına şablonunuzu nasıl sunup işleyebilmek için ne yapılacağını söyler. Aşağıdaki tabloda yaygın gerekli ve isteğe bağlı alanlar açıklanmaktadır:

Alan Türü Gerekli Description
$schema URI Hayı için template.jsonJSON şeması. https://json.schemastore.org/template Visual Studio Code gibi düzenleyicilerde IntelliSense'i etkinleştirmek için olarak ayarlayın.
author string Hayı Şablonun yazarı.
classifications array(dize) Hayı Kullanıcıların veya dotnet new listile dotnet new search şablonu bulmak için kullanabileceği etiketler. Bu değerler şablon listesinin Etiketler sütununda görünür.
description string Hayı Şablonun oluşturduğu şeyin açıklaması.
identity string Yes Şablon için benzersiz bir tanımlayıcı.
name string Yes Kullanıcılara gösterilen şablonun görünen adı.
shortName string Yes Veya gibi consoleclasslibşablondan oluşturmak için dotnet new kullanıcıların geçtiği kısa ad.
sourceName string Hayı Kaynak dosyalarınızdaki ve dosya adlarındaki, şablon altyapısının yerine kullanıcının veya --namearacılığıyla -n sağladığı adla değiştirdiğini belirten bir dize. Kullanıcı bir ad sağlamazsa, altyapı geçerli dizin adını kullanır.
preferNameDirectory Boolean Hayı Ve kullanıcı bir ad sağladığında ancak çıkış dizini sağlamadığında true , şablon altyapısı geçerli dizine dosya yazmak yerine bu ada sahip yeni bir dizin oluşturur. Varsayılan değer: false.
tags object Hayı Şablon dili ve türü gibi özellikleri tanımlayan meta veriler. dili ve tags.type , itemveya solutioniçin projectkullanıntags.language.

İki alan fazladan ilgiyi hakeder. Bu sourceName alan, şablonların adlandırmayı nasıl işlediğidir: bunu dosya adlarınızda ve kaynak kodunuzda (gibi) görünen bir dize olarak MyTemplateayarlayın ve şablon altyapısı her oluşumu kullanıcının şablonu oluştururken geçirdiği adla değiştirir. Alan classifications bulunabilirliği denetler; kullanıcıların arama yaparken bulabilmesi için şablonunuzun amacını doğru şekilde açıklayan etiketler seçin.

Konsol şablonu için en azı template.json aşağıdadır:

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

Tam şema JSON Şema Deposu'nda kullanılabilir. Koşullu dosya ekleme, oluşturma sonrası eylemler ve çok projeli şablonlar gibi gelişmiş yapılandırma seçenekleri için bkz. dotnet/templating GitHub wiki.

Şablon parametreleri (simgeler)

symbols içindeki template.json bölümü, kullanıcıların şablonunuzdan oluştururken geçirebileceği parametreleri tanımlar. Her simge üzerinde dotnet new <shortName>bir CLI seçeneğine dönüşür, bu nedenle adlı ClassName bir simge olur --ClassName (veya -C kısa bir ad tanımlarsanız).

Her sembol girdisi aşağıdaki yaygın ayarları destekler:

Setting Description
type Kullanıcıya yönelik parametreler için olmalıdır "parameter" .
description Kullanıcılar komutunu çalıştırdığında dotnet new <shortName> -?şablon yardımı çıkışında gösterilir.
datatype , veya "choice"gibi "text""bool"beklenen veri türü.
replaces Kaynak dosya içeriğinizde şablon altyapısının parametre değeriyle değiştirdiğini belirten bir dize.
fileRename Kaynak dosyanızdaki bir dize, şablon altyapısının parametre değeriyle değiştirir.
defaultValue Kullanıcı parametresini sağlamadığında kullanılan değer.

replaces ve fileRename ayarları, simgelerin değiştirme işlemini nasıl yönlendirdiğidir. Kullanıcı bir değer sağladığında şablon altyapısı, dosya içeriği içindeki dizenin replaces her oluşumunu ve dosya adlarındaki dizenin fileRename her oluşumunu değiştirir. Kullanıcı bir değer sağlamazsa, defaultValue bunun yerine kullanılır.

Örneğin, aşağıdaki simge kullanıcıların şablondan oluştururken sınıf adını ayarlamasına olanak tanır. Dosya yeniden adlandırılır ve içindeki sınıf eşleşecek şekilde güncelleştirilir:

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

Bu simge tanımlandığında, kullanıcı adlı MyHelpersbir sınıfı içeren adlı MyHelpers.cs bir dosya oluşturmak için komutunu çalıştırabilirdotnet new <shortName> --ClassName MyHelpers. bayrağı olmadan, dosya ve sınıf varsayılan adını StringExtensionstutar.

Şablonunuzun kullanıma sunduğu parametreleri doğrulamak için, yükledikten sonra kısa adına geçin -? :

dotnet new <shortName> -?

Şablon paketleri

Şablon paketi, şablonlarınızdan birini veya daha fazlasını birlikte paketleyen bir NuGet (.nupkg) dosyasıdır. Kullanıcı şablon paketinizi yüklediğinde, .NET şablon altyapısı içindeki her şablonu aynı anda kaydeder. Paketler, şablonları dağıtmanın standart yoludur. NuGet.org veya özel bir NuGet akışına tek bir paket yayımlayın ya da yerel .nupkg bir dosya paylaşın; kullanıcılar tek bir komutla koleksiyonun tamamını alır.

Şablon paketi oluşturmak için, derleme projesi yerine paketleme projesi olarak davranacak şekilde yapılandırılmış bir C# proje dosyası (.csproj) kullanın. Bu çalışmayı sağlayan temel ayarlar şunlardır:

Setting Değer Purpose
PackageType Template Paketi şablon paketi olarak işaretler ve sonuç olarak dotnet new search görünür.
IncludeContentInPack true NuGet paketine içerik dosyaları ekler.
IncludeBuildOutput false Derlenmiş ikili dosyaların pakete eklenmesini engeller.
ContentTargetFolders content Şablon klasörlerinizi content , şablon altyapısının bunları bulmayı beklediği NuGet paketinin klasörüne yerleştirir.

Proje templatepack şablonu, paketleme projesi oluşturmanın en kolay yolunu sağlar:

  1. Microsoft yükleyin. TemplateEngine.Authoring.Templates NuGet paketi:

    dotnet new install Microsoft.TemplateEngine.Authoring.Templates

  2. Paketleme projesini oluşturun:

    dotnet new templatepack -n <PackageName>

Oluşturulan proje doğru .csproj ayarları, şablonlarınız için bir content klasörü ve şablon doğrulama ve isteğe bağlı yerelleştirme için MSBuild görevlerini içerir.

Şablon paketi oluşturma, paketleme ve yayımlama hakkında tam kılavuz için bkz . Öğretici: Şablon paketi oluşturma.

Şablonunuzu yerel olarak test edin

Şablon geliştirme sırasında, önce bir paket oluşturmadan test etmek için şablonunuzu doğrudan klasöründen yükleyin. Yolu, klasörü içeren dizine geçirin .template.config :

dotnet new install ./mytemplate/

Yüklü tüm şablon paketlerini ve her birini kaldırmaya yönelik tam komutu görmek için bağımsız değişken olmadan komutunu çalıştırın dotnet new uninstall :

dotnet new uninstall

Bir dizinden yüklenen bir şablonu kaldırmak için, yüklemek için kullandığınız dizin yolunu geçirin:

dotnet new uninstall ./mytemplate/

Şablonunuzu paylaşmaya hazır olduğunuzda, şablonu NuGet paketi olarak paketleyin (bkz . Şablon paketleri) ve dağıtın. Kullanıcılar yayımlanan şablonunuzu dotnet new install ve aşağıdaki kaynak bağımsız değişkenlerinden birini yükler:

  • Geçerli dizin için yapılandırılan NuGet kaynaklarından en son kararlı sürümü yükleyen bir NuGet paket kimliği:

    dotnet new install AdatumCorporation.ConsoleTemplate.CSharp

  • Özel akış URL'si olan bir NuGet paket kimliği. --nuget-source seçeneği, yalnızca bu yükleme için yapılandırılan NuGet kaynaklarına ek olarak belirtilen akışı kullanır:

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

  • Yerel .nupkg dosyanın yolu:

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

Warning

Şablonlar, proje oluşturma sırasında MSBuild görevlerini ve rastgele kodu çalıştırabilir. Yalnızca güvendiğiniz kaynaklardan şablonları yükleyin.

NuGet kaynağından veya yerel .nupkg dosyadan yüklenen bir paketi kaldırmak için NuGet paket kimliğini kullanın:

dotnet new uninstall AdatumCorporation.ConsoleTemplate.CSharp

Yerleşik SDK şablonları kaldırma listesinde görünmez ve ile dotnet new uninstallkaldırılamaz.

Şablon yerelleştirmesi

.NET şablon altyapısı, şablon meta verilerinin isteğe bağlı yerelleştirilmesini destekler. Yerelleştirme dosyaları sağladığınızda, ve gibi dotnet new konaklar ve Visual Studio Yeni Project iletişim kutusu şablonun adını, açıklamasını ve simge bilgilerini özgün yazılan dil yerine kullanıcının dilinde görüntüler.

Aşağıdaki şablon alanları yerelleştirmeyi destekler:

  • name
  • author
  • description
  • Simgesi description ve displayName
  • Seçim parametresindeki her seçim için açıklama ve görünen ad
  • Eylem description gönder ve manualInstructions

Yerelleştirme eklemek için içinde .template.config bir localize alt klasör oluşturun ve dil başına bir JSON dosyası ekleyin. Her dosyayı templatestrings.<lang-code>.json, <lang-code> , veya degibi pt-BRzh-Hansgeçerli CultureInfo bir adla eşleşen olarak adlandır. Her dosya, iç içe alanlar için sınırlayıcı olarak kullanarak / anahtarın içindeki template.jsonöğenin yolu olduğu anahtar-değer çiftleri içerir.

Örneğin, aşağıdaki içeriğe sahip olan bir 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."
    }
  }
}

Brezilya Portekizcesi yerelleştirme dosyası şu templatestrings.pt-BR.json şekilde görünü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."
}

Şablon altyapısı, şablon bilgilerini yüklediğinde bu dosyaları ayrıştırıyor ve geçerli kullanıcı arabirimi kültürüne göre otomatik olarak yerelleştirilmiş değerler döndürüyor; kullanıcıdan ek adım gerekmez.

Yerelleştirme isteğe bağlıdır. Yerelleştirme dosyalarını eklemezseniz, şablon normal çalışır ve her zaman 'den template.jsondeğerleri görüntüler. Daha fazla bilgi için dotnet/templating wiki yerelleştirme sayfasına bakın.

Visual Studio entegrasyonu

Visual Studio Yeni proje oluştur iletişim kutusu, .NET proje şablonları için .NET şablon altyapısını kullanır. Ek yapılandırma olmadan Visual Studio'de çalışmak için dotnet new oluşturduğunuz şablonlar. Kullanıcı şablon paketinizi ile dotnet new installyüklediğinde Visual Studio bu şablonları otomatik olarak algılar ve iletişim kutusunda ortaya çıkar.

Project ve çözüm şablonları, Yerleşik SDK şablonlarının yanı sıra Yeni project oluştur iletişim kutusunda görüntülenir. Kullanıcılar şablonun dosyasındaki alandan ada, dile veya etiketlere classifications göre şablonları template.json bulabilir. Doğru sınıflandırmalar şablonunuzun doğru filtre kategorilerinde yüzey oluşturmasına yardımcı olur, bu nedenle bunları dikkatle seçin. İletişim kutusunda şablonunuza şık bir görünüm kazandırmak için klasöre .template.config bir icon.png ekleyin; Visual Studio şablonunuzun adının yanında görüntüler.

Öğe şablonları şu andaYeni ÖğeEkle> iletişim kutusunda görünmüyor. Kullanıcılar terminaldeki komutuyla dotnet new öğe şablonlarını kullanmaya devam edebilir.

Şablonunuzu henüz yüklememiş Visual Studio kullanıcılar tarafından bulunabilir hale getirmek için şablon paketinizi nuget.org yayımlayın. Yeni proje oluştur iletişim kutusu, şablon paketleri için nuget.org arama nuget.org çevrimiçi arama seçeneğinden daha fazla şablon yükle seçeneğini içerir. Kullanıcı paketinizi bu seçenek aracılığıyla yüklediğinde Visual Studio ile aynı yükleme mekanizmasını dotnet new installkullanır.

Şablon sıralama düzenini denetleme ve IDE'ye özgü ek seçenekleri yapılandırma gibi Visual Studio özgü tümleştirme hakkında daha ayrıntılı yönergeler için bkz. Sayed Hashimi'nin şablon örneği deposu.

İlgili içerik

  • Last updated on