Přizpůsobení úložiště souborů a serializace XML

Když uživatel uloží instanci, tedy model , jazyka specifického pro doménu (DSL) v prostředí Visual Studio, vytvoří se nebo aktualizuje soubor XML. Soubor je možné znovu načíst a znovu vytvořit model ve Storu.

Schéma serializace můžete přizpůsobit úpravou nastavení v části Chování serializace XML v Dsl Exploreru. Pro každou doménovou třídu, vlastnost a vztah existuje uzel pod Chování serializace XML. Relace jsou umístěny v rámci jejich zdrojových tříd. Existují také uzly odpovídající třídám obrazce, spojnice a diagramu.

Můžete také napsat kód programu pro pokročilejší přizpůsobení.

Poznámka

Pokud chcete model uložit v určitém formátu, ale nepotřebujete ho z tohoto formuláře znovu načíst, zvažte použití textových šablon k vygenerování výstupu z modelu místo vlastního schématu serializace. Další informace najdete v tématu Generování kódu z Domain-Specific jazyka.

Soubory modelů a diagramů

Každý model je uložený ve dvou souborech:

• Soubor modelu má název, například Model1.mydsl. Ukládá prvky modelu a vztahy a jejich vlastnosti. Přípona souboru, jako například .mydsl, je určena vlastností FileExtension uzlu Editor v definici DSL.

• Soubor diagramu má název, například Model1.mydsl.diagram. Ukládá obrazce, spojnice a jejich pozice, barvy, tloušťky čáry a další podrobnosti o vzhledu diagramu. Pokud uživatel odstraní soubor .diagram, základní informace v modelu se neztratí. Ztratí se jenom rozložení diagramu. Při otevření souboru modelu se vytvoří výchozí sada obrazců a spojnic.

Chcete-li změnit příponu souboru DSL

1. Otevřete definici DSL. V Průzkumníku DSL klikněte na uzel Editor.

2. V okně Vlastnosti upravte vlastnost FileExtension. Nezahrnujte počáteční . přípony názvu souboru.

3. V Průzkumníku řešení změňte název dvou souborů šablon položky v DslPackage\ProjectItemTemplates. Tyto soubory mají názvy, které mají tento formát:

   myDsl.diagram

   myDsl.myDsl

Výchozí schéma serializace

K vytvoření příkladu pro toto téma se použila následující definice DSL.

definiční diagram

Tento DSL byl použit k vytvoření modelu, který má následující vzhled na obrazovce.

Tento model byl uložen a znovu otevřen v textovém editoru 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>

Všimněte si následujících bodů o serializovaném modelu:

• Každý uzel XML má název, který je stejný jako název třídy domény, s tím rozdílem, že počáteční písmeno je malými písmeny. Například familyTreeModel a person.

• Vlastnosti domény, jako je Name a BirthYear, jsou serializovány jako atributy v uzlech XML. Znovu se počáteční znak názvu vlastnosti převede na malá písmena.

• Každá relace je serializována jako uzel XML vnořený uvnitř zdrojového konce relace. Uzel má stejný název jako vlastnost zdrojové role, ale s počátečním písmenem malým.

  Například v definici DSL je role s názvem Lidé, která pochází z třídy FamilyTree. V souboru XML je role Lidé reprezentována uzlem people, který je vnořený uvnitř uzlu familyTreeModel.

• Cílový bod každého vnořeného vztahu je serializován jako uzel vnořený pod vztahem. Například uzel people obsahuje několik person uzlů.

• Cílový konec každé referenční relace je serializován jako znak , který kóduje odkaz na cílový prvek.

  Například v person uzlu může existovat relace children. Tento uzel obsahuje přezdívky jako například:

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

Pochopení monikers

Monikers se používají k reprezentaci křížových odkazů mezi různými částmi modelu a soubory diagramu. Používají se také v souboru .diagram k odkazování na uzly v souboru modelu. Existují dvě formy monikeru:

• id monikers uvozovat identifikátor GUID cílového prvku. Například:

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

• Monikers kvalifikovaného klíče identifikují cílový prvek podle hodnoty nazvané vlastnosti domény nazývané moniker key. Moniker cílového prvku je předcházen monikerem jeho nadřazeného prvku ve stromu vkládání vztahů.

  Následující příklady pocházejí z DSL, ve kterém je doménová třída s názvem Album, která má vztah vložení do doménové třídy s názvem Song:

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

  Kvalifikovaný klíč monikers se používá, pokud cílová třída má vlastnost domény, pro kterou je možnost Je Moniker Key je nastavena na true v Xml Serialization Behavior. V tomto příkladu je tato možnost nastavena pro vlastnosti domény s názvem "Title" ve třídách domény Album a Song.

Kvalifikované klíčové monikery jsou čitelnější než ID monikery. Pokud máte v úmyslu, aby soubory modelu byly čitelné pro člověka, zvažte použití kvalifikovaných klíčových monikerů. Je však možné, aby uživatel nastavil více než jeden prvek, aby měl stejný klíč monikeru. Duplicitní klíče můžou způsobit, že se soubor nenačte správně. Proto pokud definujete třídu domény, na kterou se odkazuje pomocí kvalifikovaných klíčových monikers, měli byste zvážit způsoby, jak zabránit uživateli v uložení souboru, který má duplicitní monikers.

Nastavit třídu domény, která bude odkazována pomocí ID označení

1. Ujistěte se, že jako Moniker Key je false pro každou vlastnost domény ve třídě a jejích základních třídách.

   1. V DSL Exploreru rozbalte Xml Serialization Behavior\Class Data\<doménovou třídu>\Element Data.

   2. Ověřte, že je klíč Moniker key je false pro každou vlastnost domény.

   3. Pokud má doménová třída základní třídu, opakujte proceduru v této třídě.

2. Nastavte Serializace ID = true pro třídu domény.

   Tuto vlastnost naleznete v části Chování serializace XML.

Nastavit třídu domény tak, aby na ni odkazovaly kvalifikované klíčové identifikátory

• Nastavte jako klíč Moniker pro vlastnost domény existující třídy domény. Typ vlastnosti musí být string.

  1. V DSL Explorer rozbalte Xml Serialization Behavior\Class Data\<domain class>\Element Dataa pak vyberte vlastnost domény.

  2. V okně Vlastnosti nastavte Is Moniker Key na true.

• - nebo -

  Vytvořte novou třídu domény pomocí nástroje Pojmenovaná třída domény.

  Tento nástroj vytvoří novou třídu, která má vlastnost domény s názvem Name. Is Element Name a Is Moniker Key vlastnosti této doménové vlastnosti jsou inicializovány na true.

• - nebo -

  Vytvořte vztah dědičnosti z doménové třídy do jiné třídy, která má vlastnost moniker key.

Vyhněte se duplicitním monikerům

Pokud použijete kvalifikátory klíče, je možné, že dva elementy v modelu uživatele mohou mít stejnou hodnotu v klíčové vlastnosti. Pokud má například dsl třídu Person, která má vlastnost Jméno, může uživatel nastavit Názvy dvou prvků na stejné. I když by se model dal uložit do souboru, nenačte se správně.

Existuje několik metod, které pomáhají předejít této situaci:

• Nastavte elementu název jako = true pro vlastnost klíčové domény. Vyberte vlastnost domény v diagramu definice DSL a pak nastavte hodnotu v okně Vlastnosti.

  Když uživatel vytvoří novou instanci třídy, tato hodnota způsobí, že vlastnost domény bude automaticky přiřazena jinou hodnotu. Výchozí chování přidá číslo na konec názvu třídy. Toto uživateli nezabrání ve změně jména na duplicitní, ale pomůže, pokud uživatel nenastaví hodnotu před uložením modelu.

• Povolte ověřování pro DSL. V Průzkumníku DSL vyberte Editor/Validace a nastavte vlastnosti Používá... na true.

  Existuje automaticky generovaná metoda ověřování, která kontroluje nejednoznačnosti. Metoda je v kategorii ověřování Load. Tím se zajistí, že se uživateli zobrazí upozornění, že nemusí být možné soubor znovu otevřít.

  Další informace najdete v tématu Ověření v Domain-Specific jazyce.

Cesty a kvalifikátory moniker

Kvalifikovaný klíčový moniker končí monikerem klíče a má jako předponu moniker svého nadřazeného objektu ve stromové struktuře vložení. Pokud je například moniker alba:

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

Pak může být jedna z skladeb v tom albu:

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

Pokud jsou alba odkazována podle ID, pak by přezdívky byly následující:

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

Všimněte si, že protože identifikátor GUID je jedinečný, nikdy není doplněn monikerem svého nadřazeného objektu.

Pokud víte, že určitá vlastnost domény bude mít vždy jedinečnou hodnotu v rámci modelu, můžete pro tuto vlastnost nastavit jako kvalifikátor monikeru na true. To způsobí, že se použije jako kvalifikátor, aniž by se použil název rodiče. Například pokud nastavíte je kvalifikátor monikeru a je klíč monikeru pro vlastnost domény Název třídy Album, název nebo identifikátor modelu se v monikerech pro Album a jeho vložené podřízené položky nepoužívá.

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

Přizpůsobení struktury XML

Chcete-li provést následující přizpůsobení, rozbalte uzel Chování XML serializace v Průzkumníku DSL. V rámci třídy domény rozbalte uzel Prvková data a zobrazte seznam vlastností a vztahů, které pocházejí z této třídy. Vyberte relaci a upravte její možnosti v okně Vlastnosti.

• Nastavte Vynechat prvek na hodnotu true, pokud chcete vynechat zdrojový uzel role a ponechat pouze seznam cílových prvků. Tuto možnost byste neměli nastavit, pokud mezi zdrojovými a cílovými třídami existuje více než jeden vztah.

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

• Nastavte Použít plnou formu pro vložení cílových uzlů do uzlů představujících instance relací. Tato možnost se nastaví automaticky při přidání vlastností domény do vztahu domény.

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

• Nastavte, aby Reprezentace = prvek měl vlastnost domény uloženou jako prvek místo jako hodnotu atributu.

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

• Chcete-li změnit pořadí, ve kterém jsou atributy a vztahy serializovány, klikněte pravým tlačítkem myši na položku v části Údaje elementu a použijte příkazy nabídky Přesunout nahoru nebo Přesunout dolů.

Hlavní přizpůsobení pomocí kódu programu

Můžete nahradit části nebo všechny algoritmy serializace.

Doporučujeme studovat kód v Dsl\Generated Code\Serializer.cs a SerializationHelper.cs.

Přizpůsobit serializaci konkrétní třídy

1. Nastavení je přizpůsobený jako v uzlu pro tuto třídu v části Xml chování serializace.

2. Transformujte všechny šablony, sestavte řešení a prozkoumejte výsledné chyby kompilace. Komentáře v blízkosti každé chyby vysvětlují, jaký kód musíte poskytnout.

Poskytnutí vlastní serializace pro celý model

1. Přepsání metod v souboru Dsl\GeneratedCode\SerializationHelper.cs

Poznámka

Počínaje sadou Visual Studio 2022 17.13 už výchozí implementace serializace nepodporuje serializaci nebo deserializaci vlastních datových typů pomocí BinaryFormatter z důvodu bezpečnostních rizik s BinaryFormatter.

Pokud používáte vlastní datový typ pro jakékoli vlastnosti domény, musíte buď přepsat metody serializace ve třídě SerializationHelper, nebo implementovat TypeConverter, který je schopný převést každý vlastní datový typ do a z řetězce.

I když nedoporučujeme používat BinaryFormatter z bezpečnostních důvodů, pokud je nutné zachovat zpětnou kompatibilitu se staršími modely, které používaly BinaryFormatter serializace, můžete implementovat TypeConverter, který deserializuje binární data. Následující fragment kódu slouží jako šablona pro implementaci této kompatibility:

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

Možnosti v chování serializace XML

V nástroji DSL Explorer uzel Chování serializace XML obsahuje podřízený uzel pro každou třídu domény, relaci, obrazec, spojnici a třídu diagramu. Pod každým z těchto uzlů je seznam vlastností a relací zdrojových v daném prvku. Relace jsou reprezentovány samy o sobě i ve zdrojových třídách.

Následující tabulka shrnuje možnosti, které můžete nastavit v této části definice DSL. V každém případě vyberte prvek v Průzkumníku DSL a nastavte možnosti v okně Vlastnosti.

Data třídy Xml

Tyto prvky jsou nalezeny v DSL Explorer v části Xml Serialization Behavior\Class Data.

Vlastnost	Popis
Má vlastní schéma elementu	Pokud je true, znamená to, že třída domény má vlastní schéma elementu.
Je přizpůsobené	Nastavte hodnotu na True pokud chcete napsat vlastní serializace a deserializační kód pro tuto třídu domény. Sestavte řešení a prozkoumejte chyby a zjistěte podrobné pokyny.
Doménová třída	Doménová třída, na kterou se vztahuje datový uzel této třídy. Jen pro čtení.
Název elementu	Název uzlu XML pro elementy této třídy. Výchozí hodnota je verze názvu třídy domény s malými písmeny.
Název atributu Moniker	Název atributu použitého v elementech monikeru, který obsahuje odkaz. Pokud je hodnota prázdná, použije se název vlastnosti nebo ID klíče. V tomto příkladu je to "name": <personMoniker name="/Mike Nash"/>
Název elementu Moniker	Název prvku XML používaného pro identifikátory, které odkazují na prvky této třídy. Výchozí hodnota je malá verze názvu třídy s příponou "Moniker". Například personMoniker.
Název typu monikeru	Název typu XSD, který je vygenerován pro přezdívky k prvkům této třídy. XSD je v Dsl\Generated Code\*Schema.xsd
Serializace ID	Pokud je true, identifikátor GUID elementu je součástí souboru. Hodnota musí být nastavena na hodnotu True pokud neexistuje žádná vlastnost, která je označena Je Moniker Key a DSL definuje odkazové relace k této třídě.
Název typu	Název typu XML vygenerovaného v xsd z určené třídy domény.
Poznámky	Neformální poznámky přidružené k tomuto prvku

Data vlastností XML

Uzly vlastností XML se nacházejí pod uzly třídy.

Vlastnost	Popis
Vlastnost domény	Vlastnost, na kterou se vztahují konfigurační data serializace XML. Jen pro čtení.
Je moniker klíč?	Pokud je hodnota nastavena na True, vlastnost se používá jako klíč pro vytváření monikers, které odkazují na instance této třídy domény.
Je kvalifikátor Moniker	Pokud je hodnota nastavena na True, vlastnost se používá k vytvoření kvalifikátoru v monikers. Pokud je nepravda a pokud SerializeId není pravda pro tuto třídu domény, monikery jsou kvalifikovány monikerem nadřazeného elementu ve stromu vkládání.
Reprezentace	Pokud je hodnota nastavena na Atribut, vlastnost je serializována jako xml atribut; pokud je hodnota nastavena na Element, je serializován jako prvek; pokud je hodnota nastavena na Ignorovat, pak není serializována.
Název XML	Název použitý pro atribut xml nebo element představující vlastnost. Ve výchozím nastavení je hodnota verze názvu vlastnosti domény malými písmeny.
Poznámky	Neformální poznámky přidružené k tomuto prvku

Údaje o roli XML

Uzly dat role se nacházejí v uzlech zdrojové třídy.

Vlastnost	Popis
Má vlastní moniker	Tuto hodnotu nastavte na true, pokud chcete poskytnout vlastní kód pro generování a vyřešení monikerů, které procházejí touto relací. Pro získání podrobných pokynů sestavte řešení a dvakrát klikněte na chybové zprávy.
Vztah domény	Určuje relaci, na kterou se tyto možnosti vztahují. Jen pro čtení.
Vynechat prvek	Pokud je hodnota true, uzel XML, který odpovídá zdrojové roli, není ze schématu vynechán. Pokud mezi zdrojovými a cílovými třídami existuje více relací, tento uzel role rozlišuje mezi propojeními, které patří do těchto dvou relací. Proto doporučujeme tuto možnost v tomto případě nenastavovat.
Název elementu role	Určuje název elementu XML odvozeného ze zdrojové role. Výchozí hodnota je název vlastnosti role.
Použít úplný formulář	Pokud je hodnota true, každý cílový prvek nebo moniker je uzavřen v uzlu XML představujícím relaci. Pokud má relace vlastní vlastnosti domény, měla by být nastavena na hodnotu true.

Související obsah

• Navigace a aktualizace modelu v kódu programu
• generování kódu z Domain-Specific jazyka