Bagikan melalui

Tutorial: Membuat templat item

  • Artikel

Dengan .NET, Anda dapat membuat dan menyebarkan templat yang menghasilkan proyek, file, dan sumber daya. Tutorial ini adalah bagian 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.

Tip

Templat item tidak ditampilkan dalam dialog Tambahkan>Item Baru di Visual Studio.

Di bagian seri ini, Anda akan mempelajari cara:

  • Buat kelas untuk templat item.
  • Buat folder dan file konfigurasi templat.
  • Instal templat dari jalur file.
  • Menguji templat item.
  • Hapus instalan templat item.

Prasyarat

  • .NET SDK 7.0.100 atau versi yang lebih baru.

    Artikel referensi menjelaskan dasar-dasar tentang templat dan bagaimana templat disatukan. Beberapa informasi ini dinyatakan kembali di sini.

  • Buka terminal dan navigasi ke folder tempat Anda akan menyimpan dan menguji templat.

Penting

Artikel ini ditulis untuk .NET 7. Namun, ini juga berlaku untuk .NET 6 dan versi sebelumnya, dengan satu perbedaan: dotnet new Sintaksnya berbeda. listSub perintah , search, install, dan uninstall harus , --list--search, --install, dan --uninstall opsi, masing-masing.

Misalnya, dotnet new install perintah di .NET 7 menjadi dotnet new --install di .NET 6. dotnet new --help Gunakan perintah untuk melihat daftar semua opsi dan sub-perintah.

Membuat folder yang diperlukan

Seri ini menggunakan "folder kerja" tempat sumber templat Anda berada dan "folder pengujian" yang digunakan untuk menguji templat Anda. Folder kerja dan folder pengujian harus berada di bawah folder induk yang sama.

Pertama, buat folder induk, nama tidak masalah. Kemudian, buat dua subfolder bernama bekerja dan uji. Di dalam folder kerja, buat subfolder bernama konten.

Struktur folder akan terlihat seperti berikut ini.

parent_folder
├───test
└───working
    └───content

Membuat templat item

Templat item adalah jenis templat tertentu yang berisi satu atau beberapa file. Jenis templat ini berguna ketika Anda sudah memiliki proyek dan Anda ingin membuat file lain, seperti file konfigurasi atau file kode. Dalam contoh ini, Anda akan membuat kelas yang menambahkan metode ekstensi ke jenis string.

Di terminal Anda, navigasikan ke folder working\content dan buat subfolder baru bernama extensions.

working
└───content
    └───extensions

Navigasi ke folder ekstensi dan buat file baru bernama StringExtensions.cs. Buka file di editor teks. Kelas ini akan menyediakan metode ekstensi bernama Reverse yang membalikkan konten string. Tempelkan kode berikut dan simpan file:

namespace System;

public static class StringExtensions
{
    public static string Reverse(this string value)
    {
        char[] tempArray = value.ToCharArray();
        Array.Reverse(tempArray);
        return new string(tempArray);
    }
}

Sekarang setelah konten templat selesai, langkah selanjutnya adalah membuat konfigurasi templat.

Membuat konfigurasi templat

Di bagian tutorial ini, folder templat Anda terletak di working\content\extensions.

Templat dikenali oleh .NET karena memiliki folder khusus dan file konfigurasi yang ada di akar folder templat Anda.

Pertama, buat subfolder baru bernama .template.config, dan masukkan. Kemudian, buat file baru bernama template.json. Struktur folder Anda akan terlihat seperti ini:

working
└───content
    └───extensions
        └───.template.config
                template.json

Buka template.json dengan editor teks favorit Anda dan tempelkan kode JSON berikut dan simpan.

{
    "$schema": "http://json.schemastore.org/template",
    "author": "Me",
    "classifications": [ "Common", "Code" ],
    "identity": "ExampleTemplate.StringExtensions",
    "name": "Example templates: string extensions",
    "shortName": "stringext",
    "tags": {
      "language": "C#",
      "type": "item"
    },
    "symbols": {
      "ClassName":{
        "type": "parameter",
        "description": "The name of the code file and class.",
        "datatype": "text",
        "replaces": "StringExtensions",
        "fileRename": "StringExtensions",
        "defaultValue": "StringExtensions"
      }
    }
  }

File konfigurasi ini berisi semua pengaturan untuk templat Anda. Anda dapat melihat pengaturan dasar, seperti name dan shortName, tetapi ada juga tags/type nilai yang diatur ke item. Ini mengategorikan templat Anda sebagai templat "item". Tidak ada batasan pada jenis templat yang Anda buat. Nilai item dan project adalah nama umum yang direkomendasikan .NET sehingga pengguna dapat dengan mudah memfilter jenis templat yang mereka cari.

Item classifications mewakili kolom tag yang Anda lihat saat menjalankan dotnet new dan mendapatkan daftar templat. Pengguna juga dapat mencari berdasarkan tag klasifikasi. Jangan membingungkan tags properti dalam file template.json dengan classifications daftar tag. Mereka adalah dua konsep berbeda yang sayangnya dinamai sama. Skema lengkap untuk file template.json ditemukan di Penyimpanan Skema JSON dan dijelaskan di Referensi untuk template.json. Untuk informasi selengkapnya tentang file template.json, lihat wiki templating dotnet.

Bagian symbols dari objek JSON ini digunakan untuk menentukan parameter yang dapat digunakan dalam templat. Dalam hal ini, ada satu parameter yang ditentukan, ClassName. Parameter yang ditentukan berisi pengaturan berikut:

  • type - Ini adalah pengaturan wajib dan harus diatur ke parameter.
  • description - Deskripsi parameter, yang dicetak dalam bantuan templat.
  • datatype - Jenis data nilai parameter saat parameter digunakan.
  • replaces - Menentukan nilai teks yang harus diganti di semua file templat dengan nilai parameter.
  • fileRename - Mirip replacesdengan , ini menentukan nilai teks yang diganti dalam nama semua file templat dengan nilai parameter.
  • defaultValue - Nilai default parameter ini ketika parameter tidak ditentukan oleh pengguna.

Ketika templat digunakan, pengguna dapat memberikan nilai untuk ClassName parameter , dan nilai ini menggantikan semua kemunculan StringExtensions. Jika nilai tidak disediakan, nilai defaultValue akan digunakan. Untuk templat ini, ada dua kemunculan StringExtensions: file StringExtensions.cs dan kelas StringExtensions. defaultValue Karena parameternya adalah StringExtensions, nama file dan nama kelas tetap tidak berubah jika parameter tidak ditentukan saat menggunakan templat. Ketika nilai ditentukan, misalnya dotnet new stringext -ClassName MyExts, file diganti namanya menjadi MyExts.cs dan kelas diganti namanya menjadi MyExts.

Untuk melihat parameter apa yang tersedia untuk templat, gunakan -? parameter dengan nama templat:

dotnet new stringext -?

Yang menghasilkan output berikut:

Example templates: string extensions (C#)
Author: Me

Usage:
  dotnet new stringext [options] [template options]

Options:
  -n, --name <name>       The name for the output being created. If no name is specified, the name of the output directory is used.
  -o, --output <output>   Location to place the generated output.
  --dry-run               Displays a summary of what would happen if the given command line were run if it would result in a template creation.
  --force                 Forces content to be generated even if it would change existing files.
  --no-update-check       Disables checking for the template package updates when instantiating a template.
  --project <project>     The project that should be used for context evaluation.
  -lang, --language <C#>  Specifies the template language to instantiate.
  --type <item>           Specifies the template type to instantiate.

Template options:
  -C, --ClassName <ClassName>  The name of the code file and class.
                               Type: text
                               Default: StringExtensions

Sekarang setelah Anda memiliki file .template.config/template.json yang valid, templat Anda siap untuk diinstal. Di terminal Anda, navigasikan ke folder ekstensi dan jalankan perintah berikut untuk menginstal templat yang terletak di folder saat ini:

  • Pada Windows: dotnet new install .\
  • Di Linux atau macOS: dotnet new install ./

Perintah ini menghasilkan daftar templat yang diinstal, yang harus menyertakan templat Anda.

The following template packages will be installed:
   <root path>\working\content\extensions

Success: <root path>\working\content\extensions installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code

Menguji templat item

Sekarang setelah Anda menginstal templat item, uji templat tersebut.

  1. Navigasikan ke folder pengujian .

  2. Buat aplikasi konsol baru dengan dotnet new console, yang menghasilkan proyek kerja yang dapat Anda uji dengan mudah dengan dotnet run perintah .

    dotnet new console

    Anda mendapatkan output yang mirip dengan yang berikut ini.

    The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on C:\test\test.csproj...
  Restore completed in 54.82 ms for C:\test\test.csproj.

Restore succeeded.

  3. Jalankan proyek menggunakan perintah berikut.

    dotnet run

    Anda mendapatkan output berikut.

    Hello, World!

  4. Jalankan dotnet new stringext untuk menghasilkan file StringExtensions.cs dari templat.

    dotnet new stringext

    Anda mendapatkan output berikut.

    The template "Example templates: string extensions" was created successfully.

  5. Ubah kode di Program.cs untuk membalikkan "Hello, World!" string dengan metode ekstensi yang disediakan oleh templat.

    Console.WriteLine("Hello, World!".Reverse());

    Jalankan program lagi dan lihat bahwa hasilnya dibalik.

    dotnet run

    Anda mendapatkan output berikut.

    !dlroW ,olleH

Selamat! Anda membuat dan menyebarkan templat item dengan .NET. Sebagai persiapan untuk bagian berikutnya dari seri tutorial ini, hapus instalan templat yang Anda buat. Pastikan untuk menghapus semua file dan folder di folder pengujian juga. Ini membuat Anda kembali ke status bersih siap untuk bagian berikutnya dari seri tutorial ini.

Menghapus instalan templat

Di terminal Anda, navigasikan ke folder ekstensi dan jalankan perintah berikut untuk menghapus instalasi templat yang terletak di folder saat ini:

  • Pada Windows: dotnet new uninstall .\
  • Di Linux atau macOS: dotnet new uninstall ./

Perintah ini menghasilkan daftar templat yang dihapus instalasinya, yang harus menyertakan templat Anda.

Success: <root path>\working\content\extensions was uninstalled.

Kapan saja, Anda dapat menggunakan dotnet new uninstall untuk melihat daftar paket templat yang diinstal, termasuk untuk setiap paket templat perintah untuk menghapus instalannya.

Langkah berikutnya

Dalam tutorial ini, Anda membuat templat item. Untuk mempelajari cara membuat templat proyek, lanjutkan seri tutorial ini.

Membuat templat proyek