Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Une solution Domain-Specific Language (DSL) génère une API que vous pouvez utiliser pour lire et mettre à jour des instances de DSL dans Visual Studio. Cette API est définie dans le code généré à partir de la définition DSL. Cette rubrique décrit l’API générée.
L’exemple de solution : Diagrammes de composants
Pour créer la solution source de la plupart des exemples de cette rubrique, créez une DSL à partir du modèle de solution Modèles de composants . Il s’agit de l’un des modèles standard qui s’affichent lorsque vous créez une solution DSL.
Note
Le modèle DSL des diagrammes de composants est appelé Domain-Specific Language Designer.
Appuyez sur F5 et testez si vous n’êtes pas familiarisé avec ce modèle de solution. Notez en particulier que vous créez des ports en faisant glisser un outil de port sur un composant, et que vous pouvez connecter des ports.
Structure de la solution DSL
Le projet Dsl définit l’API de votre DSL. Le projet DslPackage définit comment il s’intègre à Visual Studio. Vous pouvez également ajouter vos propres projets, qui peuvent également contenir du code généré à partir du modèle.
Répertoires de code
La plupart du code de chacun de ces projets est généré à partir de Dsl\DslDefinition.dsl. Le code généré se trouve dans le dossier Code généré . Pour afficher un fichier généré, cliquez sur [+] en regard du fichier .tt généré.
Nous vous recommandons d’inspecter le code généré pour vous aider à comprendre la DSL. Pour afficher les fichiers générés, développez les fichiers *.tt dans l’Explorateur de solutions.
Les fichiers *.tt contiennent très peu de code de génération. Au lieu de cela, ils utilisent des directives <#include> pour inclure des fichiers de modèle partagés. Les fichiers partagés se trouvent dans \Program Files\Microsoft Visual Studio 10.0\Common7\IDE\Extensions\Microsoft\DSL SDK\DSL Designer\11.0\TextTemplates
Lorsque vous ajoutez votre propre code de programme à la solution DSL, ajoutez-le dans un fichier distinct, en dehors du dossier Code généré. Vous pouvez créer un dossier Code personnalisé . (Lorsque vous ajoutez un nouveau fichier de code à un dossier personnalisé, n’oubliez pas de corriger l’espace de noms dans le squelette de code initial.)
Nous vous recommandons vivement de ne pas modifier directement le code généré, car vos modifications seront perdues lors de la reconstruction de la solution. Au lieu de cela, pour personnaliser votre DSL :
Ajustez les nombreux paramètres dans la définition DSL.
Écrivez des classes partielles dans des fichiers de code distincts, pour remplacer les méthodes définies ou héritées par les classes générées. Dans certains cas, vous devez définir l’option Generates Double Derived d’une classe dans la définition DSL afin de pouvoir remplacer une méthode générée.
Définissez des options dans la définition DSL qui entraînent le code généré pour fournir des « hooks » pour votre propre code.
Par exemple, si vous définissez l’option Has Custom Constructor d’une classe de domaine, puis générez la solution, vous verrez des messages d’erreur. Lorsque vous double-cliquez sur l’un de ces messages d’erreur, vous verrez des commentaires dans le code généré qui expliquent ce que votre code personnalisé doit fournir.
Écrivez vos propres modèles de texte pour générer du code spécifique à votre application. Vous pouvez utiliser des fichiers include pour partager des parties des modèles communs à de nombreux projets, et vous pouvez créer des modèles de projet Visual Studio pour configurer des projets initialisés avec votre propre structure de fichiers.
Fichiers générés dans Dsl
Les fichiers générés suivants apparaissent dans le projet Dsl .
YourDslSchema.xsd
Schéma pour les fichiers qui contiennent des instances de votre DSL. Ce fichier est copié dans le répertoire de compilation (bin). Lorsque vous installez votre DSL, vous pouvez copier ce fichier dans \Program Files\Microsoft Visual Studio 11.0\Xml\Schemas afin que les fichiers de modèle puissent être validés. Pour plus d’informations, consultez Déploiement de solutions linguistiques Domain-Specific.
Si vous personnalisez la sérialisation en définissant des options dans l’Explorateur DSL, le schéma change en conséquence. Toutefois, si vous écrivez votre propre code de sérialisation, ce fichier peut ne plus représenter le schéma réel. Pour plus d’informations, consultez Personnalisation du stockage de fichiers et de la sérialisation XML.
ConnectionBuilders.cs
Un générateur de connexions est une classe qui crée des relations. Il s’agit du code derrière un outil de connexion. Ce fichier contient une paire de classes pour chaque outil de connexion. Leurs noms sont dérivés des noms de l’outil de relation de domaine et de connexion : Générateur de relationset ConnectorToolConnectAction.
(Dans l’exemple de solution de composant, l’un des générateurs de connexions est appelé ConnectionBuilder, c’est une coïncidence, car la relation de domaine est nommée Connection.)
La relation est créée dans la méthode RelationBuilder.Connect() . La version par défaut vérifie que les éléments du modèle source et cible sont acceptables, puis instancie la relation. Par exemple:
CommentReferencesSubject(sourceAccepted, targetAccepted);
Chaque classe de générateur est générée à partir d’un nœud dans la section Générateurs de connexions dans l’Explorateur DSL. Une Connect méthode peut créer des relations entre une ou plusieurs paires de classes de domaine. Chaque paire est définie par une directive Link Connect, que vous pouvez trouver dans l’Explorateur DSL sous le nœud du générateur.
Par exemple, vous pouvez ajouter à un générateur de connexions des directives link connect pour chacun des trois types de relation dans l’exemple de DSL. Cela permet à l’utilisateur d’utiliser un seul outil de connexion. Le type de relation instancié dépend des types des éléments source et cible sélectionnés par l’utilisateur. Pour ajouter des directives de connexion de liens, cliquez avec le bouton droit sur un générateur dans l’Explorateur DSL.
Pour écrire du code personnalisé qui s’exécute lorsqu’un type spécifique de relation de domaine est créé, sélectionnez la directive de connexion de liens appropriée sous le nœud du générateur. Dans la fenêtre Propriétés, définissez Utilise Custom Connect. Régénérez la solution, puis fournissez du code pour corriger les erreurs résultantes.
Pour écrire du code personnalisé qui s’exécute chaque fois que l’utilisateur utilise cet outil de connexion, définissez la propriété Is Custom du générateur de connexions. Vous pouvez fournir du code qui détermine si un élément source est autorisé, si une combinaison spécifique de source et de cible est autorisée et quelles mises à jour doivent être apportées au modèle lorsqu’une connexion est établie. Par exemple, vous pouvez autoriser une connexion uniquement si elle ne créerait pas de boucle dans le diagramme. Au lieu d’un lien de relation unique, vous pouvez instancier un modèle plus complexe de plusieurs éléments liés entre la source et la cible.
Connectors.cs
Contient les classes des connecteurs, qui sont les éléments de diagramme qui représentent généralement des relations de référence. Chaque classe est générée à partir d’un connecteur dans la définition DSL. Chaque classe de connecteur est dérivée de BinaryLinkShape
Pour rendre la couleur et d’autres caractéristiques de style variables au moment de l’exécution, cliquez avec le bouton droit sur la classe dans le diagramme de définition DSL et sélectionnez Ajouter exposé.
Pour rendre des fonctionnalités de style supplémentaires variables au moment de l’exécution, consultez par exemple TextField et ShapeElement.
Diagram.cs
Contient la classe qui définit le diagramme. Elle est dérivée de Diagram.
Pour rendre la couleur et d’autres caractéristiques de style variables au moment de l’exécution, cliquez avec le bouton droit sur la classe dans le diagramme de définition DSL et pointez sur Ajouter exposé.
De plus, ce fichier contient la FixupDiagram règle, qui répond lorsqu’un nouvel élément est ajouté au modèle. La règle ajoute une nouvelle forme et lie la forme à l’élément de modèle.
DirectiveProcessor.cs
Ce processeur de directive permet à vos utilisateurs d’écrire des modèles de texte qui lisent une instance de votre DSL. Le processeur de directives charge les assemblies (DLL) pour votre DSL et insère efficacement des déclarations using pour votre espace de noms. Cela permet au code dans les modèles de texte d’utiliser les classes et relations que vous avez définies dans votre DSL.
Pour plus d’informations, consultez Génération de code à partir d’un langage Domain-Specific et création de processeurs de directive de modèle de texte T4 personnalisés.
DomainClasses.cs
Implémentations de classes de domaine que vous avez définies, y compris les classes abstraites et la classe racine du modèle. Ils sont dérivés de ModelElement.
Chaque classe de domaine contient :
Définition de propriété et classe de gestionnaire imbriquée pour chaque propriété de domaine. Vous pouvez remplacer OnValueChanging() et OnValueChanged(). Pour plus d’informations, consultez Gestionnaires de modification de valeur de propriété de domaine.
Dans l’exemple DSL, la
Commentclasse contient une propriétéTextet une classeTextPropertyHandlerde gestionnaire .Propriétés d’accesseur pour les relations dans lesquelles cette classe de domaine participe. (Il n’existe aucune classe imbriquée pour les propriétés de rôle.)
Dans l’exemple de DSL, la
Commentclasse a des accesseurs qui accèdent à son modèle parent via la relationComponentModelHasCommentsd’incorporation.Constructeurs. Si vous souhaitez les remplacer, définissez Has Custom Constructor sur la classe de domaine.
Méthodes de gestionnaire EGP (Element Group Prototype). Ces éléments sont nécessaires si l’utilisateur peut fusionner (ajouter) un autre élément sur des instances de cette classe. En règle générale, l’utilisateur effectue cette opération en glissant-déposant depuis un outil d’éléments ou une autre forme, ou en collant.
Dans l’exemple de DSL, un port d’entrée ou un port de sortie peut être fusionné sur un composant. En outre, les composants et les commentaires peuvent être fusionnés sur le modèle. Les
Les méthodes de gestionnaire EGP de la classe Component permettent à un composant d’accepter les ports, mais pas les commentaires. Le gestionnaire EGP de la classe de modèle racine accepte les commentaires et les composants, mais pas les ports.
DomainModel.csClasse qui représente le modèle de domaine. Elle est dérivée de DomainModel.
Note
Ce n’est pas le même que la classe racine du modèle.
Les fermetures de copie et de suppression définissent les autres éléments à inclure lorsqu’un élément est copié ou supprimé. Vous pouvez contrôler ce comportement en définissant les propriétés Propagation de la copie et Propagation de la suppression des rôles de chaque côté de chaque relation. Si vous souhaitez que les valeurs soient déterminées dynamiquement, vous pouvez écrire du code pour remplacer les méthodes des classes De fermeture.
DomainModelResx.resx
Cela contient des chaînes telles que les descriptions des classes et propriétés de domaine, des noms de propriétés, des étiquettes de boîte à outils, des messages d’erreur standard et d’autres chaînes qui peuvent être affichées à l’utilisateur. Il contient également des icônes d’outils et des images pour les formes d’image.
Ce fichier est lié à l’assembly intégré et fournit les valeurs par défaut de ces ressources. Vous pouvez localiser votre DSL en créant un assembly satellite qui contient une version localisée des ressources. Cette version sera utilisée lorsque la DSL est installée dans une culture correspondant aux ressources localisées. Pour plus d’informations, consultez Déploiement de solutions linguistiques Domain-Specific.
DomainRelationships.cs
Chaque lien entre deux éléments dans un modèle est représenté par une instance d’une classe de relation de domaine. Toutes les classes de relation sont dérivées de ElementLink, qui à leur tour est dérivée de ModelElement. Étant donné qu’il s’agit d’un ModelElement, une instance d’une relation peut avoir des propriétés et peut être la source ou la cible d’une relation.
HelpKeywordHelper.cs
Fournit des fonctions utilisées lorsque l’utilisateur appuie sur F1.
MultiplicityValidation.cs
Dans les rôles de relation où vous spécifiez une multiplicité de 1..1 ou 1..*, l’utilisateur doit être averti qu’au moins une instance de la relation est requise. Ce fichier fournit des contraintes de validation qui implémentent ces avertissements. Le lien 1..1 vers un parent intégré n’est pas vérifié.
Pour que ces contraintes soient exécutées, vous devez avoir défini l’une des options Use... dans le nœud Editor\Validation dans l’Explorateur DSL. Pour plus d’informations, consultez Validation dans une langue Domain-Specific.
PropertiesGrid.cs
Ce fichier contient du code uniquement si vous avez attaché un descripteur de type personnalisé à une propriété de domaine. Pour plus d’informations, consultez Personnalisation de la fenêtre Propriétés.
SerializationHelper.cs
Méthode de validation pour s’assurer qu’aucun deux éléments ne sont référencés par le même moniker. Pour plus d’informations, consultez Personnalisation du stockage de fichiers et de la sérialisation XML.
Classe SerializationHelper, qui fournit des fonctions utilisées en commun par les classes de sérialisation.
Serializer.csClasse de sérialiseur pour chaque classe de domaine, relation, forme, connecteur, diagramme et modèle.
La plupart des fonctionnalités de ces classes peuvent être contrôlées par les paramètres de l’Explorateur DSL sous Comportement de sérialisation Xml.
Shapes.csClasse pour chaque classe de forme dans la définition DSL. Les formes sont dérivées de NodeShape. Pour plus d’informations, consultez Personnalisation du stockage de fichiers et de la sérialisation XML.
Pour remplacer les méthodes générées par vos propres méthodes dans une classe partielle, définissez Generates Double Derived pour le connecteur dans la définition DSL. Pour remplacer un constructeur par votre propre code, définissez un constructeur personnalisé.
Pour rendre la couleur et d’autres caractéristiques de style variables au moment de l’exécution, cliquez avec le bouton droit sur la classe dans le diagramme de définition DSL et pointez sur Ajouter exposé.
Pour rendre des fonctionnalités de style supplémentaires variables au moment de l’exécution, consultez par exemple TextField et ShapeElement
ToolboxHelper.csConfigure la boîte à outils en installant des prototypes de groupes d'éléments dans les outils d'élément. Les copies de ces prototypes sont fusionnées avec les éléments cibles lorsque l’utilisateur exécute l’outil.
Vous pouvez remplacer
CreateElementPrototype()pour définir un élément de boîte à outils qui crée un groupe de plusieurs objets. Par exemple, vous pouvez définir un élément pour représenter des objets qui ont des sous-composants. Après avoir modifié le code, réinitialisez l’instance expérimentale de Visual Studio pour effacer le cache de boîte à outils.
Fichiers générés dans le projet DslPackage
DslPackage couple le modèle DSL à l’interpréteur de commandes Visual Studio, en gérant la fenêtre, la boîte à outils et les commandes de menu. La plupart des classes sont double dérivées, ce qui vous permet de remplacer l’une de leurs méthodes.
CommandSet.cs
Commandes de menu en cliquant avec le bouton droit qui sont visibles dans le diagramme. Vous pouvez adapter ou ajouter à cet ensemble. Ce fichier contient le code des commandes. L’emplacement des commandes dans les menus est déterminé par le fichier Commands.vsct. Pour plus d’informations, consultez Écriture de commandes et d’actions utilisateur.
Constants.cs
GUIDs
DocData.cs
YourDslDocData gère le chargement et l’enregistrement d’un modèle dans un fichier et crée l’instance du Windows Store.
Par exemple, si vous souhaitez enregistrer votre DSL dans une base de données au lieu d’un fichier, vous pouvez remplacer les méthodes Load et Save.
DocView.cs
YourDslDocView gère la fenêtre dans laquelle le diagramme apparaît. Par exemple, vous pouvez incorporer le diagramme à l’intérieur d’un formulaire Windows :
Ajoutez un fichier de contrôle utilisateur au projet DslPackage. Ajoutez un panneau dans lequel le diagramme peut être affiché. Ajouter des boutons et d’autres contrôles. Dans la vue de code du formulaire, ajoutez le code suivant et ajustez les noms selon votre DSL :
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Drawing;
using System.Data;
using System.Linq;
using System.Text;
using System.Windows.Forms;
using Microsoft.VisualStudio.Modeling;
using Microsoft.VisualStudio.Modeling.Shell;
namespace Company.EmbedInForm
{
public partial class UserControl1 : UserControl
{
public UserControl1()
{
InitializeComponent();
}
private DiagramDocView docView;
public UserControl1(DiagramDocView docView, Control content)
: this()
{
this.docView = docView;
panel1.Controls.Add(content);
}
private void button1_Click(object sender, EventArgs e)
{
ExampleModel modelRoot = this.docView.CurrentDiagram.ModelElement as ExampleModel;
foreach (ExampleElement element in modelRoot.Elements)
{
listBox1.Items.Add(element.Name);
}
}
}
internal partial class EmbedInFormDocView
{
private ContainerControl container;
/// <summary>
/// Return a User Control instead of the DSL window.
/// The user control will contain the DSL window.
/// </summary>
public override System.Windows.Forms.IWin32Window Window
{
get
{
if (container == null)
{
// Put the normal DSL Window inside our control
container = new UserControl1(this, (Control)base.Window);
}
return container;
}
}
}
}
EditorFactory.cs
Instancie DocData et DocView. Il répond à une interface standard utilisée par Visual Studio pour ouvrir un éditeur au démarrage de votre package DSL. Il est référencé dans l’attribut ProvideEditorFactory dans Package.cs
GeneratedVSCT.vsct
Localise les commandes de menu standard sur les menus, comme le menu contextuel accessible par clic droit (menu contextuel du diagramme), le menu Modifier, etc. Le code des commandes se trouve dans CommandSet.cs. Vous pouvez déplacer ou modifier les commandes standard et ajouter vos propres commandes. Pour plus d’informations, consultez Écriture de commandes et d’actions utilisateur.
ModelExplorer.cs
Définit l’Explorateur de modèles pour votre DSL. Il s’agit de l’arborescence du modèle que l’utilisateur voit en même temps que le diagramme.
Par exemple, vous pouvez remplacer InsertTreeView() pour modifier l’ordre dans lequel les éléments apparaissent dans l’Explorateur de modèles.
Si vous souhaitez que la sélection dans l’Explorateur de modèles reste synchronisée avec la sélection du diagramme, vous pouvez utiliser le code suivant :
protected override void OnSelectionChanged(global::System.EventArgs e)
{
base.OnSelectionChanged(e);
// get the selected element
DslModeling::ModelElement selectedElement =
this.PrimarySelection as DslModeling::ModelElement;
// Select in the model explorer
SelectInModelExplorer<YOURLANGUAGEExplorerToolWindow>(selectedElement);
}
private void SelectInModelExplorer<T>(DslModeling::ModelElement modelElement)
where T : DslShell.ModelExplorerToolWindow
{
DslShell::ModelingPackage package =
this.GetService(typeof(VSShell.Package)) as DslShell::ModelingPackage;
if (package != null)
{
// find the model explorer window
T explorerWindow = package.GetToolWindow(typeof(T), true) as T;
if (explorerWindow != null)
{
// get the tree container
DslShell.ModelExplorerTreeContainer treeContainer =
explorerWindow.TreeContainer;
// find the tree node
DslShell.ExplorerTreeNode treeNode =
treeContainer.FindNodeForElement(modelElement);
// select the node
explorerWindow.TreeContainer.ObjectModelBrowser.SelectedNode = treeNode;
}
}
}
ModelExplorerToolWindow.cs
Définit la fenêtre dans laquelle l’Explorateur de modèles s’affiche. Gère la sélection d’éléments dans l’Explorateur.
Package.cs
Ce fichier définit la façon dont la DSL s’intègre à Visual Studio. Les attributs de la classe de package inscrivent le DSL en tant que gestionnaire pour les fichiers qui ont votre extension de fichier, définissent sa boîte à outils et définissent comment ouvrir une nouvelle fenêtre. La méthode Initialize() est appelée une fois lorsque la première DSL est chargée dans une instance de Visual Studio.
Source.extension.vsixmanifest
Pour personnaliser ce fichier, modifiez le .tt fichier.
Avertissement
Si vous modifiez le fichier .tt pour inclure des ressources telles que des icônes ou des images, vérifiez que la ressource est incluse dans la build VSIX. Dans l’Explorateur de solutions, sélectionnez le fichier et vérifiez que la propriété Include dans VSIX est True.
Ce fichier contrôle la façon dont la DSL est empaquetée dans une extension d’intégration Visual Studio (VSIX). Pour plus d’informations, consultez Déploiement de solutions linguistiques Domain-Specific.