Personnalisation du stockage de fichiers et de la sérialisation XML

Article
05/19/2015

Lorsque l'utilisateur enregistre une instance, ou le modèle, d'un langage spécifique au domaine dans (DSL) Visual Studio, un fichier XML est créée ou mise à jour. Le fichier peut être rechargé pour recréer le modèle dans le magasin.

Vous pouvez personnaliser le schéma de sérialisation en ajustant les paramètres sous Comportement de sérialisation XML dans l'explorateur DÉSOLÉ. Il existe un nœud sous Comportement de sérialisation XML de chaque classe, propriété, et relation de domaine. Les relations se trouvent sous leurs classes de source. Il existe également des nœuds correspondant à la forme, le connecteur, et aux classes de schéma.

Vous pouvez également écrire le code de programme d'une personnalisation plus avancée.

Notes

Si vous souhaitez enregistrer le modèle dans un format particulier, mais vous n'avez pas besoin de le recharger de ce formulaire, envisagez d'utiliser des modèles de texte pour générer la sortie du modèle, au lieu d'un modèle de sérialisation personnalisée.Pour plus d'informations, consultez Génération de code à partir d'un langage spécifique à un domaine.

Modèle et fichiers de diagrammes

Chaque modèle est généralement stocké dans deux fichiers :

le fichier de modèle a un nom tel qu' Model1.mydsl. Il stocke des éléments de modèle et les relations et leurs propriétés. L'extension de fichier telle qu' .mydsl est déterminée par la propriété de FileExtension du nœud d' Éditeur dans la définition de langage spécifique à un domaine.
le fichier de diagramme a un nom tel qu' Model1.mydsl.diagram. Il enregistre les formes, des connecteurs, et leurs positions, des couleurs, des épaisseurs de ligne, et d'autres détails de l'apparence du diagramme. si l'utilisateur supprime un fichier d' .diagram , les informations nécessaires dans le modèle ne sont pas perdues. Seule la disposition du diagramme est perdue. Lorsque le fichier modèle est ouvert, un ensemble par défaut des formes et de connecteurs sera créé.

Pour modifier l'extension de fichier d'un DÉSOLÉ

Ouvrez la définition de langage spécifique à un domaine. Dans l'explorateur DÉSOLÉ, cliquez sur le nœud de l'éditeur.
Dans la fenêtre Propriétés, remplacez la propriété de FileExtension . N'incluez pas l'initial « . » pour l'extension de nom de fichier.
Dans l'explorateur de solutions, remplacez le nom des deux fichiers de modèle d'élément dans DslPackage\ProjectItemTemplates. ces fichiers ont des noms qui suivent ce format :

myDsl.diagram

myDsl.myDsl

Le modèle de sérialisation par défaut

Pour créer un exemple de cette rubrique, la définition suivante DÉSOLÉ a été utilisée.

Diagramme de définition DSL - modèle d'arbre généalogique

Ce DÉSOLÉ est utilisé pour créer un modèle qui a l'apparence suivante à l'écran.

Diagramme d'arbre généalogique, boîte à outils et explorateur

Ce modèle a été enregistré puis rouvert dans l'éditeur de texte XML :

<?xml version="1.0" encoding="utf-8"?>
<familyTreeModel xmlns:dm0="https://schemas.microsoft.com/VisualStudio/2008/DslTools/Core" dslVersion="1.0.0.0" Id="f817b728-e920-458e-bb99-98edc469d78f" xmlns="https://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>

Notez les points suivants à propos de le modèle sérialisé :

Chaque nœud XML a un nom qui est identique qu'un nom de classe de domaine, sauf que la lettre initiale est en minuscules. Par exemple, familyTreeModel et person.
Les propriétés de domaine comme le nom et le BirthYear sont sérialisées en tant qu'attributs dans les nœuds XML. De même, le caractère initial du nom de la propriété est converti en minuscules.
Chaque relation est sérialisée comme nœud XML imbriqué à l'intérieur de l'extrémité source de la relation. Le nœud a le même nom que le rôle de propriété de source, mais avec un caractère initial en minuscules.

Par exemple, dans la définition DÉSOLÉ, un rôle nommé People est alimenté à la classe d' FamilyTree . En XML, cela est représenté par le nœud nommé people imbriqué à l'intérieur de le nœud d' familyTreeModel .
La fin cible de chaque relation d'incorporation est sérialisée comme nœud imbriqué sous la relation. Par exemple, le nœud d' people contient plusieurs nœuds d' person .
la fin cible de chaque relation de référence est sérialisée comme moniker, qui encode une référence à l'élément cible.

Par exemple, sous un nœud d' person , il peut exister une relation d' children . Ce nœud contient des monikers telle que :
```
<personMoniker name="/f817b728-e920-458e-bb99-98edc469d78f/Elizabeth I" />
```

Monikers de présentation

Les monikers sont utilisés pour représenter des références croisées entre les différentes parties du modèle et fichiers de diagrammes. Ils sont également utilisés dans le fichier d' .diagram pour faire référence aux nœuds du fichier de modèle. Il existe deux formes moniker :

Les monikers d'identificateur GUID instance de l'élément cible. Par exemple :
```
<personShapeMoniker Id="f79734c0-3da1-4d72-9514-848fa9e75157" />
```
Les monikers principaux qualifiés identifient l'élément cible par la valeur d'une propriété de domaine indiquée appelée clé moniker. le moniker de l'élément cible est préfixé par le moniker de son élément parent dans l'arborescence des relations d'incorporation.

Les exemples suivants sont pris d'un langage spécifique à un domaine dans lequel il existe une classe de domaine nommée Album, qui a une relation d'incorporer à une classe de domaine nommée Song :
```
<albumMoniker title="/My Favorites/Jazz after Teatime" />
<songMoniker title="/My Favorites/Jazz after Teatime/Hot tea" />
```
Les monikers principaux qualifiés seront utilisés si la classe cible a une propriété de domaine pour laquelle l'option Est la clé moniker est définie à true dans Comportement de sérialisation XML. Dans l'exemple, cette option est définie pour les propriétés de domaine nommées « titre » dans les classes « album » et « chanson » de domaine.

Il est plus facile à lire des monikers principaux qualifiés que des monikers d'ID. Si vous prévoyez XML de vos fichiers de modèle à lire par des personnes, envisagez d'utiliser des monikers principaux qualifiés. Toutefois, il est possible que l'utilisateur définisse plusieurs éléments pour avoir la même clé moniker. Les clés en double peuvent faire en sorte que les recharger le fichier correctement. Par conséquent, si vous définissez une classe de domaine qui est référencée à l'aide de les monikers principaux qualifiés, vous devez tenir compte des moyens d'empêcher l'utilisateur d'enregistrer un fichier qui contient des monikers en double.

Pour définir une classe de domaine à référencer par les monikers d'ID

assurez-vous qu' Est la clé moniker est false pour chaque propriété de domaine dans la classe et ses classes de base.
1. Dans l'explorateur DÉSOLÉ, développez XML de sérialisation comportement \Class Data \ <the domain class> \Element Data.
2. vérifiez qu' Est la clé moniker est false pour chaque propriété de domaine.
3. Si la classe de domaine est une classe de base, répétez la procédure de cette classe.
définissez sérialisez l'identificateur = true pour la classe de domaine.

Cette propriété se trouve sous Comportement de sérialisation XML.

Pour définir une classe de domaine à référencer par les monikers principaux qualifiés

définissez Est la clé moniker pour une propriété de domaine d'une classe existante de domaine. le type de la propriété doit être string.
1. Dans l'explorateur DÉSOLÉ, développez XML de sérialisation comportement \Class Data \ <the domain class> \Element Data, puis sélectionnez la propriété de domaine.
2. Dans la fenêtre Propriétés, affectez Est la clé moniker à true.
- ou -

Créez une nouvelle classe de domaine à l'aide de l'outil de Domain Classe nommé .

cet outil crée une nouvelle classe qui a une propriété de domaine appelée nom. les propriétés d' Est le nom de l'élément et d' Est la clé moniker de cette propriété de domaine sont initialisées à true.
- ou -

Créez une relation d'héritage de la classe de domaine à une autre classe qui a une propriété de clé moniker.

Comment éviter les monikers en double

Si vous utilisez des monikers principaux qualifiés, il est possible que deux éléments du modèle d'un utilisateur peuvent avoir la même valeur dans la propriété de clé. Par exemple, si votre DÉSOLÉ est une personne de classe qui possède un nom de propriété, l'utilisateur peut définir les noms de deux éléments pour être le même. Bien que le modèle peut être enregistré dans le fichier, il ne se rechargerait pas correctement.

Il existe plusieurs méthodes qui permettent d'éviter cette situation :

définissez Est le nom de l'élément = true pour la propriété de domaine principale. Sélectionnez la propriété de domaine sur le diagramme de définition DÉSOLÉ puis affectez à dans la fenêtre Propriétés.

Lorsque l'utilisateur crée une nouvelle instance de la classe, les causes de cette valeur à la propriété de domaine à assigner automatiquement une valeur différente. Le comportement par défaut ajoute un nombre à la fin de le nom de la classe. Cela n'empêché pas l'utilisateur de modifier le nom à un doublon, mais aide dans le cas où l'utilisateur ne définit pas la valeur avant d'enregistrer le modèle.
Vérifiez la validation du langage spécifique à un domaine. Dans l'explorateur DÉSOLÉ, sélectionnez l'éditeur \Validation, puis définissez les propriétés d' Utilise… à true.

Il existe une méthode générée automatiquement de validation pour vérifier les ambiguïtés. la méthode est dans la catégorie de validation d' Load . Cela permet de s'assurer que l'utilisateur sera prévenu qu'il ne peut pas être possible de rouvrir le fichier.

Pour plus d'informations, consultez Validation dans un langage spécifique à un domaine.

Chemins d'accès et qualificateurs moniker

Un moniker principal qualifié se termine par la clé moniker, et a pour préfixe le moniker de son parent dans l'arborescence d'incorporation. par exemple, si le moniker d'un album est :

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

L'une des chansons de cet album peut être :

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

Toutefois, si des albums sont référencés par l'ID à la place, les monikers serait la suivante :

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

Notez que lorsque le GUID est unique, il n'est jamais préfixé par le moniker de son parent.

si vous savez qu'une propriété de domaine particulière aura toujours une valeur unique dans un modèle, vous pouvez définir Est le qualificateur moniker à true pour cette propriété. Cela provoquera le à utiliser en tant que qualificateur, sans utiliser le moniker du parent. Par exemple, si vous Est le qualificateur moniker défini et Est la clé moniker pour la propriété de champ de titre de la classe de l'album, le nom du modèle ou identificateur n'est pas utilisé dans les monikers pour l'album et ses enfants incorporés :

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

Personnaliser la structure XML

Pour que les personnalisations, développez le nœud de Comportement de sérialisation XML dans l'explorateur DÉSOLÉ. Sous une classe de domaine, développez le nœud de données d'élément pour afficher la liste de propriétés et de relations qui sont générés à cette classe. Sélectionnez une relation et ajustez ses options dans la fenêtre Propriétés.

Définissez omettez l'élément true pour omettre le rôle de nœud de la source, en conservant uniquement la liste d'éléments cibles. Vous ne devez pas définir cette option s'il existe plusieurs relation entre la source et les classes de cible.
```
<familyTreeModel ...>
  
  
    <person name="Henry VIII" .../>
    <person name="Elizabeth I" .../>
  
</familyTreeModel>
```

Définissez Forme complète d'utilisation pour inclure les nœuds cibles dans des nœuds qui représentent les instances de relation. Cette option est définie automatiquement lorsque vous ajoutez des propriétés de domaine à une relation de domaine.

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

Définissez représentation = élément pour avoir une propriété de domaine enregistrée en tant qu'élément et non comme valeur d'attribut.
```
<person name="Elizabeth I" birthYear="1533">
  <deathYear>1603</deathYear>
</person>
```
Pour modifier l'ordre dans lequel les attributs et les relations sont sérialisées, cliquez avec le bouton droit sur un élément sous des données d'élément, et utilisez les commandes de menu de Monter ou de Descendre .

Personnalisation principale à l'aide de le code du programme

Vous pouvez remplacer des parties ou tous les algorithmes de sérialisation.

Il est recommandé d'examiner le code dans Dsl\Generated Code\Serializer.cs et SerializationHelper.cs.

pour personnaliser la sérialisation d'une classe particulière

Définissez est personnalisé dans le nœud de cette classe sous Comportement de sérialisation XML.
Transformez tous les modèles, générez la solution, puis recherchez les erreurs de compilation résultant. Les commentaires à l'approche de chaque erreur expliquent le code vous devez fournir.

Pour fournir votre propre sérialisation pour celles modélisez

Substituent les méthodes de DÉSOLÉ \GeneratedCode\SerializationHelper .cs

Options du comportement de sérialisation XML

Dans l'explorateur DÉSOLÉ, le nœud du comportement de sérialisation XML contient un nœud enfant pour chaque classe de classe, de relation, de forme, de connecteur et de diagrammes de domaine. Sous chacun de ces nœuds est une liste de propriétés et de relations générés à cet élément. Les relations sont représentées de leur propre chef et sous leurs classes de source.

Le tableau suivant résume les options que vous pouvez définir dans cette section de la définition de langage spécifique à un domaine. Dans chaque cas, sélectionnez un élément dans l'explorateur DÉSOLÉ, puis définissez les options dans la fenêtre Propriétés.

Données de classe XML

Ces éléments sont détectés dans l'explorateur DÉSOLÉ sous Comportement \Class Data de sérialisation XML.

Propriété	Description
a le schéma d'élément personnalisé	Si la valeur true, indique que la classe de domaine est un schéma d'élément personnalisé
est personnalisé	Définissez ce paramètre la valeur true pour écrire votre propre code de sérialisation et de désérialisation pour cette classe de domaine. Générez la solution et recherchez les erreurs pour découvrir détaillées.
classe de domaine	Classe de domaine à laquelle ce nœud de données de classe s'applique. En lecture seule.
Nom de l'élément	Nom du nœud XML pour les éléments de cette classe. La valeur par défaut est une version minuscule du nom de classe de domaine.
Nom de l'attribut moniker	Nom de l'attribut utilisé dans les constructions moniker pour contenir la référence. si l'espace, le nom de la propriété de clé ou l'identificateur est utilisé. Dans cet exemple, il s'agit de « nom » : <personMoniker name="/Mike Nash"/>
Nom d'élément moniker	Nom de l'élément XML utilisé pour les monikers qui font référence à des éléments de cette classe. La valeur par défaut est une version minuscule du nom de classe avec le suffixe par « moniker ». Par exemple, personMoniker.
Nom de type moniker	Nom du type XSD généré pour les monikers aux éléments de cette classe. XSD est dans *Dsl\Generated Code\Schema.xsd**
sérialisez l'identificateur	Si True, l'élément GUID est inclus dans le fichier. Cela doit être respectée s'il n'y a aucune propriété qui est Est la clé moniker marquée et le code DÉSOLÉ définit des relations de référence à cette classe.
Nom de type	Nom du type XML généré dans XSD de la classe indiquée de domaine.
Remarques	Remarques informelles associées à cet élément

Données de propriété XML

Des nœuds de propriété XML se trouvent sous les nœuds de classe.

Propriété	Description
propriété de domaine	Propriété à laquelle les données de configuration de sérialisation XML s'applique. En lecture seule.
Est la clé moniker	si True, la propriété est utilisé comme clé pour créer les monikers qui référencent des instances de cette classe de domaine.
Est le qualificateur moniker	si True, la propriété est utilisé pour créer le qualificateur dans les monikers. Si la valeur false, et si SerializeId ne convient pas pour les classes de domaine, des monikers sont qualifiées par le moniker de l'élément parent dans l'arborescence d'incorporation.
Représentation	Si l'attribut, la propriété est sérialisé en tant qu'attribut XML ; si l'élément, il est sérialisé en tant qu'élément ; si ignorez, il n'est pas sérialisé.
Nom XML	Nommez utilisé pour l'attribut ou l'élément XML représentant la propriété. Par défaut, il s'agit d'une version minuscule du nom de la propriété de domaine.
Remarques	Remarques informelles associées à cet élément

Données de rôle XML

Des nœuds de données de rôle sont recherchés sous les nœuds de classe source.

Propriété	Description
a le moniker personnalisé	Définissez ce paramètre la valeur true si vous souhaitez fournir votre propre code pour générer et résoudre les monikers qui parcourent cette relation. Pour obtenir des instructions détaillées, générez la solution, puis double-cliquez sur les messages d'erreur.
relation de domaine	spécifie la relation à laquelle ces options s'appliquent. En lecture seule.
omettez l'élément	Si la valeur true est affectée, le nœud XML qui correspond au rôle de source est omis du schéma. S'il existe plusieurs relation entre la source et les classes de cible, ce rôle de nœud respecte les liens qui appartiennent aux deux relations. Nous vous recommandons donc que vous ne définissez pas cette option dans ce cas.
Nom de rôle d'élément	spécifie le nom de l'élément XML qui est dérivé du rôle de source. La valeur par défaut est le nom de rôle de la propriété.
Forme complète d'utilisation	Si la valeur true est affectée, chaque élément ou moniker cible est placé dans un nœud XML qui représente la relation. Cela doit avoir la valeur true si la relation possède ses propres propriétés de domaine.

Partager via