Aracılığıyla paylaş

Eğitim: Şablon paketi oluşturun

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

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

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

Önkoşullar

  • .NET 9 veya sonraki bir sürüm.

  • Bu öğretici serisinin 1. bölümü ve 2. bölümü tamamlayın.

    Bu öğreticide, bu öğretici serisinin ilk iki bölümünde oluşturulan iki şablon kullanılır. Şablonu bir klasör olarak working\content klasörüne kopyaladığınız sürece farklı bir şablon kullanabilirsiniz.

  • Bir terminal açın ve çalışan klasörüne gidin.

  • NuGet paket akışından Microsoft.TemplateEngine.Authoring.Templates şablonunu yükleyin.

    • Terminalden dotnet new install Microsoft.TemplateEngine.Authoring.Templates komutunu çalıştırın.

Şablon paketi projesi oluşturma

Şablon paketi, NuGet paketine paketlenmiş bir veya daha fazla şablondur. Bir şablon paketini yüklediğinizde veya kaldırdığınızda, pakette yer alan tüm şablonlar sırasıyla eklenir veya kaldırılır.

Şablon paketleri bir NuGet paketi (.nupkg) dosyasıyla temsil edilir. Ayrıca, herhangi bir NuGet paketi gibi şablon paketini de bir NuGet akışına yükleyebilirsiniz. dotnet new install komutu bir NuGet paket akışından, .nupkg dosyasından veya şablon içeren bir dizinden şablon paketleri yüklemeyi destekler.

Normalde kod derlemek ve ikili dosya oluşturmak için bir C# proje dosyası kullanırsınız. Ancak, proje bir şablon paketi oluşturmak için de kullanılabilir. .csprojayarlarını değiştirerek, herhangi bir kod derlemesini engelleyebilir ve bunun yerine şablonlarınızın tüm varlıklarını kaynak olarak ekleyebilirsiniz. Bu proje oluşturulduğunda, bir şablon NuGet paketi üretir.

Oluşturacağınız paket, daha önce oluşturulan öğe ve proje şablonlarını içerir.

Microsoft.TemplateEngine.Authoring.Templates paketi şablon yazma için yararlı şablonlar içerir. Bu paketi yüklemek için nuget.org çalışma dizininde NuGet akışı olarak kullanılabilir olmalıdır.

  1. çalışan klasöründe aşağıdaki komutu çalıştırarak şablon paketini oluşturun:

    dotnet new templatepack -n "AdatumCorporation.Utility.Templates"

    parametresi proje dosya adını AdatumCorporation.Utility.Templates.csprojolarak ayarlar. Aşağıdaki çıkışa benzer bir sonuç görmeniz gerekir.

    The template "Template Package" was created successfully.

Processing post-creation actions...
Description: Manual actions required
Manual instructions: Open *.csproj in the editor and complete the package metadata configuration. Copy the templates to _content_ folder. Fill in README.md.

  2. Ardından, AdatumCorporation.Utility.Templates.csproj dosyasını bir kod düzenleyicisinde açın ve şablondaki ipuçlarına göre doldurun.

    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- The package metadata. Fill in the properties marked as TODO below -->
    <!-- Follow the instructions on https://learn.microsoft.com/nuget/create-packages/package-authoring-best-practices -->
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <PackageVersion>1.0</PackageVersion>
    <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>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>net8.0</TargetFramework>
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
    ... cut for brevity ...

Proje XML'sinin açıklaması

XML kod parçacığındaki <PropertyGroup> altındaki ayarlar iki gruba ayrılır.

İlk grup, NuGet paketi için gereken özelliklerle ilgilenir. Dört <Package*> ayarı, bir NuGet akışındaki paketinizi tanımlamak için NuGet paketi özellikleriyle ilişkilidir. <PackageId> değeri, NuGet tarafından kullanılırken şablon paketini kaldırmak için de kullanılır. <Title> ve <PackageTags>gibi diğer ayarların NuGet akışında ve .NET paket yöneticisinde görüntülenen meta verilerle ilgili olması gerekir. NuGet ayarları hakkında daha fazla bilgi için bkz. NuGet ve MSBuild özellikleri.

Not

Şablon paketinin dotnet new search sonuçlarda göründüğünden emin olmak için <PackageType>Templateolarak ayarlanmalıdır.

İkinci grupta <TargetFramework> ayarı, projeyi derlemek ve paketlemek için pack komutunu çalıştırdığınızda MSBuild'in düzgün çalışmasını sağlar. Grup, proje oluşturulduğunda NuGet paketindeki uygun klasöre şablonları dahil etmek için projeyi yapılandırmayla ilgili ayarları da içerir:

  • <NoWarn> ayarı, şablon paketi projelerine uygulanmayan bir uyarı iletisini gizler.

  • <NoDefaultExcludes> ayarı, . (.gitignoregibi) ile başlayan dosya ve klasörlerin şablonun bir parçası olmasını sağlar. NuGet paketlerinin varsayılan davranışı, bu dosya ve klasörleri yoksaymaktır.

<ItemGroup> iki öğe içerir. İlk olarak, <Content> öğesi içerik olarak şablonları klasöründeki her şeyi içerir. Ayrıca bin klasörü veya obj klasörünü dışlamak, böylece şablonlarınızı test edip derlediyseniz derlenmiş kodların dahil edilmesini önlemek üzere ayarlanmıştır. İkinci olarak, <Compile> öğesi nerede bulunurlarsa bulunsunlar tüm kod dosyalarının derlenmesinden hariç tutulur. Bu ayar, şablon paketini oluşturmak için kullanılan projenin şablonları klasör hiyerarşisindeki kodu derlemeye çalışmasını engeller.

Bahşiş

NuGet meta veri ayarları hakkında daha fazla bilgi için bkz. Şablonu NuGet paketine paketleme (nupkg dosyası).

Oluşturulan proje dosyası, MSBuild görevleri ve yerelleştirme ayarları yazan şablon içerir.

  <PropertyGroup>
    <LocalizeTemplates>false</LocalizeTemplates>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.TemplateEngine.Tasks" Version="*" PrivateAssets="all" IsImplicitlyDefined="true"/>
  </ItemGroup>

Önemli

içerik içerik klasörü bir SampleTemplate klasörü içerir. Bu klasörü sil, çünkü gösterim amacıyla yazma şablonuna eklendi.

Bu MSBuild görevleri, şablonların özelliklerinin şablon doğrulaması ve yerelleştirilmesini sağlar. Yerelleştirme varsayılan olarak devre dışıdır. Yerelleştirme dosyalarının oluşturulmasını etkinleştirmek için LocalizeTemplatestrueolarak ayarlayın.

Paketle ve yükle

Proje dosyasını kaydedin. Şablon paketini oluşturmadan önce klasör yapınızın doğru olduğunu doğrulayın. Paketlemek istediğiniz tüm şablonlar içerik klasörüne, kendi klasörüne yerleştirilmelidir. Klasör yapısı aşağıdaki hiyerarşiye benzer görünmelidir:

working
│   AdatumCorporation.Utility.Templates.csproj
└───content
    ├───extensions
    │   └───.template.config
    │           template.json
    └───consoleasync
        └───.template.config
                template.json

içerik klasörü iki klasöre sahiptir: uzantılar ve consoleasync.

Terminalinizde, çalışan klasöründen dotnet pack komutunu çalıştırın. Bu komut projeyi oluşturur ve aşağıdaki çıktıda gösterildiği gibi working\bin\Release klasöründe bir NuGet paketi oluşturur:

MSBuild version 17.8.0-preview-23367-03+0ff2a83e9 for .NET
  Determining projects to restore...
  Restored C:\code\working\AdatumCorporation.Utility.Templates.csproj (in 1.16 sec).

  AdatumCorporation.Utility.Templates -> C:\code\working\bin\Release\net8.0\AdatumCorporation.Utility.Templates.dll
  Successfully created package 'C:\code\working\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg'.

Ardından, dotnet new install komutuyla şablon paketini yükleyin. Windows'da:

dotnet new install .\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

Linux veya macOS'ta:

dotnet new install bin/Release/AdatumCorporation.Utility.Templates.1.0.0.nupkg

Aşağıdakine benzer bir çıkış görmeniz gerekir:

The following template packages will be installed:
   C:\code\working\AdatumCorporation.Utility.Templates\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

Success: AdatumCorporation.Utility.Templates::1.0.0 installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code
Example templates: async project                  consoleasync             [C#]              Common/Console/C#9

NuGet paketini bir NuGet akışına yüklediyseniz, dotnet new install <PACKAGE_ID><PACKAGE_ID> dosyasındaki <PackageId> ayarıyla aynı olduğu komutunu kullanabilirsiniz.

Şablon paketini kaldırma

Şablon paketini doğrudan .nupkg dosyasıyla veya NuGet akışıyla nasıl yüklemiş olursanız olun, şablon paketini kaldırmak aynıdır. Kaldırmak istediğiniz şablonun <PackageId> kullanın. dotnet new uninstall komutunu çalıştırarak yüklenen şablonların listesini alabilirsiniz.

C:\working> dotnet new uninstall
Currently installed items:
... cut to save space ...

  AdatumCorporation.Utility.Templates
    Details:
      NuGetPackageId: AdatumCorporation.Utility.Templates
      Version: 1.0.0
      Author: Me
    Templates:
      Example templates: async project (consoleasync) C#
      Example templates: string extensions (stringext) C#
    Uninstall Command:
      dotnet new uninstall AdatumCorporation.Utility.Templates

Şablon paketini kaldırmak için dotnet new uninstall AdatumCorporation.Utility.Templates çalıştırın. Komut, hangi şablon paketlerinin kaldırıldığı hakkında bilgi sağlar.

Tebrikler! Bir şablon paketi yüklediniz ve kaldırdınız.

Sonraki adımlar

Çoğunu zaten öğrendiğiniz şablonlar hakkında daha fazla bilgi edinmek için () dotnet new için özel şablonlar makalesine () bakabilirsiniz.

  • Last updated on