Bagikan melalui

Menyesuaikan Penyimpanan File dan Serialisasi XML

Saat pengguna menyimpan sebuah instance, atau model, dari bahasa khusus domain (DSL) di Visual Studio, sebuah file XML dibuat atau diperbarui. File dapat dimuat ulang untuk membuat ulang model di Store.

Anda dapat menyesuaikan skema serialisasi dengan menyesuaikan pengaturan di bawah Perilaku Serialisasi Xml di DSL Explorer. Ada simpul di bawah Perilaku Serialisasi Xml untuk setiap kelas domain, properti, dan hubungan. Hubungan terletak di bawah kelas sumbernya. Ada juga simpul yang sesuai dengan kelas bentuk, konektor, dan diagram.

Anda juga dapat menulis kode program untuk penyesuaian yang lebih canggih.

Nota

Jika Anda ingin menyimpan model dalam format tertentu, tetapi Anda tidak perlu memuat ulang dari formulir tersebut, pertimbangkan untuk menggunakan templat teks untuk menghasilkan output dari model, alih-alih skema serialisasi kustom. Untuk informasi selengkapnya, lihat Menghasilkan Kode dari Domain-Specific Bahasa.

File Model dan Diagram

Setiap model disimpan dalam dua file:

  • File model memiliki nama seperti Model1.mydsl. Ini menyimpan elemen model dan hubungan dan propertinya. Ekstensi file seperti .mydsl ditentukan oleh properti FileExtension dari simpul Editor dalam Definisi DSL.

  • File diagram memiliki nama seperti Model1.mydsl.diagram. Ini menyimpan bentuk, konektor, dan posisi, warna, ketebalan garis, dan detail lain dari tampilan diagram. Jika pengguna menghapus file .diagram, informasi penting dalam model tidak hilang. Hanya tata letak diagram yang hilang. Saat file model dibuka, sekumpulan bentuk dan konektor default dibuat.

Untuk mengubah ekstensi file DSL

  1. Buka dokumen Definisi DSL. Di Penjelajah DSL, klik pada simpul Editor.

  2. Di jendela Properti, edit properti FileExtension. Jangan sertakan “.” sebagai awalan dalam ekstensi nama file.

  3. Di Penjelajah Solusi, ubah nama dua file templat item di DslPackage\ProjectItemTemplates. File-file ini memiliki nama yang mengikuti format ini:

    myDsl.diagram

    myDsl.myDsl

Skema Serialisasi Default

Untuk membuat contoh untuk topik ini, Definisi DSL berikut digunakan.

Diagram Definisi DSL - Model Pohon Keluarga

DSL ini digunakan untuk membuat model yang memiliki tampilan berikut di layar.

Diagram pohon keluarga, kotak alat, dan penjelajah

Model ini disimpan lalu dibuka kembali di editor teks XML:

<?xml version="1.0" encoding="utf-8"?>
<familyTreeModel xmlns:dm0="http://schemas.microsoft.com/VisualStudio/2008/DslTools/Core" dslVersion="1.0.0.0" Id="f817b728-e920-458e-bb99-98edc469d78f" xmlns="http://schemas.microsoft.com/dsltools/FamilyTree">
  <people>
    <person name="Henry VIII" birthYear="1491" deathYear="1547" age="519">
      <children>
        <personMoniker name="/f817b728-e920-458e-bb99-98edc469d78f/Elizabeth I" />
        <personMoniker name="/f817b728-e920-458e-bb99-98edc469d78f/Mary" />
      </children>
    </person>
    <person name="Elizabeth I" birthYear="1533" deathYear="1603" age="477" />
    <person name="Mary" birthYear="1515" deathYear="1558" age="495" />
  </people>
</familyTreeModel>

Perhatikan poin-poin berikut tentang model ter-serialisasi:

  • Setiap simpul XML memiliki nama yang sama dengan nama kelas domain, kecuali bahwa huruf awal adalah huruf kecil. Misalnya, familyTreeModel dan person.

  • Properti domain seperti Nama dan BirthYear diserialisasikan sebagai atribut dalam simpul XML. Sekali lagi, karakter awal nama properti dikonversi menjadi huruf kecil.

  • Setiap hubungan diserialisasikan sebagai simpul XML yang disarangkan di dalam bagian awal sumber hubungan. Simpul memiliki nama yang sama dengan properti peran sumber, tetapi karakter awal nama tersebut menggunakan huruf kecil.

    Misalnya, dalam Definisi DSL, peran yang diberi nama People bersumber pada kelas FamilyTree. Dalam XML, peran People diwakili dengan simpul bernama people terletak dalam simpul familyTreeModel.

  • Akhir target dari setiap hubungan penyematan diserialisasikan sebagai simpul yang disarangkan dalam hubungan. Misalnya, simpul people berisi beberapa simpul person.

  • Akhir target dari setiap hubungan referensi diserialisasikan sebagai moniker , yang mengodekan referensi ke elemen target.

    Misalnya, di bawah simpul person, mungkin ada hubungan children. Simpul ini berisi moniker seperti:

    <personMoniker name="/f817b728-e920-458e-bb99-98edc469d78f/Elizabeth I" />

Memahami Monikers

Monikers digunakan untuk mewakili referensi silang antara berbagai bagian model dan file diagram. Mereka juga digunakan dalam file .diagram untuk merujuk ke simpul dalam file model. Ada dua bentuk moniker:

  • Id monikers menyisipkan GUID elemen target. Misalnya:

    <personShapeMoniker Id="f79734c0-3da1-4d72-9514-848fa9e75157" />

  • Moniker kunci terkualifikasi mengidentifikasi elemen target berdasarkan nilai properti domain yang disebut sebagai kunci moniker. Nama dari elemen target diawali dengan nama elemen induknya dalam hierarki hubungan penyematan.

    Contoh berikut diambil dari DSL di mana ada kelas domain bernama Album, yang memiliki hubungan penyematan ke kelas domain bernama Song:

    <albumMoniker title="/My Favorites/Jazz after Teatime" />
<songMoniker title="/My Favorites/Jazz after Teatime/Hot tea" />

    Moniker kunci yang memenuhi syarat digunakan jika kelas target memiliki properti domain yang opsinya Kunci Moniker diatur ke true dalam Perilaku Serialisasi Xml . Dalam contoh, opsi ini diatur untuk properti domain bernama "Judul" di kelas domain "Album" dan "Song".

Moniker kunci yang memenuhi syarat lebih mudah dibaca daripada moniker ID. Jika Anda ingin XML file model Anda dapat dibaca manusia, pertimbangkan untuk menggunakan moniker kunci yang memenuhi syarat. Namun, pengguna dapat mengatur lebih dari satu elemen untuk memiliki kunci moniker yang sama. Kunci duplikat dapat menyebabkan file tidak dimuat ulang dengan benar. Oleh karena itu, jika Anda menentukan kelas domain yang dirujuk menggunakan moniker kunci yang memenuhi syarat, Anda harus mempertimbangkan cara mencegah pengguna menyimpan file yang memiliki moniker duplikat.

Untuk mengatur kelas domain yang akan dirujuk oleh moniker ID

  1. Pastikan Kunci Moniker false untuk setiap properti domain di kelas dan kelas dasarnya.

    1. Di DSL Explorer, perluas Xml Serialization Behavior\Class Data\<kelas domain>\Element Data.

    2. Verifikasi bahwa Kunci Moniker false untuk setiap properti domain.

    3. Jika kelas domain memiliki kelas dasar, ulangi prosedur di kelas tersebut.

  2. Atur Id Serialisasi = true untuk kelas domain.

    Properti ini terdapat di bawah Perilaku Serialisasi XML.

Untuk mengatur kelas domain yang akan dirujuk oleh moniker kunci yang memenuhi syarat

  • Setel sebagai Kunci Moniker untuk properti domain dari kelas domain yang ada. Jenis properti harus string.

    1. Di DSL Explorer, perluas Xml Serialization Behavior\Class Data\<kelas domain>\Element Data, lalu pilih properti domain.

    2. Di jendela Properti, atur Kunci Moniker ke true.

  • -atau-

    Buat kelas domain baru menggunakan alat Kelas Domain Bernama.

    Alat ini membuat kelas baru yang memiliki properti domain yang disebut Nama. adalah Nama Elemen dan adalah Kunci Moniker dari properti domain ini yang diinisialisasi ke true.

  • -atau-

    Buat hubungan Pewarisan dari kelas domain ke kelas lain yang memiliki properti kunci moniker.

Hindari Penggunaan Nama Panggilan yang Sama

Jika Anda menggunakan moniker kunci yang memenuhi syarat, ada kemungkinan bahwa dua elemen dalam model pengguna dapat memiliki nilai yang sama di properti kunci. Misalnya, jika DSL Anda memiliki kelas Orang yang memiliki nama properti, pengguna dapat mengatur Nama dua elemen agar sama. Meskipun model dapat disimpan ke dalam file, model tersebut tidak dapat dimuat ulang dengan benar.

Ada beberapa metode yang membantu menghindari situasi ini:

  • Atur Adalah Nama Elemen = true untuk properti domain kunci. Pilih properti domain pada diagram Definisi DSL lalu atur nilai di jendela Properti.

    Saat pengguna membuat instans baru kelas, nilai ini menyebabkan properti domain secara otomatis diberi nilai yang berbeda. Perilaku default menambahkan angka ke akhir nama kelas. Ini tidak mencegah pengguna mengubah nama menjadi duplikat, tetapi membantu dalam kasus ketika pengguna tidak mengatur nilai sebelum menyimpan model.

  • Aktifkan validasi untuk DSL. Di DSL Explorer, pilih Editor\Validasi, dan atur Uses... properti ke true.

    Ada metode validasi yang dihasilkan secara otomatis yang memeriksa ambiguitas. Metode ini berada dalam kategori validasi Load. Ini memastikan bahwa pengguna akan diperingatkan bahwa mungkin tidak mungkin untuk membuka kembali file.

    Untuk informasi selengkapnya, lihat Validasi dalam Bahasa Domain-Specific.

Jalur dan Kualifikasi Moniker

Moniker kunci yang memenuhi syarat diakhiri dengan kunci moniker, dan diawali dengan moniker induknya di pohon penyematan. Misalnya, jika moniker Album adalah:

<albumMoniker title="/My Favorites/Jazz after Teatime" />

Kemudian salah satu Lagu dalam Album itu bisa menjadi:

<songMoniker title="/My Favorites/Jazz after Teatime/Hot tea" />

Namun, jika Album dirujuk oleh ID sebagai gantinya, maka moniker adalah sebagai berikut:

<albumMoniker Id="77472c3a-9bf9-4085-976a-d97a4745237c" />
<songMoniker title="/77472c3a-9bf9-4085-976a-d97a4745237c/Hot tea" />

Perhatikan bahwa karena GUID bersifat unik, GUID tidak pernah diawali oleh nama panggilan induknya.

Jika Anda tahu bahwa properti domain tertentu akan selalu memiliki nilai unik dalam model, Anda dapat mengatur Is Moniker Qualifier ke true untuk properti tersebut. Ini menyebabkannya digunakan sebagai penentu, tanpa menggunakan nama induk. Misalnya, jika Anda mengatur Sebagai Moniker Qualifier dan Sebagai Moniker Key untuk properti domain Judul dalam kelas Album, nama atau pengidentifikasi model tidak digunakan dalam moniker untuk Album dan anak-anak yang tertanam.

<albumMoniker name="Jazz after Teatime" />
<songMoniker title="/Jazz after Teatime/Hot tea" />

Mengkustomisasi struktur XML

Untuk membuat kustomisasi berikut, perluas simpul Perilaku Serialisasi Xml di DSL Explorer. Di bawah kelas domain, perluas simpul Data Elemen untuk melihat daftar properti dan hubungan yang bersumber di kelas ini. Pilih hubungan dan sesuaikan opsinya di jendela Properti.

  • Atur Omit Element ke true untuk menghilangkan simpul peran sumber, hanya menyisakan daftar elemen target. Anda tidak boleh mengatur opsi ini jika ada lebih dari satu hubungan antara kelas sumber dan target.

    <familyTreeModel ...>
  <!-- The following node is omitted by using Omit Element: -->
  <!-- <people> -->
    <person name="Henry VIII" .../>
    <person name="Elizabeth I" .../>
  <!-- </people> -->
</familyTreeModel>

  • Atur Gunakan Formulir Lengkap untuk menyematkan simpul target dalam simpul yang mewakili instans hubungan. Opsi ini diatur secara otomatis saat Anda menambahkan properti domain ke hubungan domain.

    <familyTreeModel ...>
  <people>
    <!-- The following node is inserted by using Use Full Form: -->
    <familyTreeModelHasPeople myRelationshipProperty="x1">
      <person name="Henry VIII" .../>
    </familyTreeModelHasPeople>
    <familyTreeModelHasPeople myRelationshipProperty="x2">
      <person name="Elizabeth I" .../>
    </familyTreeModelHasPeople>
  </people>
</familyTreeModel>

  • Atur representasi = Element agar properti domain disimpan sebagai elemen, bukan sebagai nilai atribut.

    <person name="Elizabeth I" birthYear="1533">
  <deathYear>1603</deathYear>
</person>

  • Untuk mengubah urutan di mana atribut dan hubungan diserialisasikan, klik kanan item di bawah Data Elemen, dan gunakan perintah menu Pindah ke Atas atau Pindah ke Bawah.

Kustomisasi utama menggunakan kode program

Anda dapat mengganti bagian atau semua algoritma serialisasi.

Kami menyarankan agar Anda mempelajari kode di Dsl\Generated Code\Serializer.cs dan SerializationHelper.cs.

Untuk menyesuaikan serialisasi kelas tertentu

  1. Atur Adalah Kustom di simpul untuk kelas tersebut di bawah Perilaku Serialisasi Xml .

  2. Ubah Semua Templat, buat solusi, dan selidiki kesalahan kompilasi yang dihasilkan. Komentar di dekat setiap kesalahan menjelaskan kode apa yang harus Anda berikan.

Untuk menyediakan serialisasi Anda sendiri untuk seluruh model

  1. Mengambil alih metode dalam Dsl\GeneratedCode\SerializationHelper.cs

Nota

Dimulai dengan Visual Studio 2022 17.13, implementasi serialisasi default tidak lagi mendukung serialisasi atau deserialisasi jenis data kustom menggunakan BinaryFormatter karena risiko keamanan dengan BinaryFormatter.

Jika Anda menggunakan jenis data kustom untuk properti domain apa pun, Anda perlu mengambil alih metode serialisasi di kelas SerializationHelper, atau menerapkan TypeConverter yang mampu mengonversi setiap jenis data kustom ke dan dari string.

Meskipun kami tidak merekomendasikan penggunaan BinaryFormatter untuk alasan keamanan, jika Anda harus mempertahankan kompatibilitas mundur dengan model lama yang menggunakan serialisasi BinaryFormatter, Anda dapat menerapkan TypeConverter yang mendeserialisasi data biner. Cuplikan kode berikut berfungsi sebagai templat untuk menerapkan kompatibilitas ini:

class MyCustomDataTypeConverter : TypeConverter
{
    public override bool CanConvertFrom(ITypeDescriptorContext context, Type sourceType)
    {
        return sourceType == typeof(string) || base.CanConvertFrom(context, sourceType);
    }

    public override bool CanConvertTo(ITypeDescriptorContext context, Type destinationType)
    {
        return destinationType == typeof(string) || base.CanConvertTo(context, destinationType);
    }

    public override object ConvertFrom(ITypeDescriptorContext context, CultureInfo culture, object value)
    {
        if (value is string text)
        {
            // First, try to parse the string as if it were returned by MyCustomDataType.ToString().
            if (MyCustomDataType.TryParse(text, out var custom))
                return custom;

            // Fall back to trying to deserialize the old BinaryFormatter serialization format.
            var decoded = Convert.FromBase64String(text);
            using (var memory = new MemoryStream(decoded, false))
            {
                var binaryFormatter = new BinaryFormatter();
                return binaryFormatter.Deserialize(memory) as MyCustomDataType;
            }
        }

        return base.ConvertFrom(context, culture, value);
    }

    public override object ConvertTo(ITypeDescriptorContext context, CultureInfo culture, object value, Type destinationType)
    {
        if (destinationType == typeof(string) && value is MyCustomDataType custom)
            return custom.ToString();

        return base.ConvertTo(context, culture, value, destinationType);
    }
}

// ...

[TypeConverter(MyCustomDataTypeConverter)]
class MyCustomDataType
{
    // ...
}

Opsi dalam Perilaku Serialisasi Xml

Di DSL Explorer, simpul Perilaku Serialisasi Xml berisi simpul anak untuk setiap kelas domain, hubungan, bentuk, konektor, dan kelas diagram. Di bawah masing-masing simpul tersebut adalah daftar properti dan hubungan yang bersumber pada elemen tersebut. Hubungan diwakili baik dalam hak mereka sendiri maupun di bawah kelas sumbernya.

Tabel berikut ini meringkas opsi yang bisa Anda atur di bagian Definisi DSL ini. Dalam setiap kasus, pilih elemen di DSL Explorer, dan atur opsi di jendela Properti.

Data Kelas Xml

Elemen-elemen ini ditemukan di DSL Explorer di bawah Perilaku Serialisasi XML\Kelas Data.

Harta benda Deskripsi
Memiliki Skema Elemen Kustom Jika True, menunjukkan bahwa kelas domain memiliki skema elemen kustom
Adalah Kustom Atur nilai ke True jika Anda ingin menulis kode serialisasi dan deserialisasi Anda sendiri untuk kelas domain ini.

Bangun solusi dan selidiki kesalahan untuk menemukan instruksi terperinci.
Kelas Domain Kelas domain yang diterapkan untuk simpul data kelas ini. Baca-saja.
Nama Elemen Nama simpul xml untuk elemen kelas ini. Nilai default adalah versi huruf kecil dari nama kelas domain.
Nama Atribut Moniker Nama atribut yang digunakan dalam elemen moniker untuk menampung referensi. Jika kosong, nama properti kunci atau id digunakan.

Dalam contoh ini, itu adalah "nama": <personMoniker name="/Mike Nash"/>
Nama Elemen Moniker Nama elemen xml yang digunakan untuk moniker yang merujuk ke elemen kelas ini.

Nilai default adalah versi huruf kecil dari nama kelas yang diafiks dengan "Moniker". Misalnya, personMoniker.
Nama Jenis Moniker Nama tipe xsd yang dihasilkan untuk penanda ke elemen-elemen kelas ini. XSD berada dalam Dsl\Generated Code\*Schema.xsd
Serialisasi Id Jika nilainya True, GUID elemen disertakan dalam file. Nilai harus diatur ke True jika tidak ada properti yang ditandai sebagai Kunci Moniker dan DSL menentukan hubungan referensi ke kelas ini.
Silakan ketik nama Nama jenis xml yang dihasilkan dalam xsd dari kelas domain yang ditunjuk.
Catatan Catatan informal yang terkait dengan elemen ini

Data Properti XML

Simpul-simpul Properti Xml ditemukan di bawah simpul-simpul kelas.

Harta benda Deskripsi
Properti Domain Properti tempat data konfigurasi serialisasi xml diterapkan. Baca-saja.
Apakah Moniker adalah Kunci? Jika nilai diatur ke True, properti digunakan sebagai kunci untuk membuat moniker yang mereferensikan instans kelas domain ini.
Apakah Moniker Qualifier Jika nilai diatur ke True, properti digunakan untuk membuat kualifikasi pada moniker. Jika false, dan jika SerializeId tidak berlaku untuk kelas domain ini, moniker memenuhi syarat oleh moniker elemen induk di pohon penyematan.
Representasi Jika nilai diatur ke Atribut, maka properti diserialisasikan sebagai atribut xml; jika nilai diatur ke Element, maka nilai tersebut diserialisasikan sebagai elemen; jika nilai diatur ke Abaikan, maka nilai tersebut tidak diserialisasikan.
Nama XML Nama yang digunakan untuk atribut atau elemen xml yang mewakili properti . Secara default, nilainya adalah versi huruf kecil dari nama properti domain.
Catatan Catatan informal yang terkait dengan elemen ini

Data Peran Xml

Simpul data peran ditemukan di bawah simpul kelas sumber.

Harta benda Deskripsi
Memiliki Moniker Kustom Atur ini ke true jika Anda ingin menyediakan kode Anda sendiri untuk menghasilkan dan menyelesaikan moniker yang melintasi hubungan ini.

Untuk instruksi terperinci, buat solusi, lalu klik dua kali pesan kesalahan.
Hubungan Domain Menentukan hubungan yang berlaku untuk opsi ini. Baca-saja.
Hilangkan Elemen Jika true, simpul XML yang sesuai dengan peran sumber dihilangkan dari skema.

Jika ada lebih dari satu hubungan antara kelas sumber dan target, simpul peran ini membedakan antara tautan yang termasuk dalam dua hubungan. Oleh karena itu, kami menyarankan agar Anda tidak mengatur opsi ini dalam kasus ini.
Nama Elemen Peran Menentukan nama elemen XML yang berasal dari peran sumber. Nilai defaultnya adalah nama properti peran.
Gunakan Formulir Lengkap Jika true, setiap elemen target atau moniker diapit dalam simpul XML yang mewakili hubungan. Ini harus diatur menjadi "benar" jika relasi memiliki properti domainnya sendiri.

Konten terkait

  • Last updated on