Öğretici: Öğe şablonu oluşturma

  • Makale

.NET ile proje, dosya ve kaynak oluşturan şablonlar oluşturabilir ve dağıtabilirsiniz. Bu öğretici, komutuyla kullanmak üzere şablonları oluşturmayı, yüklemeyi ve kaldırmayı öğreten bir serinin dotnet new birinci bölümüdür.

Tamamlanmış şablonu .NET Örnekleri GitHub deposunda görüntüleyebilirsiniz.

Bahşiş

Öğe şablonları Visual Studio'nun Yeni Öğe Ekle>iletişim kutusunda gösterilmez.

Serinin bu bölümünde şunları nasıl yapacağınızı öğreneceksiniz:

  • Öğe şablonu için bir sınıf oluşturun.
  • Şablon yapılandırma klasörünü ve dosyasını oluşturun.
  • Dosya yolundan şablon yükleyin.
  • Öğe şablonunu test edin.
  • Öğe şablonunu kaldırın.

Ön koşullar

  • .NET SDK 7.0.100 veya sonraki bir sürüm.

    Başvuru makalesinde şablonlar ve bunların nasıl bir araya getirdikleri hakkında temel bilgiler açıklanır. Bu bilgilerin bazıları burada tekrarlanır.

  • Bir terminal açın ve şablonları depolayıp test ettiğiniz bir klasöre gidin.

Önemli

Bu makale .NET 7 için yazılmıştır. Ancak, .NET 6 ve önceki sürümler için de geçerlidir ve tek bir fark vardır: dotnet new Söz dizimi farklıdır. , , ve alt komutları sırasıyla , --search, --installve --uninstall seçenekleri olmalıdır--list.uninstallinstallsearchlist

Örneğin, dotnet new install .NET 7'deki komut .NET 6'da olur dotnet new --install . Tüm seçeneklerin dotnet new --help ve alt komutların listesini görmek için komutunu kullanın.

Gerekli klasörleri oluşturma

Bu seri, şablon kaynağınızın bulunduğu bir "çalışma klasörü" ve şablonlarınızı test etmek için kullanılan bir "test klasörü" kullanır. Çalışma klasörü ve test klasörü aynı üst klasör altında olmalıdır.

İlk olarak, üst klasörü oluşturun; ad önemli değildir. Ardından working and test adlı iki alt klasör oluşturun. Çalışma klasörünün içinde content adlı bir alt klasör oluşturun.

Klasör yapısı aşağıdaki gibi görünmelidir.

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

Öğe şablonu oluşturma

Öğe şablonu, bir veya daha fazla dosya içeren belirli bir şablon türüdür. Bu tür şablonlar, zaten bir projeniz olduğunda ve yapılandırma dosyası veya kod dosyası gibi başka bir dosya oluşturmak istediğinizde kullanışlıdır. Bu örnekte, dize türüne bir uzantı yöntemi ekleyen bir sınıf oluşturacaksınız.

Terminalinizde working\content klasörüne gidin ve extensions adlı yeni bir alt klasör oluşturun.

working
└───content
    └───extensions

extensions klasörüne gidin ve StringExtensions.cs adlı yeni bir dosya oluşturun. Dosyayı bir metin düzenleyicisinde açın. Bu sınıf, bir dizenin içeriğini tersine çeviren adlı Reverse bir uzantı yöntemi sağlar. Aşağıdaki kodu yapıştırın ve dosyayı kaydedin:

namespace System;

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

Şablonun içeriği bittiğine göre, sonraki adım şablon yapılandırmasını oluşturmaktır.

Şablon yapılandırmasını oluşturma

Öğreticinin bu bölümünde şablon klasörünüz working\content\extensions konumundadır.

Şablon klasörünüzün kökünde özel bir klasör ve yapılandırma dosyası bulunduğundan şablonlar .NET tarafından tanınır.

İlk olarak, .template.config adlı yeni bir alt klasör oluşturun ve girin. Ardından template.json adlı yeni bir dosya oluşturun. Klasör yapınız şu şekilde görünmelidir:

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

Template.json dosyasını sık kullandığınız metin düzenleyiciyle açın ve aşağıdaki JSON kodunu yapıştırın ve kaydedin.

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

Bu yapılandırma dosyası, şablonunuzun tüm ayarlarını içerir. ve shortNamegibi name temel ayarları görebilirsiniz, ancak olarak ayarlanmış itembir tags/type değer de vardır. Bu, şablonunuzu "öğe" şablonu olarak kategorilere ayırır. Oluşturduğunuz şablon türüyle ilgili bir kısıtlama yoktur. item ve project değerleri, kullanıcıların aradıkları şablon türünü kolayca filtreleyebilmeleri için .NET tarafından önerilen yaygın adlardır.

öğe, classifications çalıştırdığınızda dotnet new ve şablonların listesini aldığınızda gördüğünüz etiketler sütununu temsil eder. Kullanıcılar sınıflandırma etiketlerine göre de arama yapabilir. template.json dosyasındaki özelliği etiketler listesiyle classifications karıştırmayıntags. Bunlar ne yazık ki aynı adlı iki farklı kavramdır. template.json dosyasının tam şeması JSON Şema Deposu'nda bulunur ve template.json başvurusu bölümünde açıklanmıştır. template.json dosyası hakkında daha fazla bilgi için dotnet templating wiki'sine bakın.

symbols Bu JSON nesnesinin bölümü, şablonda kullanılabilecek parametreleri tanımlamak için kullanılır. Bu durumda, tanımlanmış bir parametre vardır: ClassName. Tanımlanan parametre aşağıdaki ayarları içerir:

  • type - Bu zorunlu bir ayardır ve olarak ayarlanmalıdır parameter.
  • description - Şablon yardımında yazdırılan parametrenin açıklaması.
  • datatype - Parametre kullanıldığında parametre değerinin veri türü.
  • replaces - Tüm şablon dosyalarında parametresinin değeriyle değiştirilmesi gereken bir metin değeri belirtir.
  • fileRename - benzer şekilde replaces, tüm şablon dosyalarının adlarında parametresinin değeriyle değiştirilen bir metin değeri belirtir.
  • defaultValue - Parametre kullanıcı tarafından belirtilmediğinde bu parametrenin varsayılan değeri.

Şablon kullanıldığında, kullanıcı parametresi için ClassName bir değer sağlayabilir ve bu değer tüm oluşumlarının StringExtensionsyerini alır. Bir değer sağlanmazsa, defaultValue kullanılır. Bu şablon için iki yineleme StringExtensionsvardır: StringExtensions.cs dosyası ve StringExtensions sınıfı. defaultValue parametresi olduğundanStringExtensions, şablon kullanılırken parametre belirtilmezse dosya adı ve sınıf adı değişmeden kalır. Örneğin dotnet new stringext -ClassName MyExtsbir değer belirtildiğinde, dosya MyExts.cs olarak yeniden adlandırılır ve sınıf MyExts olarak yeniden adlandırılır.

Bir şablon için hangi parametrelerin kullanılabilir olduğunu görmek için parametresini -? şablon adıyla kullanın:

dotnet new stringext -?

Bu, aşağıdaki çıkışı üretir:

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

Artık geçerli bir .template.config/template.json dosyanız olduğuna göre, şablonunuz yüklenmeye hazırdır. Terminalinizde uzantılar klasörüne gidin ve geçerli klasörde bulunan şablonu yüklemek için aşağıdaki komutu çalıştırın:

  • Windows'da: dotnet new install .\
  • Linux veya macOS'ta: dotnet new install ./

Bu komut, sizinkileri de içermesi gereken yüklü şablonların listesini oluşturur.

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

Öğe şablonunu test edin

Artık yüklü bir öğe şablonunuz olduğuna göre, bunu test edin.

  1. Test klasörüne gidin.

  2. komutuyla dotnet run kolayca test edebilirsiniz çalışan bir proje oluşturan ile dotnet new consoleyeni bir konsol uygulaması oluşturun.

    dotnet new console

    Aşağıdakine benzer bir çıkış elde edersiniz.

    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. Aşağıdaki komutu kullanarak projeyi çalıştırın.

    dotnet run

    Aşağıdaki çıkışı alırsınız.

    Hello, World!

  4. Komutunu çalıştırarak dotnet new stringextşablondan StringExtensions.cs dosyasını oluşturun.

    dotnet new stringext

    Aşağıdaki çıkışı alırsınız.

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

  5. Dizeyi şablon tarafından sağlanan uzantı yöntemiyle ters çevirmek "Hello, World!" için Program.cs dosyasındaki kodu değiştirin.

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

    Programı yeniden çalıştırın ve sonucun ters çevrildiğini görün.

    dotnet run

    Aşağıdaki çıkışı alırsınız.

    !dlroW ,olleH

Tebrikler! .NET ile bir öğe şablonu oluşturdunuz ve dağıttınız. Bu öğretici serisinin sonraki bölümüne hazırlanırken, oluşturduğunuz şablonu kaldırın. Test klasöründeki tüm dosya ve klasörleri de sildiğinizden emin olun. Böylece, bu öğretici serisinin bir sonraki bölümüne hazır bir temiz duruma geri dönersiniz.

Şablonu kaldırma

Terminalinizde uzantılar klasörüne gidin ve geçerli klasörde bulunan şablonları kaldırmak için aşağıdaki komutu çalıştırın:

  • Windows'da: dotnet new uninstall .\
  • Linux veya macOS'ta: dotnet new uninstall ./

Bu komut, kaldırılan şablonların bir listesini oluşturur ve bu liste sizinkileri de içerir.

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

İstediğiniz zaman, her şablon paketi için kaldırma komutunun da dahil olduğu yüklü şablon paketlerinin listesini görmek için kullanabilirsiniz dotnet new uninstall .

Sonraki adımlar

Bu öğreticide bir öğe şablonu oluşturdunuz. Proje şablonu oluşturmayı öğrenmek için bu öğretici serisine devam edin.

Proje şablonu oluşturma