templat .NET untuk penulis

Sebagai penulis templat, Anda membuat templat .NET—cetak biru yang menghasilkan proyek, file, atau sumber daya lain dari struktur yang telah ditentukan sebelumnya. Saat pengguna menjalankan dotnet new <shortName>, mesin templat .NET membaca templat dan menghasilkan output di direktori saat ini. dialog Buat proyek baru Visual Studio juga menggunakan mesin templat .NET untuk templat proyek .NET, sehingga templat yang Anda buat untuk pekerjaan CLI di Visual Studio juga.

SDK .NET dikirim dengan templat bawaan untuk titik awal umum seperti aplikasi konsol, pustaka kelas, dan proyek ASP.NET. Di luar templat bawaan tersebut, Anda dapat menulis templat Anda sendiri dan mendistribusikannya sebagai paket NuGet.

Artikel ini adalah referensi untuk penulis templat. Ini mencakup bagaimana templat disusun, dikonfigurasi, dan didistribusikan. Untuk instruksi langkah demi langkah untuk membuat dan mengemas templat, lihat bagian Konten terkait .

Jenis templat

Mesin templat .NET mendukung tiga jenis templat: templat item, templat proyek, dan templat solusi.

Templat item menghasilkan satu atau beberapa file, seperti file kode, file konfigurasi, atau sumber daya lainnya, tanpa menghasilkan seluruh proyek di sekitarnya. Misalnya, templat item mungkin menghasilkan file kelas yang menambahkan sekumpulan metode ekstensi, atau file konfigurasi JSON yang mengikuti tata letak standar yang digunakan tim Anda. Untuk mempelajari cara membuat templat item, lihat Tutorial: Membuat templat item.
templat Project menghasilkan struktur project lengkap. Templat proyek konsol .csproj bawaan, misalnya, menghasilkan file, Program.cs file, dan file lain yang membentuk proyek. Buat templat proyek saat Anda ingin memberi pengguna titik awal proyek penuh daripada file individual. Untuk mempelajari cara membuat templat proyek, lihat Tutorial: Membuat templat proyek.
Templat solusi menghasilkan solusi dengan satu atau beberapa proyek. Misalnya, templat solusi dapat membuat proyek API yang dipasangkan dengan proyek pengujian dalam satu langkah.

Saat membuat templat Anda sendiri, Anda mendeklarasikan jenisnya menggunakan tags.type bidang dalam template.json file konfigurasi. Nilai yang valid adalah "project", "item", dan "solution". Nilai-nilai ini memungkinkan pengguna memfilter hasil saat mereka mencari templat dengan dotnet new search atau dotnet new list.

Tip

Project dan templat solusi muncul di dialog Visual Studio Buat project baru, tetapi templat item tidak muncul dalam dialog Tambahkan>Item Baru. Pengguna dapat mengakses templat item dari dotnet new CLI.

Struktur templat

Templat adalah folder pada disk yang berisi dua hal: file sumber templat dan subfolder khusus .template.config . Saat pengguna menjalankan dotnet new <shortName>, mesin templat menyalin file sumber ke lokasi output dan menerapkan konfigurasi apa pun yang telah Anda tentukan untuk templat.

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

File sumber dapat berupa semua jenis file. Mesin templat tidak mengharuskan Anda untuk menyuntikkan token atau penanda khusus ke dalam kode sumber. Ini menggunakan file as-is, yang berarti Anda dapat membangun, menjalankan, dan men-debug proyek sumber templat persis seperti proyek .NET normal. Untuk mengubah proyek yang ada menjadi templat, tambahkan .template.config/template.json file ke akar proyek.

Anda dapat secara opsional menyuntikkan token substitusi yang terkait dengan parameter templat (simbol) langsung ke file sumber templat dan nama file. Jika token bukan kode sumber yang valid, Anda tidak dapat membuat, menjalankan, atau men-debug proyek sumber sebelum menyebarkannya sebagai templat. Token tidak memengaruhi proyek yang dibuat pengguna dari templat yang disebarkan karena mesin templat menggantikannya selama pembuatan proyek.

Satu-satunya file yang diperlukan di dalamnya .template.config adalah template.json. File itu memberi tahu mesin templat semua yang dibutuhkan: nama templat, nama pendek, penulis, klasifikasi, dan parameter apa pun yang dapat diteruskan pengguna saat mereka membuat dari templat. Anda juga dapat menempatkan icon.png file di .template.config folder . Terminal tidak menampilkan ikon, tetapi Visual Studio memperlihatkan ikon di samping templat dalam dialog Buat proyek baru. 128×128 PNG bekerja dengan baik.

File template.json

File template.json adalah satu-satunya bagian konfigurasi yang diperlukan dalam templat. Ini tinggal di .template.config dalam folder dan memberi tahu mesin templat cara menyajikan dan memproses templat Anda. Tabel berikut ini menjelaskan bidang umum yang diperlukan dan opsional:

Field	Tipe	Wajib	Description
`$schema`	URI	No	Skema JSON untuk `template.json`. Atur ke `https://json.schemastore.org/template` untuk mengaktifkan IntelliSense di editor seperti Visual Studio Code.
`author`	string	No	Penulis templat.
`classifications`	array(string)	No	Tag yang dapat digunakan pengguna untuk menemukan templat dengan `dotnet new search` atau `dotnet new list`. Nilai-nilai ini muncul di kolom Tag daftar templat.
`description`	string	No	Deskripsi tentang apa yang dibuat templat.
`identity`	string	Ya	Pengidentifikasi unik untuk templat.
`name`	string	Ya	Nama tampilan templat yang diperlihatkan kepada pengguna.
`shortName`	string	Ya	Pengguna nama pendek meneruskan ke `dotnet new` untuk membuat dari templat, seperti `console` atau `classlib`.
`sourceName`	string	No	String dalam file sumber dan nama file yang diganti mesin templat dengan nama yang disediakan pengguna melalui `-n` atau `--name`. Jika pengguna tidak memberikan nama, mesin menggunakan nama direktori saat ini.
`preferNameDirectory`	Boolean	No	Ketika `true` dan pengguna memberikan nama tetapi tidak ada direktori output, mesin templat membuat direktori baru dengan nama tersebut alih-alih menulis file ke direktori saat ini. Defaultnya adalah `false`.
`tags`	objek	No	Metadata yang mengidentifikasi properti seperti bahasa dan jenis templat. Gunakan `tags.language` untuk bahasa dan `tags.type` untuk `project`, `item`, atau `solution`.

Dua bidang layak mendapat perhatian ekstra. Bidang sourceName adalah bagaimana templat menangani penamaan: atur ke string yang muncul di nama file dan kode sumber Anda (seperti MyTemplate), dan mesin templat mengganti setiap kemunculan dengan nama apa pun yang dilewatkan pengguna saat membuat templat. Bidang classifications mengontrol kemampuan penemuan; pilih tag yang secara akurat menjelaskan tujuan templat Anda sehingga pengguna dapat menemukannya saat mencari.

Berikut adalah minimal template.json untuk templat konsol:

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

Skema lengkap tersedia di Penyimpanan Skema JSON. Untuk opsi konfigurasi tingkat lanjut seperti penyertaan file kondisional, tindakan pasca-pembuatan, dan templat multi-proyek, lihat wiki GitHub dotnet/templat.

Parameter templat (simbol)

Bagian symbols dalam menentukan parameter yang dapat diteruskan template.json pengguna saat membuat dari templat Anda. Setiap simbol menjadi opsi CLI pada dotnet new <shortName>, sehingga simbol bernama ClassName menjadi --ClassName (atau -C jika Anda menentukan nama pendek).

Setiap entri simbol mendukung pengaturan umum berikut:

Setting	Description
`type`	Harus `"parameter"` untuk parameter yang menghadap pengguna.
`description`	Diperlihatkan dalam output bantuan templat saat pengguna menjalankan `dotnet new <shortName> -?`.
`datatype`	Jenis data yang diharapkan, seperti `"text"`, , `"bool"`atau `"choice"`.
`replaces`	String dalam konten file sumber Anda yang digantikan mesin templat dengan nilai parameter.
`fileRename`	String dalam nama file sumber Anda yang diganti mesin templat dengan nilai parameter.
`defaultValue`	Nilai yang digunakan saat pengguna tidak menyediakan parameter .

Pengaturan replaces dan fileRename adalah bagaimana simbol mendorong substitusi. Ketika pengguna memberikan nilai, mesin templat menggantikan setiap kemunculan replaces string di dalam konten file dan setiap kemunculan fileRename string dalam nama file. Jika pengguna tidak memberikan nilai, defaultValue pengguna akan digunakan sebagai gantinya.

Misalnya, simbol berikut memungkinkan pengguna mengatur nama kelas saat mereka membuat dari templat. File diganti namanya dan kelas di dalamnya diperbarui agar cocok:

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

Dengan simbol ini ditentukan, pengguna dapat menjalankan dotnet new <shortName> --ClassName MyHelpers untuk menghasilkan file bernama MyHelpers.cs yang berisi kelas bernama MyHelpers. Tanpa bendera, file dan kelas menyimpan nama StringExtensionsdefault .

Untuk memverifikasi parameter yang diekspos templat Anda, teruskan -? ke nama pendeknya setelah Anda menginstalnya:

dotnet new <shortName> -?

Paket templat

Paket templat adalah file NuGet (.nupkg) yang menggabungkan satu atau beberapa templat Anda bersama-sama. Saat pengguna menginstal paket templat Anda, mesin templat .NET mendaftarkan setiap templat di dalamnya sekaligus. Paket adalah cara standar untuk mendistribusikan templat. Terbitkan satu paket untuk NuGet.org atau umpan NuGet privat, atau bagikan file lokal .nupkg , dan pengguna mendapatkan seluruh koleksi dengan satu perintah.

Untuk membuat paket templat, gunakan file proyek C# (.csproj) yang dikonfigurasi untuk bertindak sebagai proyek pengemasan daripada proyek kompilasi. Pengaturan kunci yang membuat ini berfungsi adalah:

Setting	Nilai	Kegunaan
`PackageType`	`Template`	Menandai paket sebagai paket templat sehingga muncul dalam `dotnet new search` hasil.
`IncludeContentInPack`	`true`	Menyertakan file konten dalam paket NuGet.
`IncludeBuildOutput`	`false`	Mencegah biner yang dikompilasi ditambahkan ke paket.
`ContentTargetFolders`	`content`	Tempatkan folder templat Anda di `content` dalam folder paket NuGet, yang merupakan tempat mesin templat mengharapkan untuk menemukannya.

templatepack Templat proyek menyediakan cara termudah untuk membuat proyek pengemasan:

Pasang Microsoft. Paket NuGet TemplateEngine.Authoring.Templates:

dotnet new install Microsoft.TemplateEngine.Authoring.Templates

Buat proyek pengemasan:

dotnet new templatepack -n <PackageName>

Proyek yang dihasilkan mencakup pengaturan yang content benar.csproj, folder untuk templat Anda, dan tugas MSBuild untuk validasi templat dan pelokalan opsional.

Untuk panduan lengkap membuat, mengemas, dan menerbitkan paket templat, lihat Tutorial: Membuat paket templat.

Menguji templat Anda secara lokal

Selama pengembangan templat, instal templat Anda langsung dari foldernya untuk mengujinya tanpa membangun paket terlebih dahulu. Teruskan jalur ke direktori yang berisi .template.config folder:

dotnet new install ./mytemplate/

Untuk melihat semua paket templat yang diinstal dan perintah yang tepat untuk menghapus instalan masing-masing paket, jalankan dotnet new uninstall tanpa argumen:

dotnet new uninstall

Untuk menghapus instalasi templat yang diinstal dari direktori, lewati jalur direktori yang sama dengan yang Anda gunakan untuk menginstalnya:

dotnet new uninstall ./mytemplate/

Setelah Anda siap untuk berbagi templat Anda, kemas sebagai paket NuGet (lihat Paket templat) dan distribusikan. Pengguna menginstal templat yang diterbitkan dengan dotnet new install dan salah satu argumen sumber berikut:

ID paket NuGet, yang menginstal versi stabil terbaru dari sumber NuGet yang dikonfigurasi untuk direktori saat ini:
```
dotnet new install AdatumCorporation.ConsoleTemplate.CSharp
```
ID paket NuGet dengan URL umpan kustom. Opsi ini --nuget-source menggunakan umpan yang ditentukan, selain sumber NuGet yang dikonfigurasi, hanya untuk penginstalan tersebut:
```
dotnet new install AdatumCorporation.ConsoleTemplate.CSharp --nuget-source https://mynugetfeed.example.com/v3/index.json
```

Jalur ke file lokal .nupkg :

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

Warning

Templat dapat menjalankan tugas MSBuild dan kode arbitrer selama pembuatan proyek. Hanya instal templat dari sumber yang Anda percayai.

Untuk menghapus instalasi paket yang diinstal dari sumber NuGet atau file lokal .nupkg , gunakan ID paket NuGet:

dotnet new uninstall AdatumCorporation.ConsoleTemplate.CSharp

Templat SDK bawaan tidak muncul di daftar hapus instalan dan tidak dapat dihapus dengan dotnet new uninstall.

Lokalisasi templat

Mesin templat .NET mendukung pelokalan opsional metadata templat. Saat Anda menyediakan file pelokalan, host seperti dotnet new dan dialog Visual Studio New Project menampilkan nama, deskripsi, dan informasi simbol templat dalam bahasa pengguna alih-alih bahasa asli yang ditulis.

Bidang templat berikut mendukung pelokalan:

name
author
description
Simbol description dan displayName
Deskripsi dan nama tampilan untuk setiap pilihan dalam parameter pilihan
Pasca tindakan description dan manualInstructions

Untuk menambahkan pelokalan, buat localize subfolder di dalamnya .template.config dan tambahkan satu file JSON per bahasa. Beri nama setiap file templatestrings.<lang-code>.json, di mana <lang-code> cocok dengan nama yang valid CultureInfo , seperti pt-BR, zh-Hans, atau de. Setiap file berisi pasangan kunci-nilai di mana kunci adalah jalur ke elemen di template.json, menggunakan / sebagai pemisah untuk bidang berlapis.

Misalnya, diberikan template.json dengan konten berikut:

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

File pelokalan Portugis Brasil bernama templatestrings.pt-BR.json akan terlihat seperti ini:

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

Mesin templat mengurai file-file ini saat memuat informasi templat, dan mengembalikan nilai yang dilokalkan secara otomatis berdasarkan budaya UI saat ini—tidak ada langkah tambahan yang diperlukan dari pengguna.

Pelokalan bersifat opsional. Jika Anda tidak menyertakan file pelokalan, templat berfungsi secara normal dan selalu menampilkan nilai dari template.json. Untuk informasi selengkapnya, lihat halaman pelokalan wiki dotnet/templat.

Integrasi Visual Studio

dialog Buat proyek baru Visual Studio menggunakan mesin templat .NET untuk templat proyek .NET. Templat yang Anda buat untuk dotnet new bekerja di Visual Studio juga, tanpa konfigurasi tambahan. Saat pengguna menginstal paket templat Anda dengan dotnet new install, Visual Studio secara otomatis mendeteksi dan menampilkan templat tersebut dalam dialog.

Project dan templat solusi muncul dalam dialog Buat project baru bersama templat SDK bawaan. Pengguna dapat menemukan templat berdasarkan nama, bahasa, atau tag dari classifications bidang dalam file templat template.json . Klasifikasi yang akurat membantu permukaan templat Anda dalam kategori filter yang tepat, jadi pilih dengan hati-hati. Untuk memberi templat Anda tampilan yang dipoles dalam dialog, tambahkan icon.png ke .template.config folder — Visual Studio menampilkannya di samping nama templat Anda.

Templat item saat ini tidak muncul dalam dialog Tambahkan>Item Baru . Pengguna masih dapat menggunakan templat item dengan dotnet new perintah di terminal.

Untuk membuat templat Anda dapat ditemukan Visual Studio pengguna yang belum menginstalnya, terbitkan paket templat Anda ke nuget.org. Dialog Buat proyek baru menyertakan opsi Instal lebih banyak templat dari pencarian online yang mencari nuget.org untuk paket templat. Saat pengguna menginstal paket Anda melalui opsi tersebut, Visual Studio menggunakan mekanisme penginstalan yang sama dengan dotnet new install.

Untuk panduan yang lebih mendalam tentang integrasi khusus Visual Studio—seperti mengontrol urutan pengurutan templat dan mengonfigurasi opsi khusus IDE tambahan—lihat Repositori sampel templat Sayed Hashimi.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-08-13