Intégration de modèles à l'aide de Visual Studio ModelbusIntegrating Models by using Visual Studio Modelbus

Visual StudioVisual Studio ModelBus fournit une méthode de création de liens entre les modèles et d’autres outils dans les modèles. ModelBus provides a method for creating links between models and from other tools into models. Par exemple, vous pouvez lier les modèles linguistiques de spécifique à un domaine (DSL) et des modèles UML.For example, you could link domain-specific language (DSL) models and UML models. Vous pouvez créer un ensemble intégré de DSL.You can create an integrated set of DSLs.

ModelBus vous permet de créer une référence unique à un modèle ou à un élément spécifique à l'intérieur d'un modèle.ModelBus lets you create a unique reference to a model or to a specific element inside a model. Cette référence peut être stockée en dehors du modèle : dans un élément d'un autre modèle, par exemple.This reference can be stored outside the model, for example, in an element in another model. Quand, en une occasion ultérieure, un outil veut obtenir un accès à l'élément, l'infrastructure de bus de modèles charge le modèle approprié et retourne l'élément.When, on a later occasion, a tool wants to obtain access to the element, the Model Bus infrastructure will load the appropriate model and return the element. Si vous le désirez, vous pouvez afficher le modèle pour l'utilisateur.If you want, you can display the model to the user. S'il n'est pas possible d'accéder au fichier dans son emplacement précédent, ModelBus demande à l'utilisateur de le rechercher.If the file cannot be accessed in its previous location, ModelBus will ask the user to find it. Si l'utilisateur trouve le fichier, ModelBus corrige toutes les références au fichier.If the user finds the file, ModelBus will fix all the references to that file.

Note

Dans l'implémentation Visual StudioVisual Studio actuelle de ModelBus, les modèles liés doivent être des éléments de la même solution Visual StudioVisual Studio.In the current Visual StudioVisual Studio implementation of ModelBus, the linked models must be items in the same Visual StudioVisual Studio solution.

Pour obtenir plus d'informations et des exemples de code, voir :For additional information and sample code, see:

---

Dans Visual Studio 2017, le SDK de Transformation de modèle de texte et le SDK de modélisation de Visual Studio sont installés automatiquement lorsque vous installez des fonctionnalités spécifiques de Visual Studio.In Visual Studio 2017, the Text Template Transformation SDK and the Visual Studio Modeling SDK are installed automatically when you install specific features of Visual Studio. Pour plus d’informations, consultez ce billet de blog.For more details, see this blog post.

Fournir un accès à une DSLProviding Access to a DSL

Avant de créer les références ModelBus à un modèle ou à ses éléments, vous devez définir un ModelBusAdapter pour le DSL.Before you can create ModelBus references to a model or its elements, you must define a ModelBusAdapter for the DSL. La solution la plus simple consiste à utiliser l'extension Visual StudioVisual Studio Model Bus, qui ajoute les commandes au concepteur DSL.The easiest way to do this is to use the Visual StudioVisual Studio Model Bus Extension, which adds commands to the DSL Designer.

Pour exposer une définition DSL de Bus de modèlesTo expose a DSL Definition to Model Bus

  1. Téléchargez et installez l'extension Visual Studio Model Bus, à moins que vous ne l'ayez déjà fait.Download and install the Visual Studio Model Bus extension, unless you have already installed it. Pour plus d’informations, consultez Visualization and Modeling SDK.For more information, see Visualization and Modeling SDK.

  2. Ouvrez le fichier de définition DSL.Open the DSL definition file. Cliquez sur l’aire de conception, puis sur activer un Modelbus.Right-click the design surface and then click Enable Modelbus.

  3. Dans la boîte de dialogue, choisissez souhaitée exposer ce DSL pour le ModelBus.In the dialog box, choose I want to expose this DSL to the ModelBus. Vous pouvez choisir les deux options si vous voulez que ce DSL expose ses modèles et consomme les références aux autres DSL.You can choose both options if you want this DSL both to expose its models and to consume references to other DSLs.

  4. Cliquez sur OK.Click OK. Un nouveau projet « ModelBusAdapter » vient s'ajouter à la solution DSL.A new project "ModelBusAdapter" is added to the DSL solution.

  5. Si vous voulez accéder au DSL à partir d'un modèle de texte, vous devez modifier AdapterManager.tt dans le nouveau projet.If you want to access the DSL from a text template, you must modify AdapterManager.tt in the new project. Ignorez cette étape si vous voulez accéder au DSL à partir d'un autre code, tel que celui des commandes ou gestionnaires d'événements.Omit this step if you want to access the DSL from other code such as commands and event handlers. Pour plus d’informations, consultez à l’aide de Visual Studio ModelBus dans un modèle de texte.For more information, see Using Visual Studio ModelBus in a Text Template.

    1. Modifiez la classe de base d'AdapterManagerBase en VsTextTemplatingModelingAdapterManager.Change the base class of AdapterManagerBase to VsTextTemplatingModelingAdapterManager.

    2. Vers la fin du fichier, insérez cet attribut additionnel devant la classe AdapterManager :Near the end of the file, insert this additional attribute in front of class AdapterManager:

      [Microsoft.VisualStudio.Modeling.Integration.HostSpecific(HostName)]

    3. Ajoutez au projet des références de ModelBusAdapter, Microsoft.VisualStudio.TextTemplating.Modeling.11.0.In the References of ModelBusAdapter project, add Microsoft.VisualStudio.TextTemplating.Modeling.11.0.

      Pour accéder au DSL à partir de modèles de texte et d'un autre code, vous avez besoin de deux adaptateurs, l'un modifié et l'autre non modifié.If you want to access the DSL both from text templates and from other code, you need two adapters, one modified and one unmodified.

  6. Cliquez sur transformer tous les modèles.Click Transform All Templates.

  7. Régénérez la solution.Rebuild the solution.

    Il est désormais possible pour ModelBus d'ouvrir des instances de ce DSL.It is now possible for ModelBus to open instances of this DSL.

    Le dossier ModelBusAdapters\bin\* contient les assemblys générés par les projets Dsl et ModelBusAdapters.The folder ModelBusAdapters\bin\* contains the assemblies built by the Dsl project and the ModelBusAdapters project. Pour faire référence à ce DSL à partir d'un autre DSL, vous devez importer ces assemblys.To reference this DSL from another DSL, you should import these assemblies.

S'assurer que les éléments peuvent être référencésMaking sure that elements can be referenced

Visual StudioVisual Studio Par défaut, les adaptateurs ModelBus utilisent le GUID d'un élément pour l'identifier. ModelBus adapters use the guid of an element to identify it, by default. Par conséquent, ces identificateurs doivent être conservés dans le fichier de modèle.These identifiers must therefore be persisted in the model file.

Pour s'assurer que les ID d'élément sont conservésTo ensure that element IDs are persisted
  1. Ouvrez DslDefinition.dsl.Open DslDefinition.dsl.

  2. Dans l’Explorateur DSL, développez comportement de sérialisation Xml, puis les données de classe.In DSL Explorer, expand Xml Serialization Behavior, then Class Data.

  3. Pour chaque classe pour laquelle vous voulez créer des références de bus de modèles :For each class to which you want to create Model Bus references:

    Cliquez sur le nœud de classe et dans la fenêtre Propriétés, assurez-vous que Id de sérialiser a la valeur true.Click the class node, and in the Properties window, make sure that Serialize Id is set to true.

    Une autre solution, si vous voulez utiliser le nom d'élément à la place du GUID pour identifier l'élément, consiste à remplacer certaines parties des adaptateurs générés.Alternatively, if you want to use element names to identify elements instead of guids, you can override parts of the generated adapters. Remplacez les méthodes suivantes dans la classe d'adaptateur :Override the following methods in the adapter class:

  • Remplacez GetElementId pour retourner l'identificateur que vous voulez utiliser.Override GetElementId to return the identifier you want to use. Cette méthode est appelée lors de la création de références.This method is called when creating references.

  • Remplacez ResolveElementReference pour rechercher l'élément approprié à partir d'une référence de bus de modèles.Override ResolveElementReference to locate the correct element from a Model Bus reference.

L’accès à une DSL à partir d’un autre DSLAccessing a DSL from another DSL

Vous pouvez stocker les références de bus de modèles dans une propriété de domaine d'un DSL et vous pouvez écrire le code personnalisé qui les utilise.You can store model bus references in a domain property in a DSL, and you can write custom code that uses them. Vous pouvez aussi laisser l'utilisateur créer une référence de bus de modèles en sélectionnant un fichier de modèle, ainsi qu'un élément à l'intérieur du modèle.You can also let the user create a model bus reference by picking a model file and an element within it.

Pour activer une DSL faire référence à un autre DSL, vous devez d’abord le vous un consommateur de références de bus de modèle.To enable a DSL to use references to another DSL, you should first make it a consumer of model bus references.

Pour permettre à un DSL de consommer les références à un DSL exposéTo enable a DSL to consume references to an exposed DSL

  1. Dans le diagramme de définition DSL, avec le bouton droit de la partie principale du diagramme, puis activer un Modelbus.In the DSL Definition diagram, right-click the main part of the diagram and then click Enable Modelbus.

  2. Dans la boîte de dialogue, sélectionnez activer ce modèle consommer des références de bus de modèle.In the dialog box, select I want to enable this model to consume model bus references.

  3. Dans le projet DSL du DSL consommateur, ajoutez les assemblys suivants aux références du projet.In the Dsl project of the consuming DSL, add the following assemblies to the project references. Vous trouverez ces assemblys (fichiers .dll) dans le ModelBusAdapter\bin\* de la DSL exposée.You will find these assemblies (.dll files) in the ModelBusAdapter\bin\* directory of the exposed DSL.

    • L’assembly DSL exposé, par exemple Fabrikam.FamilyTree.Dsl.dllThe exposed DSL assembly, for example Fabrikam.FamilyTree.Dsl.dll

    • Le modèle exposé bus assembly d’adaptateur, par exemple Fabrikam.FamilyTree.ModelBusAdapter.dllThe exposed model bus adapter assembly, for example Fabrikam.FamilyTree.ModelBusAdapter.dll

  4. Ajoutez les assemblys .NET suivants aux références de projet du projet DSL consommateur.Add the following .NET assemblies to the project references of the consuming DSL project.

    1. Microsoft.VisualStudio.Modeling.Sdk.Integration.11.0.dllMicrosoft.VisualStudio.Modeling.Sdk.Integration.11.0.dll

    2. Microsoft.VisualStudio.Modeling.Sdk.Integration.Shell.11.0.dllMicrosoft.VisualStudio.Modeling.Sdk.Integration.Shell.11.0.dll

Pour stocker une référence de bus de modèles dans une propriété de domaineTo store a Model Bus Reference in a domain property

  1. Dans la définition DSL du DSL consommateur, ajoutez une propriété de domaine à une classe de domaine et définissez son nom.In the DSL Definition of the consuming DSL, add a domain property to a domain class and set its name.

  2. Dans les fenêtre Propriétés, avec la propriété du domaine sélectionnée, définissez Type à ModelBusReference.In the Properties window, with the domain property selected, set Type to ModelBusReference.

    À ce stade, le code de programme peut définir la valeur de la propriété, mais elle est en lecture seule dans la fenêtre Propriétés.At this stage, program code can set the property value, but it is read-only in the Properties window.

    Vous pouvez permettre aux utilisateurs de définir la propriété avec un éditeur de références ModelBus spécialisé.You can allow users to set the property with a specialized ModelBus reference editor. Il existe deux versions de cet éditeur ou sélecteur : une permet aux utilisateurs de choisir un fichier de modèle, et l’autre permet aux utilisateurs de choisir un fichier de modèle et un élément dans le modèle.There are two versions of this editor or picker: one allows users to choose a model file, and the other allows users to choose a model file and an element within the model.

Pour permettre à l'utilisateur de définir une référence de bus de modèles dans une propriété de domaineTo allow the user to set a Model Bus Reference in a domain property

  1. Avec le bouton droit de la propriété de domaine, puis cliquez sur ModelBusReference de modifier les propriétés spécifiques.Right-click the domain property and then click Edit ModelBusReference specific properties. Une boîte de dialogue s'ouvre.A dialog box opens. Il s’agit de la sélecteur de Bus de modèle.This is the Model Bus Picker.

  2. Sélectionnez la de ModelBusReference: à un modèle ou à un élément à l’intérieur d’un modèle.Select the appropriate Kind of ModelBusReference: to a model or to an element inside a model.

  3. Dans la chaîne de filtre de la boîte de dialogue Fichier, entrez une chaîne telle que Family Tree files |*.ftree.In file dialog filter string, enter a string such as Family Tree files |*.ftree. Remplacez l'extension de fichier de votre DSL exposé.Subsitute the file extension of your exposed DSL.

  4. Si vous choisissez de référencer un élément dans un modèle, vous pouvez ajouter une liste de types que l'utilisateur peut sélectionner, par exemple Company.FamilyTree.Person.If you chose to reference an element in a model, you can add a list of types that the user can select, for example Company.FamilyTree.Person.

  5. Cliquez sur OK, puis cliquez sur transformer tous les modèles dans la barre d’outils de l’Explorateur de solutions.Click OK, and then click Transform All Templates in the solution explorer toolbar.

    Avertissement

    Si vous n'avez pas sélectionné un modèle ou une entité valide, le bouton OK sera sans effet, même s'il peut paraître activé.If you have not selected a valid model or entity, the OK button will have no effect, even though it might appear enabled.

  6. Si vous avez spécifié une liste de types cibles tels que Company.FamilyTree.Person, vous devez ajouter une référence d'assembly à votre projet DSL, en faisant référence à la DLL du DSL cible : Company.FamilyTree.Dsl.dll, par exemple.If you specified a list of target types such as Company.FamilyTree.Person, then you must add an assembly reference to your DSL project, referencing the DLL of the target DSL, for example Company.FamilyTree.Dsl.dll

Pour tester une référence de bus de modèlesTo test a Model Bus Reference

  1. Générez à la fois le DSL exposé et le DSL consommateur.Build both the exposed and consuming DSLs.

  2. Exécutez l'un des DSL en mode expérimental en appuyant sur F5 ou CTRL+F5.Run one of the DSLs in experimental mode by pressing F5 or CTRL+F5.

  3. Dans le projet Débogage de l'instance expérimentale de Visual StudioVisual Studio, ajoutez les fichiers qui sont les instances de chaque DSL.In the Debugging project in the experimental instance of Visual StudioVisual Studio, add files that are instances of each DSL.

    Note

    Visual StudioVisual Studio ModelBus peut uniquement résoudre les références aux modèles qui sont des éléments de la même solution Visual StudioVisual Studio. ModelBus can only resolve references to models that are items in the same Visual StudioVisual Studio solution. Par exemple, vous ne pouvez pas créer de référence à un fichier de modèle dans une autre partie de votre système de fichiers.For example, you cannot create a reference to a model file in another part of your file system.

  4. Créez quelques éléments et liens dans l'instance du DSL exposé, puis enregistrez-les.Create some elements and links in the instance of the exposed DSL, and save it.

  5. Ouvrez une instance du DSL consommateur et sélectionnez un élément de modèle qui possède une propriété de référence de bus de modèles.Open an instance of the consuming DSL, and select a model element that has a model bus reference property.

  6. Dans la fenêtre Propriétés, double-cliquez sur la propriété de référence de bus de modèles.In Properties window, double-click the model bus reference property. La boîte de dialogue du sélecteur s'ouvre.The picker dialog opens.

  7. Cliquez sur Parcourir et sélectionnez l’instance du DSL exposé.Click Browse and select the instance of the exposed DSL.

    Le sélecteur vous permettra aussi de choisir un élément du modèle, si vous avez spécifié le type propre à l'élément de la référence de bus de modèles.The picker will also let you choose an item in the model, if you specified the element-specific kind of model bus reference.

Création de références dans le code de programmeCreating References in Program Code

Lorsque vous voulez stocker une référence à un modèle ou à un élément à l'intérieur d'un modèle, vous créez une ModelBusReference.When you want to store a reference to a model or an element inside a model, you create a ModelBusReference. Il existe deux sortes de ModelBusReference : les références de modèle et les références d'élément.There are two kinds of ModelBusReference: model references and element references.

Pour créer une référence de modèle, vous avez besoin de la classe AdapterManager du DSL dont le modèle est une instance et du nom de fichier ou de l'élément de projet Visual StudioVisual Studio du modèle.To create a model reference, you need the AdapterManager of the DSL of which the model is an instance, and the filename or Visual StudioVisual Studio project item of the model.

Pour créer une référence d'élément, vous avez besoin d'un adaptateur pour le fichier de modèle et de l'élément auquel vous voulez faire référence.To create an element reference, you need an adapter for the model file, and the element you want to refer to.

Note

Avec le Visual StudioVisual Studio ModelBus, vous ne pouvez créer des références que vers les éléments de la même solution Visual StudioVisual Studio.With the Visual StudioVisual Studio ModelBus, you can create references only to items in the same Visual StudioVisual Studio solution.

Importer les assemblys DSL exposésImport the exposed DSL assemblies

Dans le projet consommateur, ajoutez les références de projet aux assemblys DSL et ModelBusAdapter du DSL exposé.In the consuming project, add project references to the DSL and ModelBusAdapter assemblies of the exposed DSL.

Par exemple, imaginez que vous vouliez stocker les références ModelBus dans les éléments d'un DSL MusicLibrary.For example, suppose that you want to store ModelBus References in elements of a MusicLibrary DSL. Les références ModelBus feront référence aux éléments du DSL FamilyTree.The ModelBus References will refer to elements of the FamilyTree DSL. Dans le projet Dsl de la solution MusicLibrary, dans le nœud Références, ajoutez les références aux assemblys suivants :In the Dsl project of the MusicLibrary solution, in the References node, add references to the following assemblies:

  • Fabrikam.FamilyTree.Dsl.dll - le DSL exposé.Fabrikam.FamilyTree.Dsl.dll - the exposed DSL.

  • Fabrikam.FamilyTree.ModelBusAdapters.dll - l'adaptateur ModelBus du DSL exposé.Fabrikam.FamilyTree.ModelBusAdapters.dll - the ModelBus adapter of the exposed DSL.

  • Microsoft.VisualStudio.Modeling.Sdk.Integration.11.0Microsoft.VisualStudio.Modeling.Sdk.Integration.11.0

  • Microsoft.VisualStudio.Modeling.Sdk.Integration.Shell.11.0Microsoft.VisualStudio.Modeling.Sdk.Integration.Shell.11.0

    Ces assemblys sont disponibles dans le projet ModelBusAdapters du DSL exposé, sous bin\*.These assemblies can be found in the ModelBusAdapters project of the exposed DSL, under bin\*.

    Dans le fichier de code où vous allez créer les références, vous devez généralement importer ces espaces de noms :In the code file where you will create references, you will typically have to import these namespaces:

// The namespace of the DSL you want to reference:
using Fabrikam.FamilyTree;  // Exposed DSL
using Fabrikam.FamilyTree.ModelBusAdapters;
using Microsoft.VisualStudio.Modeling.Integration;
using System.Linq;
...

Pour créer une référence à un modèleTo create a reference to a model

Pour créer une référence de modèle, vous accédez à l'AdapterManager du DSL exposé et l'utilisez pour créer une référence au modèle.To create a model reference, you access the AdapterManager for the exposed DSL, and use it to create a reference to the model. Vous pouvez spécifier un chemin d'accès du fichier ou un EnvDTE.ProjectItem.You can specify either a file path, or a EnvDTE.ProjectItem.

À partir de la classe AdapterManager, vous pouvez obtenir un adaptateur, qui fournit l'accès aux éléments individuels du modèle.From the AdapterManager, you can obtain an Adapter, which provides access to individual elements in the model.

Note

Lorsque vous avez fini d'utiliser l'adaptateur, vous devez le supprimer.You must dispose an Adapter when you have finished with it. La solution la plus pratique pour y parvenir consiste à utiliser une instruction using.The most convenient way to achieve this is with a using statement. L'exemple suivant illustre ce comportement.The following example illustrates this.

// The file path of a model instance of the FamilyTree DSL:
string targetModelFile = "TudorFamilyTree.ftree";
// Get the ModelBus service:
IModelBus modelBus =
    this.Store.GetService(typeof(SModelBus)) as IModelBus;
// Get an adapterManager for the target DSL:
FamilyTreeAdapterManager manager =
    (modelbus.GetAdapterManager(FamilyTreeAdapter.AdapterId)
     as FamilyTreeAdapterManager;
// or: (modelBus.FindAdapterManagers(targetModelFile).First())
// or could provide an EnvDTE.ProjectItem

// Create a reference to the target model:
// NOTE: the target model must be a file in this project.
ModelBusReference modelReference =
     manager.CreateReference(targetModelFile);
// or can use an EnvDTE.ProjectItem instead of the filename

// Get the root element of this model:
using (FamilyTreeAdapter adapter =
     modelBus.CreateAdapter(modelReference) as FamilyTreeAdapter)
{
  FamilyTree modelRoot = adapter.ModelRoot;
  // Access elements under the root in the usual way:
  foreach (Person p in modelRoot.Persons) {...}
  // You can create adapters for individual elements:
  ModelBusReference elementReference =
     adapter.GetElementReference(person);
  ...
} // Dispose adapter

Si vous souhaitez pouvoir utiliser la modelReference ultérieurement, vous pouvez la stocker dans une propriété de domaine qui possède le type externe ModelBusReference :If you want to be able to use modelReference later, you can store it in a domain property that has the External Type ModelBusReference:

using Transaction t = this.Store.TransactionManager
    .BeginTransaction("keep reference"))
{
  artist.FamilyTreeReference = modelReference;
  t.Commit();
}

Pour permettre aux utilisateurs de modifier cette propriété de domaine, utilisez ModelReferenceEditor comme paramètre de l'attribut Editor.To allow users to edit this domain property, use ModelReferenceEditor as the parameter in the Editor attribute. Pour plus d’informations, consultez autoriser l’utilisateur à modifier une référence.For more information, see Allow the User to Edit a Reference.

Pour créer une référence à un élémentTo create a reference to an element

L'adaptateur que vous avez créé pour le modèle peut être utilisé pour créer et résoudre les références.The adapter that you created for the model can be used to create and resolve references.

// person is an element in the FamilyTree model:
ModelBusReference personReference =
  adapter.GetElementReference(person);

Si vous souhaitez pouvoir utiliser la elementReference ultérieurement, vous pouvez la stocker dans une propriété de domaine qui possède le type externe ModelBusReference.If you want to be able to use elementReference later, you can store it in a domain property that has the External Type ModelBusReference. Pour permettre aux utilisateurs de la modifier, utilisez ModelElementReferenceEditor comme paramètre de l'attribut Editor.To allow users to edit it, use ModelElementReferenceEditor as the parameter in the Editor attribute. Pour plus d’informations, consultez autoriser l’utilisateur à modifier une référence.For more information, see Allow the User to Edit a Reference.

Résolution des référencesResolving references

Si vous avez une ModelBusReference (MBR), vous pouvez obtenir le modèle ou l'élément du modèle auquel elle fait référence.If you have a ModelBusReference (MBR) you can obtain the model or the model element to which it refers. Si l'élément est présenté sur un diagramme ou une autre vue, vous pouvez ouvrir la vue et sélectionner l'élément.If the element is presented on a diagram or other view, you can open the view and select the element.

Vous pouvez créer un adaptateur à partir d'une MBR.You can create an adapter from an MBR. À partir de l'adaptateur, vous pouvez obtenir la racine du modèle.From the adapter, you can obtain the root of the model. Vous pouvez aussi résoudre les MBR qui font référence à des éléments spécifiques à l'intérieur du modèle.You can also resolve MBRs that refer to specific elements within the model.

using Microsoft.VisualStudio.Modeling.Integration; ...
ModelBusReference elementReference = ...;

// Get the ModelBus service:
IModelBus modelBus =
    this.Store.GetService(typeof(SModelBus)) as IModelBus;
// Use a model reference or an element reference
// to obtain an adapter for the target model:
using (FamilyTreeAdapter adapter =
   modelBus.CreateAdapter(elementReference) as FamilyTreeAdapter)
   // or CreateAdapter(modelReference)
{
  // Get the root of the model:
  FamilyTree tree = adapter.ModelRoot;

  // Get a model element:
  MyDomainClass mel =
    adapter.ResolveElementReference<MyDomainClass>(elementReference);
  if (mel != null) {...}

  // Get the diagram or other view, if there is one:
  ModelBusView view = adapter.GetDefaultView();
  if (view != null)
  {
   view.Open();
   // Display the diagram:
   view.Show();
   // Attempt to select the shape that presents the element:
   view.SetSelection(elementReference);
  }
} // Dispose the adapter.
Pour résoudre les références ModelBus dans un modèle de texteTo resolve ModelBus References in a Text Template
  1. Le DSL auquel vous voulez accéder doit avoir un adaptateur ModelBus configuré pour être accessible par les modèles de texte.The DSL you want to access must have a ModelBus Adapter that has been configured for access by text templates. Pour plus d’informations, consultez fournissant un accès à une DSL.For more information, see Providing Access to a DSL.

  2. Généralement, vous accèderez à un DSL cible à l'aide d'une référence de bus de modèles (MBR) stockée dans un DSL source.Typically, you will be accessing a target DSL using a Model Bus Reference (MBR) stored in a source DSL. Par conséquent, votre modèle inclut la directive du DSL source, plus le code pour résoudre la MBR.Your template therefore includes the directive of the source DSL, plus code to resolve the MBR. Pour plus d’informations sur les modèles de texte, consultez génération du Code à partir d’un langage spécifique à un domaine.For more information about text templates, see Generating Code from a Domain-Specific Language.

    <#@ template debug="true" hostspecific="true"
    inherits="Microsoft.VisualStudio.TextTemplating.Modeling.ModelBusEnabledTextTransformation" #>
    <#@ SourceDsl processor="SourceDslDirectiveProcessor" requires="fileName='Sample.source'" #>
    <#@ output extension=".txt" #>
    <#@ assembly name = "Microsoft.VisualStudio.Modeling.Sdk.Integration.11.0" #>
    <#@ assembly name = "System.Core" #>
    <#@ assembly name = "Company.CompartmentDragDrop.Dsl.dll" #>
    <#@ assembly name = "Company.CompartmentDragDrop.ModelBusAdapter.dll" #>
    <#@ import namespace="Microsoft.VisualStudio.Modeling.Integration" #>
    <#@ import namespace="System.Linq" #>
    <#@ import namespace="Company.CompartmentDragDrop" #>
    <#@ import namespace="Company.CompartmentDragDrop.ModelBusAdapters" #>
    <# // Get source root from directive processor:
      ExampleModel source = this.ExampleModel;
      // This DSL has a MBR in its root:
    using (ModelBusAdapter adapter = this.ModelBus.CreateAdapter(source.ModelReference) as ModelBusAdapter)
      {
      ModelBusAdapterManager manager = this.ModelBus.FindAdapterManagers(this.Host.ResolvePath("Sample.compDD1")).FirstOrDefault();
      ModelBusReference modelReference =
        manager.CreateReference(this.Host.ResolvePath("Sample.compDD1"));
    
      // Get the root element of this model:
      using (CompartmentDragDropAdapter adapter =
         this.ModelBus.CreateAdapter(modelReference) as CompartmentDragDropAdapter)
      {
        ModelRoot root = adapter.ModelRoot;
    #>
    [[<#= root.Name #>]]
    <#
      }
    #>
    

    Pour plus d’informations et une procédure pas à pas, consultez à l’aide de Visual Studio ModelBus dans un modèle de texteFor more information and a walkthrough, see Using Visual Studio ModelBus in a Text Template

Sérialisation d'une ModelBusReferenceSerializing a ModelBusReference

Si vous voulez stocker une ModelBusReference (MBR) sous la forme d'une chaîne, vous pouvez la sérialiser :If you want to store a ModelBusReference (MBR) in the form of a string, you can serialize it:

string serialized = modelBus.SerializeReference(elementReference);
// Store it anywhere, then get it back again:
ModelBusReference elementReferenceRestored =
    modelBus.DeserializeReference(serialized, null);

Une MBR ainsi sérialisée est indépendante du contexte.A MBR that is serialized in this manner is independent of context. Si vous utilisez l'adaptateur de bus de modèles basé sur un fichier simple, la MBR contient un chemin d'accès au fichier absolu.If you are using the simple file-based Model Bus Adapter, the MBR contains an absolute file path. Cela suffit si les fichiers du modèle d'instance ne sont jamais déplacés.This is sufficient if the instance model files will never move. Cependant, les fichiers de modèles sont généralement des éléments d'un projet Visual StudioVisual Studio.However, the model files will typically be items in a Visual StudioVisual Studio project. Vos utilisateurs attendront de pouvoir déplacer la totalité du projet vers différentes parties du système de fichiers.Your users will expect to be able to move the whole project to different parts of the file system. Ils s'attendront aussi à pouvoir maintenir le projet sous contrôle du code source et à l'ouvrir sur différents ordinateurs.They will also expect to be able to keep the project under source control and open it on different computers. Les noms des chemins d'accès doivent par conséquent être sérialisés par rapport à l'emplacement du projet qui contient les fichiers.Path names should therefore be serialized relative to the location of the project that contains the files.

Sérialisation par rapport à un chemin de fichier spécifiéSerializing Relative to a Specified File Path

Une ModelBusReference contient un ReferenceContext, lequel est un dictionnaire où vous pouvez stocker des informations telles que le chemin d'accès par rapport auquel la sérialisation doit être effectuée.A ModelBusReference contains a ReferenceContext, which is a dictionary in which you can store information such as the file path relative to which it should be serialized.

Pour sérialiser par rapport à un chemin d'accès :To serialize relative to a path:

elementReference.ReferenceContext.Add(
   ModelBusReferencePropertySerializer.FilePathSaveContextKey,
   currentProjectFilePath);
string serialized = modelBus.SerializeReference(elementReference);

Pour extraire la référence de la chaîne :To retrieve the reference from the string:

ReferenceContext context = new ReferenceContext();
context.Add(ModelBusReferencePropertySerializer.FilePathLoadContextKey,
    currentProjectFilePath);
ModelBusReference elementReferenceRestored =
    modelBus.DeserializeReference(serialized, context);

ModelBusReference créées par d'autres adaptateursModelBusReferences created by other Adapters

Les informations suivantes sont utiles si vous désirez créer votre propre adaptateur.The following information is useful if you want to create your own adapter.

Une ModelBusReference (MBR) se compose de deux parties : l'en-tête MBR, désérialisé par le bus de modèles, et une partie propre à l'adaptateur et gérée par le gestionnaire de l'adaptateur spécifique.A ModelBusReference (MBR) consists of two parts: the MBR header, which is deserialized by the model bus, and an adapter-specific that is handled by the specific adapter manager. Vous pouvez ainsi fournir votre propre format de sérialisation de l'adaptateur.This lets you provide your own adapter serialization format. Par exemple, vous pouvez référencer une base de données plutôt qu'un fichier ou stocker des informations supplémentaires dans la référence de l'adaptateur.For example, you could reference a database rather than a file, or you could store additional information in the adapter reference. Votre propre adaptateur peut placer des informations supplémentaires dans le ReferenceContext.Your own adapter can place additional information in the ReferenceContext.

Lorsque vous désérialisez une MBR, vous devez fournir un ReferenceContext, qui est alors stocké dans l'objet MBR.When you deserialize an MBR, you must provide a ReferenceContext, which is then stored in the MBR object. Lorsque vous sérialisez une MBR, le ReferenceContext stocké est utilisé par l'adaptateur pour aider à générer la chaîne.When you serialize an MBR, the stored ReferenceContext is used by the adapter to help generate the string. La chaîne désérialisée ne contient pas toutes les informations du ReferenceContext.The deserialized string does not contain all the information in the ReferenceContext. Par exemple, dans l'adaptateur basé sur un fichier simple, le ReferenceContext contient un chemin de fichier racine, qui n'est pas stocké dans la chaîne MBR sérialisée.For example, in the simple file-based adapter, the ReferenceContext contains a root file path, which is not stored in the serialized MBR string.

La désérialisation de la MBR s'effectue en deux étapes :The MBR is deserialized in two stages:

  • ModelBusReferencePropertySerializer est le sérialiseur standard qui gère l'en-tête MBR.ModelBusReferencePropertySerializer is the standard serializer that deals with the MBR header. Il utilise le conteneur de propriétés SerializationContext DSL standard, stocké dans le ReferenceContext à l'aide de la clé ModelBusReferencePropertySerializer.ModelBusLoadContextKey.It uses the standard DSL SerializationContext property bag, which is stored in the ReferenceContext using the key ModelBusReferencePropertySerializer.ModelBusLoadContextKey. En particulier, le SerializationContext doit contenir une instance du ModelBus.In particular, the SerializationContext should contain an instance of ModelBus.

  • Votre adaptateur ModelBus gère la partie spécifique à l'adaptateur de la MBR.Your ModelBus Adapter deals with the adapter-specific part of the MBR. Il peut utiliser les informations supplémentaires stockées dans le ReferenceContext de la MBR.It can use additional information stored in the ReferenceContext of the MBR. L’adaptateur de fichier simple conserve les chemins d’accès du fichier racine à l’aide de clés FilePathLoadContextKey et FilePathSaveContextKey.The simple file-based adapter keeps root file paths using the keys FilePathLoadContextKey and FilePathSaveContextKey.

    Une référence d'adaptateur d'un fichier de modèle n'est désérialisée que lorsqu'elle est utilisée.An adapter reference in a model file is deserialized only when it is used.

Pour créer un modèleTo Create a Model

Création, ouverture et modification d'un modèleCreating, opening and editing a model

Le fragment suivant est extrait de l'exemple State Machine du site web VMSDK.The following fragment is taken from the State Machine sample on the VMSDK Web site. Il illustre l'utilisation des ModelBusReference pour créer et ouvrir un modèle, et pour obtenir le diagramme associé au modèle.It illustrates the use of ModelBusReferences to create and open a model, and to obtain the diagram associated with the model.

Dans cet exemple, le nom du DSL cible est StateMachine.In this sample, the name of the target DSL is StateMachine. Plusieurs noms en sont dérivés, tels que le nom de la classe de modèle et le nom du ModelBusAdapter.Several names are derived from it, such as the name of the model class and the name of the ModelBusAdapter.

using Fabrikam.StateMachine.ModelBusAdapters;
using Microsoft.VisualStudio.Modeling;
using Microsoft.VisualStudio.Modeling.Diagrams;
using Microsoft.VisualStudio.Modeling.Integration;
using Microsoft.VisualStudio.Modeling.Integration.Shell;
using Microsoft.VisualStudio.Modeling.Shell;
...
// Create a new model.
ModelBusReference modelReference =
   StateMachineAdapterManager    .CreateStateMachineModel(modelName, fileName);
//Keep reference of new model in this model.
using (Transaction t = ...)
{
  myModelElement.ReferenceProperty = modelReference;
  t.Commit();
}
// Get the ModelBus service from Visual Studio.
IModelBus modelBus = Microsoft.VisualStudio.Shell.Package.
    GetGlobalService(typeof(SModelBus)) as IModelBus;
// Get a modelbus adapter on the new model.
ModelBusAdapter modelBusAdapter;
modelBus.TryCreateAdapter(modelReference,
    this.ServiceProvider, out modelBusAdapter);
using (StateMachineAdapter adapter =
      modelBusAdapter as StateMachineAdapter)
{
    if (adapter != null)
    {
        // Obtain a Diagram from the adapter.
        Diagram targetDiagram =
           ((StandardVsModelingDiagramView)
                 adapter.GetDefaultView()
            ).Diagram;

        using (Transaction t =
             targetDiagram.Store.TransactionManager
                .BeginTransaction("Update diagram"))
        {
            DoUpdates(targetDiagram);
            t.Commit();
        }

        // Display the new diagram.
        adapter.GetDefaultView().Show();
    }
}

Validation des référencesValidating references

Le BrokenReferenceDetector teste toutes les propriétés de domaine d'un magasin qui peut contenir les ModelBusReference.The BrokenReferenceDetector tests all the domain properties in a Store that can hold ModelBusReferences. Il appelle l'action que vous fournissez quand une action est trouvée.It calls the action you that provide where any action is found. Ceci est particulièrement utile pour les méthodes de validation.This is particularly useful for validation methods. La méthode de validation suivante teste le magasin lors de la tentative d'enregistrement du modèle et signale les références rompues dans la fenêtre des erreurs :The following validation method tests the store on an attempt to save the model, and reports broken references in the errors window:

[ValidationMethod(ValidationCategories.Save)]
public void ValidateModelBusReferences(ValidationContext context)
{
  BrokenReferenceDetector.DetectBrokenReferences(this.Store,
    delegate(ModelElement element, // parent of property
             DomainPropertyInfo property, // identifies property
             ModelBusReference reference) // invalid reference
    {
      context.LogError(string.Format(INVALID_REF_FORMAT,
             property.Name,
             referenceState.Name,
             new ModelBusReferenceTypeConverter().
                 ConvertToInvariantString(reference)),
         "Reference",
         element);
      });
}}
private const string INVALID_REF_FORMAT =
    "The '{0}' domain property of ths ReferenceState instance "
  + "named '{1}' contains reference value '{2}' which is invalid";

Actions exécutées par l'extension ModelBusActions performed by the ModelBus Extension

Les informations suivantes ne sont pas essentielles, mais peuvent être utiles si vous utilisez intensivement ModelBus.The following information is not essential, but might be useful if you make extensive use of ModelBus.

L'extension ModelBus apporte les modifications suivantes dans votre solution DSL.The ModelBus Extension makes the following changes in your DSL solution.

Lorsque vous cliquez sur le diagramme de définition DSL, cliquez sur activer un Modelbus, puis sélectionnez activer cette DSL consommer le ModelBus:When you right-click the DSL Definition diagram, click Enable Modelbus, and then select Enable this DSL to Consume the ModelBus:

  • Dans le projet DSL, une référence est ajoutée à Microsoft.VisualStudio.Modeling.Sdk.Integration.11.0.dllIn the DSL project, a reference is added to Microsoft.VisualStudio.Modeling.Sdk.Integration.11.0.dll

  • Dans la définition DSL, une référence de type externe est ajoutée : Microsoft.VisualStudio.Modeling.Integration.ModelBusReference.In the DSL Definition, an External Type reference is added: Microsoft.VisualStudio.Modeling.Integration.ModelBusReference.

    Vous pouvez voir la référence dans Explorateur DSL, sous Types de domaine.You can see the reference in DSL Explorer, under Domain Types. Pour ajouter manuellement des références de type externe, cliquez avec le bouton droit sur le nœud racine.To add external type references manually, right-click the root node.

  • Un nouveau fichier de modèle est ajouté, Dsl\GeneratedCode\ModelBusReferencesSerialization.tt.A new template file is added, Dsl\GeneratedCode\ModelBusReferencesSerialization.tt.

    Lorsque vous définissez le type d’une propriété de domaine sur ModelBusReference, avec le bouton droit de la propriété et cliquez sur ModelBusReference d’activer des propriétés spécifiques:When you set the type of a domain property to ModelBusReference, and then right-click the property and click Enable ModelBusReference specific properties:

  • Plusieurs attributs CLR sont ajoutés à la propriété de domaine.Several CLR attributes are added to the domain property. Vous pouvez les voir dans le champ Attributs personnalisés de la fenêtre Propriétés.You can see them in the Custom Attributes field in the Properties window. Dans Dsl\GeneratedCode\DomainClasses.cs, vous pouvez voir les attributs sur la déclaration de propriété :In Dsl\GeneratedCode\DomainClasses.cs, you can see the attributes on the property declaration:

    [System.ComponentModel.TypeConverter(typeof(
    Microsoft.VisualStudio.Modeling.Integration.ModelBusReferenceTypeConverter))]
    [System.ComponentModel.Editor(typeof(
      Microsoft.VisualStudio.Modeling.Integration.Picker
      .ModelReferenceEditor // or ModelElementReferenceEditor
      ), typeof(System.Drawing.Design.UITypeEditor))]
    [Microsoft.VisualStudio.Modeling.Integration.Picker
      .SupplyFileBasedBrowserConfiguration
      ("Choose a model file", "Target model|*.target")]
    

    Lorsque vous avec le bouton droit sur le schéma de définition DSL, cliquez sur activer un ModelBus, puis sélectionnez exposer cette DSL pour le ModelBus:When you right click the DSL Definition Diagram, click Enable ModelBus, and select Expose this DSL to the ModelBus:

  • Un nouveau projet ModelBusAdapter est ajouté à la solution.A new project ModelBusAdapter is added to the solution.

  • Une référence à ModelBusAdapter est ajoutée au projet DslPackage.A reference to ModelBusAdapter is added to the DslPackage project. ModelBusAdapter possède une référence au projet Dsl.ModelBusAdapter has a reference to the Dsl project.

  • Dans DslPackage\source.extention.tt, |ModelBusAdapter| est ajouté en tant que composant MEF.In DslPackage\source.extention.tt, |ModelBusAdapter| is added as a MEF Component.

Voir aussiSee Also