Templat kustom untuk dotnet new

.NET SDK dilengkapi dengan banyak templat yang sudah diinstal dan siap digunakan. Perintahdotnet new ini bukan hanya cara menggunakan templat, tetapi juga cara menginstal dan menghapus instalasi templat. Anda dapat membuat templat kustom Anda sendiri untuk semua jenis proyek, seperti aplikasi, layanan, alat, atau pustaka kelas. Anda bahkan dapat membuat templat yang menghasilkan satu atau beberapa file independen, seperti file konfigurasi.

Anda dapat menginstal templat kustom dari paket NuGet pada umpan NuGet apa pun, dengan merujuk file NuGet .nupkg secara langsung, atau dengan menentukan direktori sistem file yang berisi templat. Mesin templat menawarkan fitur yang memungkinkan Anda mengganti nilai, menyertakan dan mengecualikan file, dan menjalankan operasi pemrosesan kustom saat templat Anda digunakan.

Mesin templat adalah sumber terbuka, dan repositori kode online berada di dotnet/templating di GitHub. Lebih banyak templat, termasuk templat dari pihak ketiga, dapat ditemukan menggunakan dotnet new search. Untuk informasi selengkapnya tentang membuat dan menggunakan templat kustom, lihat Cara membuat templat Anda sendiri untuk dotnet new dan Wiki repositori GitHub dotnet/templating.

Nota

Contoh templat tersedia di repositori GitHub dotnet/templating .

Untuk mengikuti panduan dan membuat templat, lihat tutorial Membuat templat kustom untuk dotnet baru .

Template bawaan .NET

Saat menginstal SDK .NET, Anda menerima lebih dari satu lusin template bawaan untuk membuat proyek dan file, termasuk aplikasi konsol, pustaka kelas, proyek uji unit, aplikasi ASP.NET Core (termasuk Proyek Angular dan React), dan file konfigurasi. Untuk mencantumkan templat bawaan, jalankan dotnet new list perintah :

dotnet new list

Konfigurasi

Templat terdiri dari bagian-bagian berikut:

Berkas dan folder sumber.
File konfigurasi (template.json).

File dan folder sumber

File dan folder sumber menyertakan berkas dan folder apa pun yang Anda ingin mesin template gunakan saat perintah dotnet new <TEMPLATE> dijalankan. Mesin templat dirancang untuk menggunakan proyek yang dapat dijalankan sebagai kode sumber untuk menghasilkan proyek. Ini memiliki beberapa manfaat:

Mesin templat tidak mengharuskan Anda untuk menyuntikkan token khusus ke dalam kode sumber proyek Anda.
File kode bukan file khusus atau dimodifikasi dengan cara apa pun untuk bekerja dengan mesin templat. Jadi, alat yang biasanya Anda gunakan saat bekerja dengan proyek juga berfungsi dengan konten templat.
Anda membangun, menjalankan, dan men-debug proyek templat seperti yang Anda lakukan untuk salah satu proyek Anda yang lain.
Anda dapat dengan cepat membuat templat dari proyek yang ada hanya dengan menambahkan file konfigurasi ./.template.config/template.json ke proyek.

File dan folder yang disimpan dalam templat tidak terbatas pada jenis proyek .NET formal. File dan folder sumber mungkin terdiri dari konten apa pun yang ingin Anda buat saat templat digunakan, bahkan jika mesin templat hanya menghasilkan satu file sebagai outputnya.

File yang dihasilkan oleh templat dapat dimodifikasi berdasarkan logika dan pengaturan yang telah Anda sediakan dalam file konfigurasi template.json . Pengguna dapat mengambil alih pengaturan ini dengan meneruskan opsi perintah ke dotnet new <TEMPLATE>. Contoh umum logika kustom adalah memberikan nama untuk kelas atau variabel dalam file kode yang disebarkan oleh templat.

template.json

File template.json ditempatkan di folder .template.config di direktori akar templat. File menyediakan informasi konfigurasi ke mesin templat. Konfigurasi minimum mengharuskan anggota yang diperlihatkan dalam tabel berikut, yang cukup untuk membuat templat fungsi.

Anggota	Tipe	Deskripsi
`$schema`	URI	Skema JSON untuk file template.json . Editor yang mendukung skema JSON mengaktifkan fitur pengeditan JSON saat skema ditentukan. Misalnya, Visual Studio Code mengharuskan anggota ini mengaktifkan IntelliSense. Gunakan nilai `http://json.schemastore.org/template`.
`author`	string	Penulis templat.
`classifications`	array(string)	Nol atau lebih karakteristik templat yang mungkin digunakan pengguna untuk menemukan templat saat mencarinya. Klasifikasi juga muncul di kolom Tag saat muncul dalam daftar templat yang dihasilkan dengan menggunakan `dotnet new list` perintah .
`identity`	string	Nama unik untuk templat ini.
`name`	string	Nama untuk templat yang akan dilihat pengguna.
`shortName`	string	Nama singkat default untuk memilih templat yang berlaku untuk lingkungan tempat nama templat ditentukan oleh pengguna, tidak dipilih melalui GUI. Misalnya, nama pendek berguna saat menggunakan templat dari command line dengan perintah CLI.
`sourceName`	string	Nama di pohon sumber untuk diganti dengan nama yang ditentukan pengguna. Mesin templat akan menemukan semua kemunculan `sourceName` yang disebutkan dalam file konfigurasi dan mengganti dengan nama file maupun isi file. Nilai yang digantikan dapat diberikan menggunakan opsi `-n` atau `--name` dalam menjalankan templat. Jika tidak ada nama yang ditentukan, direktori saat ini akan digunakan.
`preferNameDirectory`	Boolean	Menunjukkan apakah akan membuat direktori untuk templat jika nama ditentukan tetapi direktori output tidak diatur (alih-alih membuat konten langsung di direktori saat ini). Nilai defaultnya adalah false.

Skema lengkap untuk file template.json ditemukan di Penyimpanan Skema JSON. Untuk informasi selengkapnya tentang file template.json , lihat wiki templat dotnet. Untuk contoh dan informasi yang lebih mendalam tentang cara membuat templat Anda terlihat di Visual Studio, lihat sumber daya yang telah dibuat Sayed Hashimi.

Contoh

Misalnya, berikut adalah folder templat yang berisi dua file konten: console.cs dan readme.txt. Ada juga folder yang diperlukan bernama .template.config yang berisi file template.json .

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

File template.json terlihat seperti berikut ini:

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

Folder mytemplate adalah paket templat yang dapat diinstal. Setelah paket diinstal, shortName dapat digunakan dengan dotnet new perintah . Misalnya, dotnet new adatumconsole akan menghasilkan console.cs file dan readme.txt ke folder saat ini.

Lokalisasi templat

Templat .NET dapat dilokalkan. Jika templat dilokalkan untuk bahasa yang cocok dengan lokal saat ini, elemennya muncul dalam bahasa yang sama dengan CLI. Pelokalan bersifat opsional saat membuat templat baru.

Elemen yang dapat dilokalkan pada templat adalah:

Nama
Penulis
Deskripsi
Simbol
- Deskripsi
- Nama Tampilan
- Deskripsi dan Nama tampilan pilihan untuk parameter pilihan
Tindakan untuk Postingan
- Deskripsi
- Instruksi manual

File pelokalan memiliki format JSON, dan hanya satu file per budaya yang harus ada. Konvensi penamaan adalah: templatestrings.<lang code>.json, di mana lang code sesuai dengan salah satu opsi CultureInfo . Semua file pelokalan harus berada di dalam folder .template-config\localize.

JSON pelokalan terdiri dari pasangan nilai kunci:

Kuncinya adalah referensi ke elemen template.json yang akan dilokalkan. Jika elemen adalah anak, gunakan jalur lengkap dengan pemisah / .
Nilainya adalah string lokalisasi dari elemen yang ditentukan oleh kunci.

Untuk informasi selengkapnya tentang melokalisasi templat, lihat halaman pelokalan wiki templat dotnet.

Contoh

Misalnya, berikut adalah file template.json dengan beberapa bidang yang dapat dilokalkan:

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

Beberapa bidang akan dilokalisasi ke bahasa Portugis Brasil. Nama file akan templatestrings.pt-BR.json cocok dengan budaya, dan akan terlihat seperti:

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

Mengemas templat ke dalam paket NuGet (file nupkg)

Templat kustom dikemas dengan perintah paket dotnet dan file .csproj . Atau, NuGet dapat digunakan dengan perintah paket nuget bersama dengan file .nuspec . Namun, NuGet memerlukan .NET Framework di Windows dan Mono di Linux dan macOS.

File .csproj sedikit berbeda dari file .csproj proyek kode tradisional. Perhatikan pengaturan berikut:

Pengaturan <PackageType> ditambahkan dan diatur ke Template.
Pengaturan <PackageVersion> ditambahkan dan diatur ke nomor versi NuGet yang valid.
Pengaturan <PackageId> ditambahkan dan diatur ke pengidentifikasi unik. Pengidentifikasi ini digunakan untuk menghapus instalan paket templat dan digunakan oleh umpan NuGet untuk mendaftarkan paket templat Anda.
Pengaturan metadata generik harus diatur: <Title>, , <Authors><Description>, dan <PackageTags>.
Pengaturan <TargetFramework> harus diatur, meskipun biner yang dihasilkan oleh proses templat tidak digunakan. Dalam contoh di bawah ini diatur ke netstandard2.0.

Paket templat, dalam bentuk paket .nupkg NuGet, mengharuskan semua templat disimpan di folder konten dalam paket. Ada beberapa pengaturan lagi untuk ditambahkan ke file .csproj untuk memastikan bahwa .nupkg yang dihasilkan dapat diinstal sebagai paket templat:

Pengaturan <IncludeContentInPack> diatur ke true untuk menyertakan file apa pun yang ditetapkan proyek sebagai konten dalam paket NuGet.
Pengaturan <IncludeBuildOutput> diatur ke false untuk mengecualikan semua biner yang dihasilkan oleh kompiler dari paket NuGet.
Pengaturan <ContentTargetFolders> diatur ke content. Ini memastikan bahwa file yang diatur sebagai konten disimpan dalam folder konten dalam paket NuGet. Folder dalam paket NuGet ini diurai oleh sistem templat dotnet.

Cara mudah untuk mengecualikan semua file kode agar tidak dikompilasi oleh proyek templat Anda adalah dengan menggunakan <Compile Remove="**\*" /> item dalam file proyek Anda, di dalam <ItemGroup> elemen .

Cara mudah untuk menyusun paket templat Anda adalah dengan menempatkan semua templat di folder individual, lalu setiap folder templat di dalam folder templat yang terletak di direktori yang sama dengan file .csproj Anda. Dengan cara ini, Anda dapat menggunakan satu item proyek untuk menyertakan semua file dan folder dalam templat sebagai konten. Di dalam elemen <ItemGroup>, buat item <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />.

Berikut adalah contoh file .csproj yang mengikuti semua panduan ini. Ini mengemas folder anak templat ke folder paket konten dan mengecualikan file kode apa pun agar tidak dikompilasi.

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

Contoh berikut menunjukkan struktur file dan folder menggunakan .csproj untuk membuat paket templat. File MyDotnetTemplates.csproj dan folder templates kedua-duanya berada di direktori utama bernama project_folder. Folder templat berisi dua templat, mytemplate1 dan mytemplate2. Setiap templat memiliki file konten dan folder .template.config dengan file konfigurasi template.json .

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

Nota

Untuk memastikan bahwa paket templat muncul dalam dotnet new search hasil, atur jenis paket NuGet ke Template.

Menginstal paket templat

Gunakan perintah instal baru dotnet untuk menginstal paket templat.

Peringatan

Templat dapat menjalankan kode MSBuild saat dipicu, jangan menginstal atau menjalankan templat .NET yang tidak tepercaya.

Untuk menginstal paket templat dari paket NuGet yang disimpan di nuget.org

Gunakan pengidentifikasi paket NuGet untuk menginstal paket templat.

dotnet new install <NUGET_PACKAGE_ID>

Untuk menginstal paket templat dari sumber NuGet kustom

Berikan sumber NuGet kustom (misalnya, https://api.my-custom-nuget.com/v3/index.json).

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

Untuk menginstal paket templat dari file nupkg lokal

Berikan jalur ke file paket .nupkg NuGet.

dotnet new install <PATH_TO_NUPKG_FILE>

Untuk menginstal paket templat dari direktori sistem file

Templat dapat diinstal dari folder templat, seperti folder mytemplate1 dari contoh sebelumnya. Tentukan jalur folder folder .template.config . Jalur ke direktori templat tidak perlu mutlak.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Mendapatkan daftar paket templat yang diinstal

Perintah hapus instalan, tanpa parameter lain, mencantumkan semua paket templat yang diinstal dan templat yang disertakan.

dotnet new uninstall

Perintah tersebut mengembalikan sesuatu yang mirip dengan output berikut:

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

Tingkat item pertama setelah Currently installed items: adalah pengidentifikasi yang digunakan dalam menghapus instalasi paket templat. Dan dalam contoh sebelumnya, Microsoft.Azure.WebJobs.ProjectTemplates tercantum. Jika paket templat diinstal dengan menggunakan jalur sistem file, pengidentifikasi ini adalah jalur folder folder .template.config . Hanya paket templat yang diinstal melalui dotnet new install yang ditampilkan dalam daftar. Paket templat yang disertakan dalam .NET SDK tidak ditampilkan.

Meng-uninstall paket template

Gunakan perintah dotnet new uninstall untuk menghapus paket templat.

Jika paket diinstal oleh umpan NuGet atau oleh file .nupkg secara langsung, berikan pengidentifikasi.

dotnet new uninstall <NUGET_PACKAGE_ID>

Jika paket diinstal dengan menentukan jalur ke folder .template.config , gunakan jalur tersebut untuk menghapus instalan paket. Anda dapat melihat jalur absolut paket templat dalam output yang disediakan oleh dotnet new uninstall perintah . Untuk informasi selengkapnya, lihat bagian Dapatkan daftar templat yang terinstal .

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Membuat proyek menggunakan templat kustom

Setelah templat diinstal, gunakan templat dengan menjalankan dotnet new <TEMPLATE> perintah seperti yang Anda lakukan dengan templat lain yang telah diinstal sebelumnya. Anda juga dapat menentukan opsi untuk dotnet new perintah, termasuk opsi khusus templat yang Anda konfigurasikan di pengaturan templat. Berikan nama pendek templat langsung ke perintah:

dotnet new <TEMPLATE>

Lihat juga

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-06-17

Bagikan melalui

Templat kustom untuk dotnet new

Template bawaan .NET

Konfigurasi

File dan folder sumber

template.json

Contoh

Lokalisasi templat

Contoh

Mengemas templat ke dalam paket NuGet (file nupkg)

Menginstal paket templat

Untuk menginstal paket templat dari paket NuGet yang disimpan di nuget.org

Untuk menginstal paket templat dari sumber NuGet kustom

Untuk menginstal paket templat dari file nupkg lokal

Untuk menginstal paket templat dari direktori sistem file

Mendapatkan daftar paket templat yang diinstal

Meng-uninstall paket template

Membuat proyek menggunakan templat kustom

Lihat juga

Saran dan Komentar

Sumber Daya Tambahan: