Bagikan melalui

Tutorial: Membuat paket templat

Dengan .NET, Anda dapat membuat dan menyebarkan templat yang menghasilkan proyek, file, dan sumber daya. Tutorial ini adalah bagian ketiga dari seri yang mengajarkan Anda cara membuat, menginstal, dan menghapus instalasi templat untuk digunakan dengan dotnet new perintah .

Anda dapat melihat templat yang telah selesai di repositori GitHub Sampel .NET.

Di bagian seri ini, Anda mempelajari cara:

Prasyarat

  • .NET 9 atau versi yang lebih baru.

  • Selesaikan bagian 1 dan bagian 2 dari seri tutorial ini.

    Tutorial ini menggunakan dua templat yang dibuat di dua bagian pertama dari seri tutorial ini. Anda dapat menggunakan templat yang berbeda selama Anda menyalin templat, sebagai folder, ke folder working\content .

  • Buka terminal dan navigasikan ke folder kerja .

  • Instal template Microsoft.TemplateEngine.Authoring.Templates dari umpan paket NuGet.

    • Jalankan dotnet new install Microsoft.TemplateEngine.Authoring.Templates perintah dari terminal Anda.

Membuat proyek paket templat

Paket templat adalah satu atau beberapa templat yang dikemas ke dalam paket NuGet. Saat Anda menginstal atau menghapus instalasi paket templat, semua templat yang terkandung dalam paket ditambahkan atau dihapus, masing-masing.

Paket templat diwakili oleh file paket NuGet (.nupkg). Dan, seperti paket NuGet apa pun, Anda dapat mengunggah paket templat ke umpan NuGet. Perintah ini dotnet new install mendukung penginstalan paket templat dari umpan paket NuGet, file .nupkg , atau direktori dengan templat.

Biasanya Anda menggunakan file proyek C# untuk mengkompilasi kode dan menghasilkan biner. Namun, proyek juga dapat digunakan untuk menghasilkan paket templat. Dengan mengubah pengaturan .csproj, Anda dapat mencegahnya mengkompilasi kode apa pun dan sebaliknya menyertakan semua aset templat Anda sebagai sumber daya. Ketika proyek ini dibangun, proyek ini menghasilkan paket templat NuGet.

Paket yang akan Anda hasilkan mencakup item dan templat proyek yang sebelumnya dibuat.

Paket Microsoft.TemplateEngine.Authoring.Templates berisi templat yang berguna untuk penulisan templat. Untuk menginstal paket ini, nuget.org harus tersedia sebagai umpan NuGet di direktori kerja.

  1. Di folder kerja , jalankan perintah berikut untuk membuat paket templat:

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

    Parameter -n mengatur nama file proyek ke AdatumCorporation.Utility.Templates.csproj. Anda akan melihat hasil yang mirip dengan output berikut.

    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. Selanjutnya, buka file AdatumCorporation.Utility.Templates.csproj di editor kode dan isi sesuai dengan petunjuk dalam templat:

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

Deskripsi XML proyek

Pengaturan di bawah <PropertyGroup> dalam cuplikan XML dipecah menjadi dua grup.

Grup pertama menangani properti yang diperlukan untuk paket NuGet. Empat <Package*> pengaturan berkaitan dengan pengaturan properti paket NuGet untuk mengidentifikasi paket Anda di umpan NuGet. Nilai <PackageId> , saat digunakan oleh NuGet, juga digunakan untuk menghapus instalan paket templat. Pengaturan yang tersisa, seperti <Title> dan <PackageTags>, ada hubungannya dengan metadata yang ditampilkan pada umpan NuGet dan manajer paket .NET. Untuk informasi selengkapnya tentang pengaturan NuGet, lihat properti NuGet dan MSBuild.

Nota

Untuk memastikan bahwa paket templat muncul di hasil dotnet new search, <PackageType> harus disetel ke Template.

Di grup kedua, <TargetFramework> pengaturan memastikan bahwa MSBuild berjalan dengan benar saat Anda menjalankan perintah paket untuk mengkompilasi dan mengemas proyek. Grup ini juga menyertakan pengaturan yang ada hubungannya dengan mengonfigurasi proyek untuk menyertakan templat dalam folder yang sesuai dalam paket NuGet saat dibuat:

  • Pengaturan <NoWarn> ini menekan pesan peringatan yang tidak berlaku untuk proyek paket templat.

  • Pengaturan <NoDefaultExcludes> memastikan bahwa file dan folder yang dimulai dengan . (seperti .gitignore) adalah bagian dari templat. Perilaku default paket NuGet adalah mengabaikan file dan folder tersebut.

<ItemGroup> berisi dua item. Pertama, <Content> item menyertakan semua yang ada di folder templat sebagai konten. Ini juga diatur untuk mengecualikan folder bin atau folder obj apa pun untuk mencegah kode yang dikompilasi (jika Anda menguji dan mengkompilasi templat Anda) agar tidak disertakan. Kedua, item <Compile> mengecualikan semua file kode dari kompilasi di mana pun mereka berada. Pengaturan ini mencegah proyek yang digunakan untuk membuat paket templat agar tidak mencoba mengkompilasi kode dalam hierarki folder templat .

Petunjuk / Saran

Untuk informasi selengkapnya tentang pengaturan metadata NuGet, lihat Mengemas templat ke dalam paket NuGet (file nupkg).

File proyek yang dibuat mencakup penulisan templat tugas MSBuild dan pengaturan pelokalan.

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

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

Penting

Content folder berisi folder SampleTemplate. Hapus folder ini, karena ditambahkan ke templat penulisan untuk tujuan demonstrasi.

Tugas MSBuild ini menyediakan validasi templat dan pelokalan kemampuan templat . Pelokalan dinonaktifkan secara default. Untuk mengaktifkan pembuatan file pelokalan, atur LocalizeTemplates ke true.

Mengemas dan menginstal

Simpan file proyek. Sebelum membuat paket templat, verifikasi bahwa struktur folder Anda sudah benar. Templat apa pun yang ingin Anda kemas harus ditempatkan di folder konten , di foldernya sendiri. Struktur folder akan terlihat mirip dengan hierarki berikut:

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

Folder konten memiliki dua folder: ekstensi dan consoleasync.

Di terminal Anda, dari folder kerja , jalankan dotnet pack perintah . Perintah ini membangun proyek dan membuat paket NuGet di folder working\bin\Release , seperti yang ditunjukkan oleh output berikut:

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

Selanjutnya, instal paket templat dengan dotnet new install perintah . Pada Windows:

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

Di Linux atau macOS:

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

Anda akan melihat output yang mirip dengan hal berikut:

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

Jika Anda mengunggah paket NuGet ke umpan NuGet, Anda dapat menggunakan dotnet new install <PACKAGE_ID> perintah di mana <PACKAGE_ID> sama dengan <PackageId> pengaturan dari file .csproj .

Copot pemasangan paket templat

Tidak peduli bagaimana Anda menginstal paket templat, baik dengan file .nupkg secara langsung atau oleh umpan NuGet, menghapus paket templat adalah sama. Gunakan <PackageId> template yang ingin Anda hapus instalasinya. Anda bisa mendapatkan daftar templat yang diinstal dengan menjalankan dotnet new uninstall perintah .

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

Jalankan dotnet new uninstall AdatumCorporation.Utility.Templates untuk menghapus instalan paket templat. Perintah menghasilkan informasi tentang paket templat apa yang dihapus instalasinya.

Selamat! Anda telah menginstal dan menghapus paket templat.

Langkah selanjutnya

Untuk mempelajari selengkapnya tentang templat, yang sebagian besar sudah Anda pelajari, lihat artikel Templat kustom untuk dotnet baru .

  • Last updated on