Bagikan melalui

Template kustom untuk dotnet baru

  • Artikel

SDK .NET dilengkapi dengan banyak template yang sudah terinstal dan siap untuk Anda gunakan. Perintah dotnet new bukan hanya cara menggunakan template, tetapi juga cara menginstal dan mencopot pemasangan template. Anda dapat membuat template kustom sendiri untuk semua jenis proyek, seperti aplikasi, layanan, alat, atau pustaka kelas. Anda bahkan dapat membuat template yang menghasilkan satu atau beberapa file independen, seperti file konfigurasi.

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

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

Catatan

Contoh templat tersedia di repositori GitHub dotnet/templating .

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

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

Template terdiri dari bagian-bagian berikut:

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

File dan folder sumber

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

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

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

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

template.json

File template.json ditempatkan dalam folder .template.config di direktori akar kerangka. File memberikan informasi konfigurasi ke mesin template. Konfigurasi minimum memerlukan anggota yang ditunjukkan pada tabel berikut, yang cukup untuk membuat template fungsional.

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 untuk mengaktifkan IntelliSense. Gunakan nilai http://json.schemastore.org/template.
author string Pembuat template.
classifications array(string) Nol atau lebih karakteristik template yang mungkin digunakan pengguna untuk menemukan template 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 template ini.
name string Nama untuk template yang harus dilihat pengguna.
shortName string Nama singkatan default untuk memilih template yang berlaku untuk lingkungan di mana nama template ditentukan oleh pengguna, tidak dipilih melalui GUI. Misalnya, nama pendek berguna saat menggunakan template dari perintah dengan perintah CLI.
sourceName string Nama di pohon sumber yang akan diganti dengan nama yang ditentukan pengguna. Mesin template akan mencari kemunculan sourceName yang disebutkan dalam file konfigurasi dan menggantinya dengan nama file dan konten file. Nilai yang akan diganti dapat diberikan menggunakan opsi -n atau --name saat menjalankan template. Jika tidak ada nama yang ditentukan, direktori saat ini 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 dapat ditemukan di JSON Schema Store. Untuk informasi selengkapnya tentang file template.json, lihat wiki templating dotnet. Untuk contoh dan informasi yang lebih mendalam tentang cara membuat template Anda terlihat di Visual Studio, lihat sumber daya yang 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:

{
  "$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 template yang dapat diinstal. Setelah paket diinstal, shortName dapat digunakan dengan perintah dotnet new. Misalnya, dotnet new adatumconsole akan menampilkan file console.cs dan readme.txt ke folder saat ini.

Pelokalan 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
  • Pasca tindakan
    • 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 .template-config\localize dalam folder.

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 pelokalan elemen yang diberikan 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."
    }
  }
}

Dan beberapa bidang akan dilokalkan ke 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)

Template kustom dikemas dengan perintah dotnet pack 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:

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

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

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

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

Cara mudah untuk menyusun paket template Anda adalah dengan meletakkan semua template di folder terpisah, lalu setiap folder template di dalam folder template 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 di template 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. Hal ini mengemas folder turunan template 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 template keduanya terletak di akar direktori bernama project_folder. Folder template berisi dua template, mytemplate1 dan mytemplate2. Setiap template 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

Catatan

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

Menginstal paket templat

Gunakan perintah instal baru dotnet untuk menginstal paket templat.

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

Gunakan pengidentifikasi paket NuGet untuk menginstal paket template.

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 template dari file nupkg lokal

Berikan jalur ke file paket NuGet .nupkg.

dotnet new install <PATH_TO_NUPKG_FILE>

Untuk menginstal paket template dari direktori sistem file

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

dotnet new install <FILE_SYSTEM_DIRECTORY>

Dapatkan daftar paket template yang diinstal

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

dotnet new uninstall

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

Item tingkat pertama setelah Currently installed items: adalah pengidentifikasi yang digunakan dalam menghapus instalan paket template. 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.

Menghapus instalan paket templat

Gunakan perintah hapus instalan baru dotnet untuk menghapus instalan paket templat.

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

dotnet new uninstall <NUGET_PACKAGE_ID>

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

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Membuat proyek menggunakan template 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 pada perintah dotnet new, termasuk opsi khusus template yang Anda konfigurasikan di pengaturan template. Berikan nama pendek template langsung ke perintah:

dotnet new <TEMPLATE>

Lihat juga