Anpassen von Dateispeicher und XML-Serialisierung

Wenn der Benutzer eine Instanz oder ein Modell einer domänenspezifischen Sprache (DSL) in Visual Studio speichert, wird eine XML-Datei erstellt oder aktualisiert. Die Datei kann erneut geladen werden, um das Modell im Speicher neu zu erstellen.

Sie können das Serialisierungsschema anpassen, indem Sie die Einstellungen unter Xml-Serialisierungsverhalten im DSL-Explorer anpassen. Unter Xml-Serialisierungsverhalten ist für jede Domänenklasse, Eigenschaft und Beziehung ein Knoten vorhanden. Die Beziehungen befinden sich unter ihren Quellklassen. Es gibt auch Knoten, die den Form-, Verbinder- und Diagrammklassen entsprechen.

Sie können auch Programmcode für eine erweiterte Anpassung schreiben.

Hinweis

Wenn Sie das Modell in einem bestimmten Format speichern möchten, es aber nicht aus diesem Formular neu laden müssen, sollten Sie anstelle eines benutzerdefinierten Serialisierungsschemas Textvorlagen verwenden, um eine Ausgabe aus dem Modell zu generieren. Weitere Informationen finden Sie unter Generieren von Code aus einer domänenspezifischen Sprache.

Modell- und Diagrammdateien

Jedes Modell wird in der Regel in zwei Dateien gespeichert:

• Die Modelldatei trägt einen Namen wie Model1.mydsl. In ihr werden die Modellelemente und -beziehungen und deren Eigenschaften gespeichert. Die Dateierweiterung (z. B. .mydsl) wird durch die FileExtension-Eigenschaft des Editor-Knotens in der DSL-Definition bestimmt.

• Die Diagrammdatei trägt einen Namen wie Model1.mydsl.diagram. In ihr werden die Formen, Verbinder und ihre Positionen, Farben, Linienstärken und andere Details zum Aussehen des Diagramms gespeichert. Wenn der Benutzer eine DIAGRAM-Datei löscht, gehen die wesentlichen Informationen im Modell nicht verloren. Nur das Layout des Diagramms geht verloren. Wenn die Modelldatei geöffnet wird, wird ein Standardsatz von Formen und Verbindern erstellt.

So ändern Sie die Dateierweiterung einer DSL

1. Öffnen Sie die DSL-Definition. Klicken Sie im DSL-Explorer auf den Editor-Knoten.

2. Bearbeiten Sie im Eigenschaftenfenster die FileExtension-Eigenschaft. Schließen Sie nicht den anfänglichen „.“ der Erweiterung ein.

3. Ändern Sie im Projektmappen-Explorer die Namen der beiden Elementvorlagendateien in DslPackage\ProjectItemTemplates. Diese Dateien weisen Namen im folgenden Format auf:

   myDsl.diagram

   myDsl.myDsl

Das Standardserialisierungsschema

Um ein Beispiel für dieses Thema zu erstellen, wurde die folgende DSL-Definition verwendet.

Diese DSL wurde verwendet, um ein Modell zu erstellen, das auf dem Bildschirm wie folgt aussieht.

Dieses Modell wurde gespeichert und dann im XML-Text-Editor erneut geöffnet:

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

Beachten Sie die folgenden Punkte zum serialisierten Modell:

• Jeder XML-Knoten weist einen Namen auf, der mit einem Domänenklassennamen identisch ist, mit der Ausnahme, dass der Anfangsbuchstabe ein Kleinbuchstabe ist. Beispiel: familyTreeModel und person.

• Domäneneigenschaften wie Name und BirthYear werden als Attribute in den XML-Knoten serialisiert. Auch hier wird das Anfangszeichen des Eigenschaftennamens in einen Kleinbuchstaben konvertiert.

• Jede Beziehung wird als XML-Knoten serialisiert, der innerhalb der Quellseite der Beziehung geschachtelt ist. Der Knoten weist den gleichen Namen wie die Quellrolleneigenschaft auf, jedoch mit einem Kleinbuchstaben als Anfangszeichen.

  In der DSL-Definition weist eine Rolle namens People beispielsweise als Quelle die FamilyTree-Klasse auf. Im XML-Code wird dies durch den Knoten mit dem Namen people dargestellt, der innerhalb des familyTreeModel-Knotens geschachtelt ist.

• Die Zielseite jeder Einbettungsbeziehung wird als Knoten serialisiert, der unter der Beziehung geschachtelt ist. Der people-Knoten enthält beispielsweise mehrere person-Knoten.

• Die Zielseite jeder Verweisbeziehung wird als Moniker serialisiert, der einen Verweis auf das Zielelement codiert.

  Unter einem person-Knoten kann beispielsweise eine children-Beziehung vorhanden sein. Dieser Knoten enthält Moniker wie die folgenden:

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

Grundlegendes zu Monikern

Moniker werden verwendet, um Querverweise zwischen verschiedenen Teilen des Modells und Diagrammdateien darzustellen. Sie werden auch in der .diagram-Datei verwendet, um auf Knoten in der Modelldatei zu verweisen. Es gibt zwei Formen von Monikern:

• ID-Moniker zitieren die GUID des Zielelements. Zum Beispiel:

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

• Qualifizierte Schlüsselmoniker identifizieren das Zielelement anhand des Werts einer angegebenen Domäneneigenschaft, die als „Monikerschlüssel“ bezeichnet wird. Dem Moniker des Zielelements wird der Moniker seines übergeordneten Elements in der Struktur der Einbettungsbeziehungen als Präfix vorangestellt.

  Die folgenden Beispiele stammen aus einer DSL, in der eine Domänenklasse namens „Album“ vorhanden ist, die eine Einbettungsbeziehung zu einer Domänenklasse namens „Song“ aufweist:

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

  Qualifizierte Schlüsselmoniker werden verwendet, wenn die Zielklasse über eine Domäneneigenschaft verfügt, für die die Option Is Moniker Key im XML-Serialisierungsverhalten auf true festgelegt ist. Im Beispiel wird diese Option für Domäneneigenschaften namens „Title“ in den Domänenklassen „Album“ und „Song“ festgelegt.

Qualifizierte Schlüsselmoniker sind einfacher zu lesen als ID-Moniker. Wenn Sie möchten, dass der XML-Code Ihrer Modelldateien von Personen gelesen werden kann, sollten Sie die Verwendung qualifizierter Schlüsselmoniker in Betracht ziehen. Es ist jedoch möglich, dass der Benutzer mehrere Elemente auf denselben Monikerschlüssel festlegt. Doppelte Schlüssel können dazu führen, dass die Datei nicht ordnungsgemäß neu geladen wird. Wenn Sie also eine Domänenklasse definieren, auf die mit qualifizierten Schlüsselmonikern verwiesen wird, sollten Sie Möglichkeiten in Betracht ziehen, um zu verhindern, dass der Benutzer eine Datei mit doppelten Monikern speichern kann.

So legen Sie eine Domänenklasse fest, auf die durch ID-Moniker verwiesen werden soll

1. Stellen Sie sicher, dass Is Moniker Key für jede Domäneneigenschaft in der Klasse und deren Basisklassen false ist.

   1. Erweitern Sie im DSL-Explorer XML-Serialisierungsverhalten\Klassendaten\<die Domänenklasse>\Elementdaten.

   2. Vergewissern Sie sich, dass Is Moniker Key für jede Domäneneigenschaft false ist.

   3. Wenn die Domänenklasse über eine Basisklasse verfügt, wiederholen Sie den Vorgang in dieser Klasse.

2. Legen Sie die Serialisierungs-ID = true für die Domänenklasse fest.

   Diese Eigenschaft finden Sie unter XML-Serialisierungsverhalten.

So legen Sie eine Domänenklasse fest, auf die von qualifizierten Schlüsselmonikern verwiesen werden soll

• Legen Sie Is Moniker Key für eine Domäneneigenschaft einer vorhandenen Domänenklasse fest. Der Typ der Eigenschaft muss string sein.

  1. Erweitern Sie im DSL-Explorer XML-Serialisierungsverhalten\Klassendaten\<Domänenklasse>\Elementdaten, und wählen Sie dann die Domäneneigenschaft aus.

  2. Legen Sie im Eigenschaftenfenster Is Moniker Key auf true fest.

• - oder -

  Erstellen Sie mit dem Tool Named Domain Class eine neue Domänenklasse.

  Dieses Tool erstellt eine neue Klasse mit einer Domäneneigenschaft namens „Name“. Die Eigenschaften Is Element Name und Is Moniker Key dieser Domäneneigenschaft werden mit true initialisiert.

• - oder -

  Erstellen Sie eine Vererbungsbeziehung zwischen der Domänenklasse und einer anderen Klasse, die über eine Monikerschlüsseleigenschaft verfügt.

Vermeiden doppelter Moniker

Wenn Sie qualifizierte Schlüsselmoniker verwenden, ist es möglich, dass zwei Elemente im Modell eines Benutzers den gleichen Wert in der Schlüsseleigenschaft aufweisen. Wenn Ihre DSL beispielsweise über eine Person-Klasse mit einer Eigenschaft „Name“ verfügt, kann der Benutzer die Namen von zwei Elementen auf den gleichen Wert festlegen. Obwohl das Modell in einer Datei gespeichert werden kann, würde es nicht ordnungsgemäß neu geladen.

Es gibt mehrere Methoden, mit denen Sie diese Situation vermeiden können:

• Legen Sie Is Element Name = true für die Schlüsseldomäneneigenschaft fest. Wählen Sie die Domäneneigenschaft im DSL-Definitionsdiagramm aus, und legen Sie den Wert dann im Eigenschaftenfenster fest.

  Wenn der Benutzer eine neue Instanz der Klasse erstellt, bewirkt dieser Wert, dass der Domäneneigenschaft automatisch ein anderer Wert zugewiesen wird. Das Standardverhalten fügt am Ende des Klassennamens eine Zahl hinzu. Dies hindert den Benutzer nicht daran, den Namen in ein Duplikat zu ändern, ist aber hilfreich, wenn der Benutzer den Wert vor dem Speichern des Modells nicht festgelegt hat.

• Aktivieren Sie Validierung für die DSL. Wählen Sie im DSL-Explorer „Editor\Validierung“ aus, und legen Sie die Uses... -Eigenschaften auf true fest.

  Es gibt eine automatisch generierte Validierungsmethode, die auf Mehrdeutigkeiten prüft. Die Methode befindet sich in der Load-Validierungskategorie. Dadurch wird sichergestellt, dass der Benutzer gewarnt wird, dass es ggf. nicht möglich ist, die Datei erneut zu öffnen.

  Weitere Informationen finden Sie unter Validierung in einer domänenspezifischen Sprache.

Monikerpfade und -qualifizierer

Ein qualifizierter Schlüsselmoniker endet mit dem Monikerschlüssel und wird in der Einbettungsstruktur mit dem Moniker seines übergeordneten Elements als Präfix versehen. Beispiel: Der Moniker eines Albums lautet:

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

Dann könnte dies einer der Songs in diesem Album sein:

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

Wenn jedoch stattdessen über die ID auf Alben verwiesen wird, würden die Moniker wie folgt aussehen:

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

Beachten Sie Folgendes: Da eine GUID eindeutig ist, wird ihr niemals der Moniker ihres übergeordneten Elements als Präfix vorangestellt.

Wenn Sie wissen, dass eine bestimmte Domäneneigenschaft immer über einen eindeutigen Wert innerhalb eines Modells verfügt, können Sie Is Moniker Qualifier für diese Eigenschaft auf true festlegen. Dies führt dazu, dass sie als Qualifizierer verwendet wird, ohne den Moniker des übergeordneten Elements zu verwenden. Wenn Sie beispielsweise sowohl den Is Moniker Qualifier als auch Is Moniker Key für die Domäneneigenschaft „Title“ der Album-Klasse festlegen, wird der Name oder Bezeichner des Modells nicht in Monikern für „Album“ und die eingebetteten untergeordneten Elemente verwendet:

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

Anpassen der Struktur des XML-Codes

Erweitern Sie den Knoten XML-Serialisierungsverhalten im DSL-Explorer, um die folgenden Anpassungen vorzunehmen. Erweitern Sie unter einer Domänenklasse den Knoten „Elementdaten“, um die Liste der Eigenschaften und Beziehungen anzuzeigen, die aus dieser Klasse stammen. Wählen Sie eine Beziehung aus, und passen Sie deren Optionen im Eigenschaftenfenster an.

• Legen Sie Element auslassen auf TRUE fest, um den Quellrollenknoten auszulassen, sodass nur die Liste der Zielelemente übrig bleibt. Sie sollten diese Option nicht festlegen, wenn mehrere Beziehungen zwischen den Quell- und Zielklassen vorhanden sind.

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

• Legen Sie Vollständige Form verwenden fest, um die Zielknoten in Knoten einzubetten, die die Beziehungsinstanzen darstellen. Diese Option wird automatisch festgelegt, wenn Sie einer Domänenbeziehung Domäneneigenschaften hinzufügen.

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

• Legen SieDarstellung = Element so fest, dass eine Domäneneigenschaft als Element anstatt als Attributwert gespeichert wird.

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

• Um die Reihenfolge zu ändern, in der Attribute und Beziehungen serialisiert werden, klicken Sie mit der rechten Maustaste auf ein Element unter „Elementdaten“, und verwenden Sie die Menübefehle Nach oben oder Nach unten.

Größere Anpassungen mithilfe von Programmcode

Sie können Teile von oder alle Serialisierungsalgorithmen ersetzen.

Es wird empfohlen, den Code unter Dsl\Generated Code\Serializer.cs und SerializationHelper.cs zu untersuchen.

So passen Sie die Serialisierung einer bestimmten Klasse an

1. Legen Sie Is custom im Knoten für diese Klasse unter XML-Serialisierungsverhalten fest.

2. Transformieren Sie alle Vorlagen, erstellen Sie die Lösung, und untersuchen Sie die sich ergebenden Kompilierungsfehler. Kommentare in der Nähe jedes Fehlers erläutern, welchen Code Sie bereitstellen müssen.

So stellen Sie eine eigene Serialisierung für das gesamte Modell bereit

1. Außerkraftsetzen von Methoden in Dsl\GeneratedCode\SerializationHelper.cs

Optionen im XML-Serialisierungsverhalten

Im DSL-Explorer enthält der Knoten „XML-Serialisierungsverhalten“ einen untergeordneten Knoten für jede Domänenklasse, Beziehung, Form, Verbinder und Diagrammklasse. Unter jedem dieser Knoten befindet sich eine Liste der Eigenschaften und Beziehungen, die aus diesem Element stammen. Beziehungen werden sowohl eigenständig als auch unter ihren Quellklassen dargestellt.

In der folgenden Tabelle werden die Optionen zusammengefasst, die Sie in diesem Abschnitt der DSL-Definition festlegen können. Wählen Sie in jedem Fall ein Element im DSL-Explorer aus, und legen Sie die Optionen im Eigenschaftenfenster fest.

XML-Klassendaten

Diese Elemente befinden sich im DSL-Explorer unter XML-Serialisierungsverhalten\Klassendaten.

Eigenschaft	BESCHREIBUNG
Has Custom Element Schema	Gibt an, dass die Domänenklasse über ein benutzerdefiniertes Elementschema verfügt, wenn der Wert TRUE ist.
Is Custom	Legen Sie diesen Wert auf TRUE fest, wenn Sie Ihren eigenen Serialisierungs- und Deserialisierungscode für diese Domänenklasse schreiben möchten. Erstellen Sie die Lösung, und untersuchen Sie die Fehler, um detaillierte Anweisungen abzurufen.
Domänenklasse	Die Domänenklasse, für die dieser Klassendatenknoten gilt. Schreibgeschützt.
Elementname	Der XML-Knotenname für Elemente dieser Klasse. Der Standardwert ist eine Version des Domänenklassennamens in Kleinbuchstaben.
Moniker Attribute Name	Der Name des Attributs, das in Monikerelementen den Verweis enthält. Wenn das Attribut leer ist, wird der Name der Schlüsseleigenschaft oder der ID verwendet. In diesem Beispiel handelt es sich um "name": <personMoniker name="/Mike Nash"/>
Moniker Element Name	Der Name des XML-Elements, das für Moniker verwendet wird, die auf Elemente dieser Klasse verweisen. Der Standardwert ist eine Version des Klassennamens in Kleinbuchstaben mit dem Suffix „Moniker“. Beispiel: personMoniker.
Moniker Type Name	Der Name des XSD-Typs, der für Moniker für Elemente dieser Klasse generiert wird. Der XSD-Typ befindet sich in Dsl\Generated Code\*Schema.xsd.
Serialize Id	TRUE gibt an, dass die Element-GUID in der Datei enthalten ist. Dieser Wert muss TRUE sein, wenn keine Eigenschaft mit der Bezeichnung Is Moniker Key vorhanden ist und die DSL Verweisbeziehungen zu dieser Klasse definiert.
Typname	Der Name des XML-Typs, der in der XSD-Datei aus der angegebenen Domänenklasse generiert wird.
Notizen	Informelle Hinweise, die diesem Element zugeordnet sind

Xml Property Data

XML-Eigenschaftenknoten befinden sich unter den Klassenknoten.

Eigenschaft	BESCHREIBUNG
Domäneneigenschaft	Die Eigenschaft, für die die XML-Serialisierungskonfigurationsdaten gelten. Schreibgeschützt.
Is Moniker Key	Wenn dieser Wert TRUE ist, wird die Eigenschaft als Schlüssel zum Erstellen von Monikern verwendet, die auf Instanzen dieser Domänenklasse verweisen.
Is Moniker Qualifier	Wenn dieser Wert TRUE ist, wird die Eigenschaft zum Erstellen des Qualifizierers in Monikern verwendet. Wenn FALSE und SerializeId für diese Domänenklasse nicht TRUE ist, werden Moniker durch den Moniker des übergeordneten Elements in der Einbettungsstruktur qualifiziert.
Darstellung	Wenn es sich um ein Attribut handelt, wird die Eigenschaft als ein XML-Attribut serialisiert. Wenn es sich um ein Element handelt, erfolgt die Serialisierung als ein Element. Wenn „Ignorieren“ angegeben wird, findet keine Serialisierung statt.
Xml Name	Der Name, der für das XML-Attribut oder -Element verwendet wird, das die Eigenschaft darstellt. Standardmäßig ist dies eine Version des Domäneneigenschaftsnamens in Kleinbuchstaben.
Notizen	Informelle Hinweise, die diesem Element zugeordnet sind

Xml Role data

Rollendatenknoten befinden sich unter den Quellklassenknoten.

Eigenschaft	BESCHREIBUNG
Has Custom Moniker	Legen Sie diesen Wert auf TRUE fest, wenn Sie Ihren eigenen Code zum Generieren und Auflösen von Monikern bereitstellen möchten, die diese Beziehung durchlaufen. Um ausführliche Anweisungen zu erhalten, erstellen Sie die Projektmappe, und doppelklicken Sie dann auf die Fehlermeldungen.
Domänenbeziehung	Gibt die Beziehung an, für die diese Optionen gelten. Schreibgeschützt.
Omit Element	Wenn dieser Wert TRUE ist, wird der XML-Knoten,der der Quellrolle entspricht, im Schema ausgelassen. Wenn mehrere Beziehungen zwischen der Quell- und der Zielklasse vorhanden sind, unterscheidet dieser Rollenknoten zwischen Verknüpfungen, die zu den beiden Beziehungen gehören. Es wird daher empfohlen, diese Option in diesem Fall nicht festzulegen.
Role Element Name	Gibt den Namen des XML-Elements an, das von der Quellrolle abgeleitet ist. Der Standardwert ist der Name der Rolleneigenschaft.
Use Full Form	Wenn dieser Wert TRUE ist, wird jedes Zielelement oder jeder Moniker in einen XML-Knoten eingeschlossen, der die Beziehung darstellt. Dies sollte auf TRUE festgelegt werden, wenn die Beziehung über eigene Domäneneigenschaften verfügt.

Zugehöriger Inhalt

• Navigieren in und Aktualisieren von Modellen im Programmcode
• Generieren von Code für eine domänenspezifische Sprache