Menyesuaikan Alat dan Toolbox

Anda harus menentukan item toolbox untuk elemen yang ingin Anda biarkan pengguna tambahkan ke model mereka. Ada dua jenis alat: alat elemen dan alat koneksi. Di perancang yang dibuat, pengguna dapat memilih alat elemen untuk menyeret bentuk ke diagram, dan dapat memilih alat koneksi untuk menggambar tautan di antara bentuk. Secara umum, alat elemen memungkinkan pengguna menambahkan instans kelas domain ke model mereka, dan alat koneksi memungkinkan mereka menambahkan instans hubungan domain.

Cara toolbox ditentukan

Di Penjelajah DSL, buka node Editor dan node di bawahnya. Biasanya Anda akan melihat hierarki yang menyerupai ini:

Editor
     Toolbox Tabs
        MyDsl          //a tab
           Tools
               ExampleElement      // an element tool
               ExampleRelationship // a connection tool

Di bagian Penjelajah DSL ini, Anda dapat:

• Membuat tab baru. Tab menentukan judul bagian di toolbox.

• Membuat alat baru.

• Menyalin dan menempel alat.

• Memindahkan alat ke atas atau ke bawah dalam daftar.

• Menghapus tab dan alat.

Penting

Untuk menambahkan atau menempelkan item di Penjelajah DSL, klik kanan yang terdahulu dari node baru. Misalnya, untuk menambahkan alat, klik kanan tab, dan bukan node Alat. Untuk menambahkan tab, klik kanan node Editor.

Properti Ikon Toolbox dari setiap alat mereferensikan file bitmap 16x16. File tersebut biasanya disimpan di folder Dsl\Resources.

Properti Kelas dari alat elemen merujuk pada kelas domain konkret. Secara default, alat ini akan membuat instans kelas ini. Namun, Anda dapat menulis kode agar alat membuat grup elemen, atau elemen dari berbagai jenis.

Properti Penyusun Koneksi dari alat koneksi merujuk pada penyusun koneksi, yang menentukan jenis elemen apa yang dapat disambungkan alat, dan hubungan apa yang dibuatnya di antara mereka. Penyusun koneksi ditentukan sebagai node di Penjelajah DSL. Penyusun koneksi dibuat secara otomatis saat Anda menentukan hubungan domain, tetapi Anda dapat menulis kode untuk menyesuaikannya.

Untuk menambahkan alat ke toolbox

1. Anda biasanya membuat alat elemen setelah membuat kelas bentuk dan memetakannya ke kelas domain.

   Anda biasanya membuat alat konektor setelah membuat kelas konektor dan memetakannya ke hubungan referensi.

2. Di Penjelajah DSL, buka node Editor dan node Tab Toolbox.

   Klik kanan node tab toolbox, lalu klik Tambahkan Alat Elemen Baru atau Tambahkan Alat Koneksi Baru.

3. Atur properti Ikon Toolbox untuk merujuk ke bitmap 16x16.

   Jika Anda ingin menentukan ikon baru, buat file bitmap di Penjelajah Solusi di folder Dsl\Resources. File harus memiliki nilai properti berikut: Tindakan Build = Konten; Salin ke Direktori Output = Jangan salin.

4. Untuk alat elemen: Atur properti Kelas alat untuk merujuk ke kelas domain konkret yang dipetakan ke bentuk.

   Untuk alat konektor: Atur properti Penyusun Koneksi alat ke salah satu item yang ditawarkan di daftar drop-down. Penyusun koneksi secara otomatis dibuat saat Anda memetakan konektor ke hubungan domain. Jika Anda baru saja membuat konektor, Anda biasanya akan memilih penyusun koneksi terkait.

5. Untuk menguji DSL, tekan F5 atau CTRL+F5, dan dalam instans eksperimental Visual Studio, buka file model sampel. Alat baru akan muncul di toolbox. Seret ke diagram untuk memverifikasi bahwa alat tersebut membuat elemen baru.

   Jika alat tidak muncul, hentikan Visual Studio eksperimental. Di menu Mulai Windows, ketik reset Visual Studio, lalu jalankan perintah Reset Instans Eksperimental Microsoft Visual Studio yang cocok dengan versi Visual Studio Anda. Pada menu Buils, pilih Buat ulang Solusi. Kemudian uji DSL lagi.

Menyesuaikan Alat Elemen

Secara default, alat ini akan membuat satu instans dari kelas yang ditentukan, tetapi Anda dapat memvariasikan ini dengan dua cara:

• Tentukan Petunjuk Gabungan Elemen pada kelas lain, sehingga mereka dapat menerima instans baru kelas ini, dan dapat membuat tautan tambahan saat elemen baru dibuat. Misalnya, Anda dapat mengizinkan pengguna untuk memberi Komentar ke elemen lain, dan dengan demikian membuat tautan referensi di antara keduanya.

  Penyesuaian ini juga memengaruhi apa yang terjadi saat pengguna menempelkan atau menyeret dan menghilangkan elemen.

  Untuk informasi selengkapnya, lihat Menyesuaikan Pembuatan dan Gerakan Elemen.

• Tulis kode untuk menyesuaikan alat sehingga dapat membuat grup elemen. Alat ini diinisialisasi oleh metode di ToolboxHelper.cs yang dapat Anda ganti. Untuk informasi selengkapnya, lihat Membuat Grup Elemen dari Alat.

Membuat Grup Elemen dari Alat

Setiap alat elemen berisi prototipe elemen yang harus dibuat. Secara default, setiap alat elemen akan membuat satu elemen, tetapi juga dapat membuat sekelompok objek terkait dengan satu alat. Untuk melakukan ini, Anda menginisialisasi alat dengan ElementGroupPrototype yang berisi item terkait.

Contoh berikut diambil dari DSL tempat ada jenis Transistor. Setiap Transistor memiliki tiga terminal bernama. Alat elemen untuk Transistors menyimpan prototipe yang berisi empat elemen model dan tiga tautan hubungan. Saat pengguna menyeret alat ke diagram, prototipe akan dibuat dan ditautkan ke akar model.

Kode ini akan mengganti metode yang ditentukan dalam Dsl\GeneratedCode\ToolboxHelper.cs.

Untuk informasi selengkapnya tentang menyesuaikan model dengan menggunakan kode program, lihat Menavigasi dan Memperbarui Model dalam Kode Program.

using Microsoft.VisualStudio.Modeling;
using Microsoft.VisualStudio.Modeling.Diagrams;

  public partial class CircuitsToolboxHelper
  {
    /// <summary>
    /// Toolbox initialization, called for each element tool on the toolbox.
    /// This version deals with each Component subtype separately.
    /// </summary>
    /// <param name="store"></param>
    /// <param name="domainClassId">Identifies the domain class this tool should instantiate.</param>
    /// <returns>prototype of the object or group of objects to be created by tool</returns>
    protected override ElementGroupPrototype CreateElementToolPrototype(Store store, Guid domainClassId)
    {
        if (domainClassId == Transistor.DomainClassId)
        {
            Transistor transistor = new Transistor(store);

            transistor.Base = new ComponentTerminal(store);
            transistor.Collector = new ComponentTerminal(store);
            transistor.Emitter = new ComponentTerminal(store);

            transistor.Base.Name = "base";
            transistor.Collector.Name = "collector";
            transistor.Emitter.Name = "emitter";

            // Create an ElementGroup for the Toolbox.
            ElementGroup elementGroup = new ElementGroup(store.DefaultPartition);
            elementGroup.AddGraph(transistor, true);
            // AddGraph includes the embedded parts

            return elementGroup.CreatePrototype();
        }
        else
        {
            return base.CreateElementToolPrototype(store, domainClassId);
}  }    }

Menyesuaikan Alat Koneksi

Biasanya, Anda membuat alat elemen saat membuat kelas konektor baru. Atau, Anda dapat membebani satu alat dengan memungkinkan jenis kedua ujung untuk menentukan jenis hubungan. Misalnya, Anda dapat menentukan satu alat koneksi yang dapat membuat hubungan Orang-Orang dan hubungan Orang-Kota.

Alat koneksi memanggil penyusun koneksi. Gunakan penyusun koneksi untuk menentukan cara pengguna dapat menautkan elemen di perancang yang dibuat. Penyusun koneksi menentukan elemen yang dapat ditautkan dan jenis tautan yang dibuat di antaranya.

Saat Anda membuat hubungan referensi antara kelas domain, penyusun koneksi secara otomatis dibuat. Anda dapat menggunakan penyusun koneksi ini saat memetakan alat koneksi. Untuk informasi selengkapnya tentang cara membuat alat koneksi, lihat Mengonfigurasi Toolbox.

Anda dapat mengubah penyusun koneksi default sehingga dapat menangani berbagai jenis sumber dan target, dan membuat berbagai jenis hubungan.

Anda juga dapat menulis kode kustom untuk penyusun koneksi untuk menentukan kelas sumber dan target untuk koneksi, menentukan jenis koneksi yang akan dibuat, dan mengambil tindakan lain yang terkait dengan pembuatan koneksi.

Struktur Penyusun Koneksi

Penyusun koneksi berisi satu atau beberapa petunjuk koneksi tautan, yang menentukan hubungan domain serta elemen sumber dan target. Misalnya, dalam template solusi Alur Tugas, Anda bisa melihat CommentReferencesSubjectsBuilder di Penjelajah DSL. Penyusun koneksi ini berisi satu petunjuk koneksi tautan bernama CommentReferencesSubjects, yang dipetakan ke hubungan domain CommentReferencesSubjects. Petunjuk tautan ini berisi petunjuk peran sumber yang mengarah ke kelas domain Comment, dan petunjuk peran target yang mengarah ke kelas domain FlowElement.

Menggunakan Penyusun Koneksi untuk Membatasi Peran Sumber dan Target

Anda dapat menggunakan penyusun koneksi untuk membatasi kemunculan kelas tertentu baik dalam peran sumber atau peran target dari hubungan domain tertentu. Misalnya, Anda mungkin memiliki kelas domain dasar yang memiliki hubungan domain dengan kelas domain lain, tetapi Anda mungkin tidak ingin semua kelas turunan dari kelas dasar memiliki peran yang sama dalam hubungan tersebut. Dalam solusi Alur Tugas, ada empat kelas domain konkret (StartPoint, EndPoint, MergeBranch, dan Synchronization) yang mewarisi langsung dari kelas domain abstrak FlowElement, dan dua kelas domain konkret (Task dan ObjectInState) yang secara tidak langsung mewarisi darinya. Ada juga hubungan referensi Flow yang mengambil kelas domain FlowElement dalam peran sumber dan peran targetnya. Namun, instans kelas domain EndPoint tidak boleh menjadi sumber instans hubungan Flow, juga instans kelas StartPoint tidak boleh menjadi target instans hubungan Flow. Penyusun koneksi FlowBuilder memiliki petunjuk koneksi tautan bernama Flow yang menentukan kelas domain mana yang dapat memainkan peran sumber (Task, MergeBranch, StartPoint, dan Synchronization) dan yang dapat memainkan peran target (MergeBranch, Endpoint, dan Synchronization).

Penyusun Koneksi dengan Beberapa Petunjuk Koneksi Tautan

Anda dapat menambahkan lebih dari satu petunjuk koneksi tautan ke penyusun koneksi. Ini dapat membantu Anda menyembunyikan beberapa kompleksitas model domain dari pengguna dan menjaga Toolbox agar tidak terlalu berantakan. Anda dapat menambahkan petunjuk koneksi tautan untuk beberapa hubungan domain yang berbeda ke satu penyusun koneksi. Namun, Anda harus menggabungkan hubungan domain saat mereka melakukan fungsi yang kurang lebih sama.

Dalam solusi Alur Tugas, alat koneksi Flow digunakan untuk menggambar instans hubungan domain Flow dan ObjectFlow. Penyusun koneksi FlowBuilder memiliki, selain petunjuk koneksi tautan Flow yang dijelaskan sebelumnya, dua petunjuk koneksi tautan bernama ObjectFlow. Petunjuk ini menentukan bahwa instans hubungan ObjectFlow dapat digambar di antara instans kelas domain ObjectInState, atau dari instans ObjectInState ke instans Task, tetapi tidak antara dua instans Task, atau dari instans Task ke instans ObjectInState. Namun, instans hubungan Flow dapat digambar di antara dua instans Task. Jika Anda mengompilasi dan menjalankan solusi Alur Tugas, Anda dapat melihat bahwa menggambar Flow dari instans ObjectInState ke instans Task akan membuat instans ObjectFlow, tetapi menggambar Flow di antara dua instans Task akan membuat instans Flow.

Kode Kustom untuk Penyusun Koneksi

Ada empat kotak centang di antarmuka pengguna yang menentukan berbagai jenis penyesuaian penyusun koneksi:

• kotak centang Penerimaan kustom pada petunjuk peran sumber atau target

• kotak centang Koneksi kustom pada petunjuk peran sumber atau target

• kotak centang Menggunakan koneksi kustom pada petunjuk koneksi

• properti Kustom dari penyusun koneksi

  Anda harus menyediakan beberapa kode program untuk membuat penyesuaian ini. Untuk menemukan kode apa yang harus Anda berikan, centang salah satu kotak ini, klik Ubah Semua Template, lalu buat solusi Anda. Laporan kesalahan akan dihasilkan. Klik dua kali laporan kesalahan untuk melihat komentar yang menjelaskan kode apa yang harus Anda tambahkan.

Catatan

Untuk menambahkan kode kustom, buat definisi kelas parsial dalam file kode yang terpisah dari file kode di folder GeneratedCode. Agar pekerjaan Anda tidak hilang, Anda tidak boleh mengedit file kode yang dibuat. Untuk informasi selengkapnya, lihat Mengambil alih dan Memperluas Kelas yang Dihasilkan.

Membuat kode Koneksi Kustom

Di setiap petunjuk koneksi tautan, tab Petunjuk peran sumber menentukan dari jenis apa yang dapat Anda seret. Demikian pula, tab Petunjuk peran target menentukan jenis apa yang dapat Anda seret. Untuk setiap jenis, Anda dapat menentukan lebih lanjut apakah akan mengizinkan koneksi (untuk petunjuk koneksi tautan tersebut) dengan mengatur bendera Penerimaan Kustom lalu menyediakan kode tambahan.

Anda juga dapat menyesuaikan apa yang dilakukan saat koneksi dibuat. Misalnya, Anda dapat menyesuaikan hanya kasus di mana tarikan dilakukan ke atau dari kelas tertentu, semua kasus yang diatur oleh satu tautan menghubungkan petunjuk, atau seluruh penyusun koneksi FlowBuilder. Untuk setiap opsi ini, Anda dapat mengatur bendera kustom pada tingkat yang sesuai. Saat Anda mengubah semua template dan mencoba membuat solusi, pesan kesalahan mengarahkan Anda ke komentar yang ada dalam kode yang dihasilkan. Komentar ini mengidentifikasi apa yang harus Anda berikan.

Dalam sampel Diagram Komponen, penyusun koneksi untuk hubungan domain Koneksi disesuaikan untuk membatasi koneksi yang dapat dibuat di antara port. Ilustrasi berikut menunjukkan bahwa Anda hanya dapat membuat koneksi dari elemen OutPort ke elemen InPort, tetapi Anda dapat menumpuk komponen di dalam satu sama lain.

Koneksi Masuk ke OutPort dari Komponen Berlapis

Oleh karena itu, Anda mungkin ingin menentukan bahwa koneksi dapat berasal dari komponen berlapis ke OutPort. Untuk menentukan koneksi seperti itu, Anda dapat mengatur Gunakan Penerimaan Kustom pada jenis InPort sebagai peran sumber dan jenis OutPort sebagai peran target di jendela Detail DSL seperti yang diperlihatkan dalam ilustrasi berikut:

Menautkan Petunjuk Koneksi di Penjelajah DSL

Menautkan Petunjuk Koneksi di Jendela Detail DSL

Anda kemudian harus menyediakan metode di kelas ConnectionBuilder:

  public partial class ConnectionBuilder
  {
    /// <summary>
    /// OK if this component has children
    /// </summary>
    private static bool CanAcceptInPortAsSource(InPort candidate)
    {
       return candidate.Component.Children.Count > 0;
    }

    /// <summary>
    /// Only if source is on parent of target.
    /// </summary>
    private static bool CanAcceptInPortAndInPortAsSourceAndTarget                (InPort sourceInPort, InPort targetInPort)
    {
      return sourceInPort.Component == targetInPort.Component.Parent;
    }
// And similar for OutPorts...

Untuk informasi selengkapnya tentang menyesuaikan model dengan menggunakan kode program, lihat Menavigasi dan Memperbarui Model dalam Kode Program.

Anda dapat menggunakan kode serupa, misalnya, untuk mencegah pengguna membuat perulangan dengan tautan induk-turunan. Pembatasan ini dianggap sebagai batasan 'keras' karena pengguna tidak dapat melanggarnya kapan saja. Anda juga dapat membuat pemeriksaan validasi 'sementara' yang dapat dilewati pengguna untuk sementara waktu dengan membuat konfigurasi yang tidak valid yang tidak dapat disimpan.

Praktik Yang Baik dalam Menentukan Penyusun Koneksi

Anda harus menentukan satu penyusun koneksi untuk membuat berbagai jenis hubungan hanya jika terkait secara konseptual. Dalam sampel alur tugas, Anda menggunakan penyusun yang sama untuk membuat alur antara tugas dan juga antara tugas dan objek. Namun, akan membingungkan untuk menggunakan penyusun yang sama untuk membuat hubungan antara komentar dan tugas.

Jika Anda menentukan penyusun koneksi untuk beberapa jenis hubungan, Anda harus memastikan bahwa itu tidak dapat mencocokkan lebih dari satu jenis dari pasangan objek sumber dan target yang sama. Jika tidak, hasilnya tidak akan dapat diprediksi.

Anda menggunakan kode kustom untuk menerapkan batasan 'permanen', tetapi Anda harus mempertimbangkan apakah pengguna harus dapat membuat koneksi yang tidak valid untuk sementara waktu. Jika harus, Anda dapat mengubah batasan sehingga koneksi tidak divalidasi sampai pengguna mencoba menyimpan perubahan.

Konten terkait

• Menyesuaikan Pembuatan dan Gerakan Elemen
• Menyesuaikan Perilaku Salin
• Cara: Menambahkan Penangan Seret dan Letakkan
• Menavigasi dan Memperbarui Model dalam Kode Program
• DSL sampel Diagram Sirkuit