dotnet new için özel şablonlar

Makale
08/15/2023

.NET SDK'sı, zaten yüklü ve kullanıma hazır birçok şablonla birlikte gelir. Komut dotnet new yalnızca şablon kullanmanın yolu değildir, aynı zamanda şablonların nasıl yüklenip kaldırılma yöntemidir. Uygulama, hizmet, araç veya sınıf kitaplığı gibi herhangi bir proje türü için kendi özel şablonlarınızı oluşturabilirsiniz. Yapılandırma dosyası gibi bir veya daha fazla bağımsız dosyanın çıktılarını veren bir şablon bile oluşturabilirsiniz.

Doğrudan bir NuGet .nupkg dosyasına başvurarak veya şablonu içeren bir dosya sistemi dizini belirterek herhangi bir NuGet akışına nuGet paketinden özel şablonlar yükleyebilirsiniz. Şablon altyapısı, değerleri değiştirmenize, dosyaları dahil edip hariç tutmanıza ve şablonunuz kullanıldığında özel işlem işlemleri yürütmenize olanak sağlayan özellikler sunar.

Şablon altyapısı açık kaynak ve çevrimiçi kod deposu GitHub'da dotnet/templating konumundadır. üçüncü tarafların şablonları da dahil olmak üzere daha fazla şablon kullanılarak dotnet new searchbulunabilir. Özel şablonlar oluşturma ve kullanma hakkında daha fazla bilgi için bkz . Dotnet new ve dotnet/templating GitHub deposu Wiki'sine yönelik kendi şablonlarınızı oluşturma.

Not

Şablon örnekleri dotnet/templating GitHub deposunda bulunabilir.

İzlenecek yolu izlemek ve şablon oluşturmak için dotnet yeni öğreticisi için özel şablon oluşturma öğreticisine bakın.

.NET varsayılan şablonları

.NET SDK'sını yüklediğinizde konsol uygulamaları, sınıf kitaplıkları, birim testi projeleri, ASP.NET Core uygulamaları (Angular ve React projeleri dahil) ve yapılandırma dosyaları dahil olmak üzere proje ve dosya oluşturmak için bir düzineden fazla yerleşik şablon alırsınız. Yerleşik şablonları listelemek için komutunu dotnet new list çalıştırın:

dotnet new list

Yapılandırma

Şablon aşağıdaki bölümlerden oluşur:

Kaynak dosya ve klasörler.
Yapılandırma dosyası (template.json).

Kaynak dosya ve klasörler

Kaynak dosya ve klasörler, komut çalıştırıldığında dotnet new <TEMPLATE> şablon altyapısının kullanmasını istediğiniz dosyaları ve klasörleri içerir. Şablon altyapısı, proje üretmek için kaynak kodu olarak çalıştırılabilir projeleri kullanacak şekilde tasarlanmıştır. Bunun çeşitli avantajları vardır:

Şablon altyapısı, projenizin kaynak koduna özel belirteçler eklemenizi gerektirmez.
Kod dosyaları özel dosyalar değildir veya şablon altyapısıyla çalışmak için herhangi bir şekilde değiştirilmez. Bu nedenle, projelerle çalışırken normalde kullandığınız araçlar şablon içeriğiyle de çalışır.
Şablon projelerinizi diğer projelerinizde yaptığınız gibi derleyin, çalıştırın ve hatalarını ayıklayın.
Projeye bir ./.template.config/template.json yapılandırma dosyası ekleyerek var olan bir projeden hızla şablon oluşturabilirsiniz.

Şablonda depolanan dosya ve klasörler resmi .NET proje türleriyle sınırlı değildir. Kaynak dosya ve klasörler, şablon altyapısı çıktı olarak yalnızca bir dosya üretse bile şablon kullanıldığında oluşturmak istediğiniz içeriklerden oluşabilir.

Şablon tarafından oluşturulan dosyalar, template.json yapılandırma dosyasında sağladığınız mantık ve ayarlara göre değiştirilebilir. Kullanıcı, komut seçenekleri dotnet new <TEMPLATE> geçirerek bu ayarları geçersiz kılabilir. Özel mantığın yaygın bir örneği, şablon tarafından dağıtılan kod dosyasındaki bir sınıf veya değişken için bir ad sağlamaktır.

template.json

template.json dosyası, şablonun kök dizinindeki .template.config klasörüne yerleştirilir. Dosya, şablon altyapısına yapılandırma bilgileri sağlar. En düşük yapılandırma, işlevsel bir şablon oluşturmak için yeterli olan aşağıdaki tabloda gösterilen üyeleri gerektirir.

Üye	Type	Açıklama
`$schema`	URI	template.json dosyasının JSON şeması. JSON şemalarını destekleyen düzenleyiciler, şema belirtildiğinde JSON düzenleme özelliklerini etkinleştirir. Örneğin, Visual Studio Code bu üyenin IntelliSense'i etkinleştirmesini gerektirir. değerini `http://json.schemastore.org/template`kullanın.
`author`	Dize	Şablonun yazarı.
`classifications`	array(dize)	Bir kullanıcının şablonu ararken bulmak için kullanabileceği şablonun sıfır veya daha fazla özelliği. Sınıflandırmalar, komutu kullanılarak `dotnet new list` oluşturulan şablonların listesinde göründüğünde Etiketler sütununda da görünür.
`identity`	Dize	Bu şablon için benzersiz bir ad.
`name`	Dize	Kullanıcıların görmesi gereken şablonun adı.
`shortName`	Dize	Şablon adının kullanıcı tarafından belirtildiği ortamlara uygulanan şablonu seçmek için varsayılan bir kısaltma adıdır, GUI aracılığıyla seçilmez. Örneğin, cli komutlarıyla bir komut istemindeki şablonları kullanırken kısa ad kullanışlıdır.
`sourceName`	Dize	Yerine kullanıcının belirttiği kaynak ağaçtaki ad. Şablon altyapısı, yapılandırma dosyasında belirtilenlerin herhangi bir örneğini `sourceName` arar ve dosya adlarında ve dosya içeriğinde değiştirir. Değiştirilecek değer, şablon çalıştırılırken veya `--name` seçenekleri kullanılarak `-n` verilebilir. Ad belirtilmezse geçerli dizin kullanılır.
`preferNameDirectory`	Boolean	Ad belirtilirse ancak çıkış dizini ayarlanmadıysa (içeriği doğrudan geçerli dizinde oluşturmak yerine) şablon için dizin oluşturulup oluşturulmayacağını gösterir. Varsayılan değer olarak yanlış kullanılır.

template.json dosyasının tam şeması JSON Şema Deposu'nda bulunur. template.json dosyası hakkında daha fazla bilgi için dotnet templating wiki'sine bakın. Şablonlarınızı Visual Studio'da görünür hale getirme hakkında daha ayrıntılı örnekler ve bilgiler için Sayed Hashimi'nin oluşturduğu kaynaklara göz atın.

Örnek

Örneğin, iki içerik dosyası içeren bir şablon klasörü vardır: console.cs ve readme.txt. ayrıca template.json dosyasını içeren .template.config adlı gerekli klasör de vardır.

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

template.json dosyası aşağıdaki gibi görünür:

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

mytemplate klasörü yüklenebilir bir şablon paketidir. Paket yüklendikten sonra komutuyla shortNamedotnet new kullanılabilir. Örneğin, dotnet new adatumconsole ve readme.txt dosyalarının çıkışını console.cs geçerli klasöre yapar.

Şablon yerelleştirmesi

.NET şablonları yerelleştirilebilir. Bir şablon geçerli yerel ayarla eşleşen dil için yerelleştirilmişse, bu şablonun öğeleri CLI ile aynı dilde görünür. Yeni şablonlar oluşturulurken yerelleştirme isteğe bağlıdır.

Şablondaki yerelleştirilebilir öğeler şunlardır:

Veri Akışı Adı
Yazma
Açıklama
Sembol
- Açıklama
- Görünen Ad
- Seçim parametreleri için açıklamalar ve Seçeneklerin görünen adı
Eylemleri gönderme
- Açıklama
- El ile yönergeler

Yerelleştirme dosyalarının JSON biçimi vardır ve kültür başına yalnızca bir dosya olmalıdır. Adlandırma kuralı: templatestrings.<lang code>.json, burada lang code CultureInfo seçeneklerinden birine karşılık gelir. Tüm yerelleştirme dosyaları klasörün içinde .template-config\localize olmalıdır.

Yerelleştirme JSON'i anahtar değer çiftlerinden oluşur:

Anahtar, yerelleştirilecek öğesinin template.json başvurusudur. Öğesi bir alt öğeyse, sınırlayıcı ile / tam yolu kullanın.
değeri, anahtar tarafından verilen öğenin yerelleştirme dizesidir.

Şablonları yerelleştirme hakkında daha fazla bilgi için dotnet templating wiki'nin yerelleştirme sayfasına bakın.

Örnek

Örneğin, bazı yerelleştirilebilir alanlara sahip template.json dosyası aşağıda verilmişti:

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

Ayrıca bazı alanlar Brezilya Portekizcesi olarak yerelleştirilmelidir. Dosya adı kültürle eşleşecek templatestrings.pt-BR.json ve şöyle görünecektir:

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

Şablonu NuGet paketine paketleme (nupkg dosyası)

Dotnet pack komutu ve .csproj dosyasıyla birlikte özel bir şablon paketlenmiştir. Alternatif olarak, NuGet bir .nuspec dosyasıyla birlikte nuget pack komutuyla da kullanılabilir. Ancak NuGet, Windows üzerinde .NET Framework ve Linux ve macOS üzerinde Mono gerektirir.

.csproj dosyası, geleneksel bir kod projesi .csproj dosyasından biraz farklıdır. Aşağıdaki ayarlara dikkat edin:

Ayar <PackageType> eklenir ve olarak Templateayarlanır.
Ayar <PackageVersion> eklenir ve geçerli bir NuGet sürüm numarasına ayarlanır.
Ayar <PackageId> eklenir ve benzersiz bir tanımlayıcıya ayarlanır. Bu tanımlayıcı, şablon paketini kaldırmak için kullanılır ve NuGet akışları tarafından şablon paketinizi kaydetmek için kullanılır.
Genel meta veri ayarları ayarlanmalıdır: <Title>, <Authors>, <Description>ve <PackageTags>.
<TargetFramework> Şablon işlemi tarafından üretilen ikili dosya kullanılmasa bile ayar ayarlanmalıdır. Aşağıdaki örnekte olarak ayarlanmıştır netstandard2.0.

.nupkg NuGet paketi biçimindeki bir şablon paketi, tüm şablonların paket içindeki içerik klasöründe depolanmasını gerektirir. Oluşturulan .nupkg dosyasının şablon paketi olarak yüklenebilmesini sağlamak için .csproj dosyasına eklenecek birkaç ayar daha vardır:

Bu <IncludeContentInPack> ayar, projenin NuGet paketine içerik olarak ayarlandığı herhangi bir dosyayı içerecek şekilde ayarlanırtrue.
Ayar <IncludeBuildOutput> , derleyici tarafından oluşturulan tüm ikili dosyaları NuGet paketinden dışlamak için olarak ayarlanır false .
Ayarı <ContentTargetFolders> olarak contentayarlanır. Bu, içerik olarak ayarlanan dosyaların NuGet paketindeki içerik klasöründe depolanmasını sağlar. NuGet paketindeki bu klasör dotnet şablon sistemi tarafından ayrıştırılır.

Şablon projeniz tarafından derlenen tüm kod dosyalarını dışlamanın kolay bir yolu, öğeyi <Compile Remove="**\*" /> proje dosyanızda bir <ItemGroup> öğenin içinde kullanmaktır.

Şablon paketinizi yapılandırmanın kolay bir yolu, tüm şablonları tek tek klasörlere ve ardından her şablon klasörünü .csproj dosyanızla aynı dizinde bulunan bir templates klasörünün içine yerleştirmektir. Bu şekilde, şablonlardaki tüm dosya ve klasörleri içerik olarak eklemek için tek bir proje öğesi kullanabilirsiniz. Öğenin <ItemGroup> içinde bir <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> öğe oluşturun.

Bu yönergelerin tümüne uygun örnek bir .csproj dosyası aşağıda verilmiştir. Şablonlar alt klasörünü içerik paketi klasörüne paketler ve tüm kod dosyalarının derlenmesini dışlar.

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

Aşağıdaki örnekte şablon paketi oluşturmak için .csproj kullanmanın dosya ve klasör yapısı gösterilmektedir. MyDotnetTemplates.csproj dosyası ve templates klasörü, project_folder adlı dizinin kökünde bulunur. templates klasöründe mytemplate1 ve mytemplate2 adlı iki şablon bulunur. Her şablonun içerik dosyaları ve template.json yapılandırma dosyası içeren bir .template.config klasörü vardır.

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

Not

Şablon paketinin sonuç olarak dotnet new search göründüğünden emin olmak için NuGet paket türünü olarak Templateayarlayın.

Şablon paketi yükleme

Şablon paketi yüklemek için dotnet new install komutunu kullanın.

nuget.org'de depolanan bir NuGet paketinden şablon paketi yüklemek için

Şablon paketi yüklemek için NuGet paket tanımlayıcısını kullanın.

dotnet new install <NUGET_PACKAGE_ID>

Özel bir NuGet kaynağından şablon paketi yüklemek için

Özel bir NuGet kaynağı sağlayın (örneğin, https://api.my-custom-nuget.com/v3/index.json).

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

Yerel bir nupkg dosyasından şablon paketi yüklemek için

.nupkg NuGet paket dosyasının yolunu belirtin.

dotnet new install <PATH_TO_NUPKG_FILE>

Dosya sistemi dizininden şablon paketi yüklemek için

Şablonlar, önceki örnekteki mytemplate1 klasörü gibi bir şablon klasöründen yüklenebilir. .template.config klasörünün klasör yolunu belirtin. Şablon dizini yolunun mutlak olması gerekmez.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Yüklü şablon paketlerinin listesini alma

Kaldır komutu, başka parametre olmadan tüm yüklü şablon paketlerini ve dahil edilen şablonları listeler.

dotnet new uninstall

Bu komut aşağıdaki çıkışa benzer bir şey döndürür:

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

Sonraki öğelerin ilk düzeyi Currently installed items: , şablon paketini kaldırırken kullanılan tanımlayıcılardır. Önceki örnekte Microsoft.Azure.WebJobs.ProjectTemplates ise listelenmiştir. Şablon paketi bir dosya sistemi yolu kullanılarak yüklendiyse, bu tanımlayıcı .template.config klasörünün klasör yoludur. Listede yalnızca aracılığıyla dotnet new install yüklenen şablon paketleri gösterilir. .NET SDK'da yerleşik olarak bulunan şablon paketleri gösterilmez.

Şablon paketini kaldırma

Şablon paketini kaldırmak için dotnet new uninstall komutunu kullanın.

Paket bir NuGet akışı veya .nupkg dosyası tarafından doğrudan yüklendiyse tanımlayıcıyı sağlayın.

dotnet new uninstall <NUGET_PACKAGE_ID>

Paket .template.config klasörünün yolu belirtilerek yüklendiyse, paketi kaldırmak için bu yolu kullanın. Komut tarafından dotnet new uninstall sağlanan çıktıda şablon paketinin mutlak yolunu görebilirsiniz. Daha fazla bilgi için Yüklü şablonların listesini alma bölümüne bakın.

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Özel şablon kullanarak proje oluşturma

Bir şablon yüklendikten sonra, önceden yüklenmiş diğer tüm şablonlarda olduğu gibi komutunu yürüterek dotnet new <TEMPLATE> şablonu kullanın. Ayrıca, şablon ayarlarında yapılandırdığınız şablona dotnet new özgü seçenekler de dahil olmak üzere komutun seçeneklerini belirtebilirsiniz. Şablonun kısa adını doğrudan komutuna sağlayın:

dotnet new <TEMPLATE>

Aracılığıyla paylaş

dotnet new için özel şablonlar

.NET varsayılan şablonları

Yapılandırma

Kaynak dosya ve klasörler

template.json

Örnek

Şablon yerelleştirmesi

Örnek

Şablonu NuGet paketine paketleme (nupkg dosyası)

Şablon paketi yükleme

nuget.org'de depolanan bir NuGet paketinden şablon paketi yüklemek için

Özel bir NuGet kaynağından şablon paketi yüklemek için

Yerel bir nupkg dosyasından şablon paketi yüklemek için

Dosya sistemi dizininden şablon paketi yüklemek için

Yüklü şablon paketlerinin listesini alma

Şablon paketini kaldırma

Özel şablon kullanarak proje oluşturma

Ayrıca bkz.

Ek kaynaklar