Définition d'une stratégie de verrouillage pour créer des segments en lecture seuleDefining a Locking Policy to Create Read-Only Segments

L’API d’immuabilité du kit de développement logiciel (SDK) de visualisation et de modélisation de Visual Studio permet à un programme de verrouiller tout ou partie d’un modèle de langage spécifique à un domaine (DSL) afin qu’il puisse être lu mais pas modifié.The Immutability API of the Visual Studio Visualization and Modeling SDK allows a program to lock part or all of a domain-specific language (DSL) model so that it can be read but not changed. Cette option en lecture seule peut être utilisée, par exemple, pour qu’un utilisateur puisse demander aux collègues d’annoter et de passer en revue un modèle DSL, mais peut les empêcher de modifier l’original.This read-only option could be used, for example, so that a user can ask colleagues to annotate and review a DSL model but can disallow them from changing the original.

En outre, en tant qu’auteur d’une solution DSL, vous pouvez définir une stratégie de verrouillage.In addition, as author of a DSL, you can define a locking policy. Une stratégie de verrouillage définit les verrous autorisés, non autorisés ou obligatoires.A locking policy defines which locks are permitted, not permitted, or mandatory. Par exemple, lorsque vous publiez un DSL, vous pouvez encourager les développeurs tiers à l’étendre avec de nouvelles commandes.For example, when you publish a DSL, you can encourage third-party developers to extend it with new commands. Toutefois, vous pouvez également utiliser une stratégie de verrouillage pour les empêcher de modifier l’État en lecture seule des parties spécifiées du modèle.But you could also use a locking policy to prevent them from altering the read-only status of specified parts of the model.

Notes

Une stratégie de verrouillage peut être contournée à l’aide de la réflexion.A locking policy can be circumvented by using reflection. Il fournit une limite claire pour les développeurs tiers, mais ne fournit pas une sécurité renforcée.It provides a clear boundary for third-party developers, but does not provide strong security.

Des informations supplémentaires et des exemples sont disponibles sur le site Web du Kit de développement logiciel de visualisation et de modélisation de Visual Studio.More information and samples are available at the Visual Studio Visualization and Modeling SDK website.

Notes

Le composant de transformation de modèle de texte est automatiquement installé dans le cadre de la charge de travail développement d' extension Visual Studio .The Text Template Transformation component is automatically installed as part of the Visual Studio extension development workload. Vous pouvez également l’installer à partir de l’onglet composants individuels de Visual Studio installer, sous la catégorie Kits SDK, bibliothèques et infrastructures .You can also install it from the Individual components tab of Visual Studio Installer, under the SDKs, libraries, and frameworks category. Installez le composant SDK Modeling à partir de l’onglet composants individuels .Install the Modeling SDK component from the Individual components tab.

Définition et obtention de verrousSetting and Getting Locks

Vous pouvez définir des verrous sur le magasin, sur une partition ou sur un élément individuel.You can set locks on the store, on a partition, or on an individual element. Par exemple, cette instruction empêchera la suppression d’un élément de modèle, et empêchera également la modification de ses propriétés :For example, this statement will prevent a model element from being deleted, and will also prevent its properties from being changed:

using Microsoft.VisualStudio.Modeling.Immutability; ...
element.SetLocks(Locks.Delete | Locks.Property);

D’autres valeurs de verrouillage peuvent être utilisées pour empêcher les modifications de relations, la création d’éléments, le déplacement entre les partitions et la réorganisation des liens dans un rôle.Other lock values can be used to prevent changes in relationships, element creation, movement between partitions, and re-ordering links in a role.

Les verrous s’appliquent aux actions de l’utilisateur et au code du programme.The locks apply both to user actions and to program code. Si le code de programme tente d’apporter une modification, une InvalidOperationException est levée.If program code attempts to make a change, an InvalidOperationException will be thrown. Les verrous sont ignorés lors d’une opération d’annulation ou de rétablissement.Locks are ignored in an Undo or Redo operation.

Vous pouvez déterminer si un élément a un verrou dans un jeu donné à l’aide de IsLocked(Locks) et que vous pouvez obtenir le jeu actuel de verrous sur un élément à l’aide de GetLocks() .You can discover whether an element has a any lock in a given set by using IsLocked(Locks) and you can obtain the current set of locks on an element by using GetLocks().

Vous pouvez définir un verrou sans utiliser de transaction.You can set a lock without using a transaction. Le verrou de base de données ne fait pas partie du magasin.The lock database is not part of the store. Si vous définissez un verrou en réponse à une modification d’une valeur dans le magasin, par exemple dans OnValueChanged, vous devez autoriser les modifications qui font partie d’une opération d’annulation.If you set a lock in response to a change of a value in the store, for example in OnValueChanged, you should allow changes that are part of an Undo operation.

Ces méthodes sont des méthodes d’extension définies dans l' Microsoft.VisualStudio.Modeling.Immutability espace de noms.These methods are extension methods that are defined in the Microsoft.VisualStudio.Modeling.Immutability namespace.

Verrous sur les partitions et les magasinsLocks on partitions and stores

Les verrous peuvent également être appliqués aux partitions et au magasin.Locks can also be applied to partitions and the store. Un verrou défini sur une partition s’applique à tous les éléments de la partition.A lock that is set on a partition applies to all the elements in the partition. Par exemple, l’instruction suivante empêchera tous les éléments d’une partition d’être supprimés, quels que soient les États de leurs propres verrous.Therefore, for example, the following statement will prevent all the elements in a partition from being deleted, irrespective of the states of their own locks. Toutefois, d’autres verrous tels que Locks.Property peuvent toujours être définis sur des éléments individuels :Nevertheless, other locks such as Locks.Property could still be set on individual elements:

partition.SetLocks(Locks.Delete);

Un verrou défini sur le magasin s’applique à tous ses éléments, quels que soient les paramètres de ce verrou sur les partitions et les éléments.A lock that is set on the Store applies to all its elements, irrespective of the settings of that lock on the partitions and the elements.

Utilisation de verrousUsing Locks

Vous pouvez utiliser des verrous pour implémenter des schémas tels que les exemples suivants :You could use locks to implement schemes such as the following examples:

  • Interdisez les modifications apportées à tous les éléments et relations, à l’exception de ceux qui représentent des commentaires.Disallow changes to all elements and relationships except those that represent comments. Cela permet aux utilisateurs d’annoter un modèle sans le modifier.This allows users to annotate a model without changing it.

  • Interdire les modifications dans la partition par défaut, mais autoriser les modifications dans la partition du diagramme.Disallow changes in the default partition, but allow changes in the diagram partition. L’utilisateur peut réorganiser le diagramme, mais ne peut pas modifier le modèle sous-jacent.The user can rearrange the diagram, but cannot alter the underlying model.

  • Interdire les modifications apportées au magasin, à l’exception d’un groupe d’utilisateurs inscrits dans une base de données distincte.Disallow changes to the Store except for a group of users who are registered in a separate database. Pour les autres utilisateurs, le schéma et le modèle sont en lecture seule.For other users, the diagram and model are read-only.

  • Interdire les modifications apportées au modèle si une propriété booléenne du diagramme a la valeur true.Disallow changes to the model if a Boolean property of the diagram is set to true. Fournissez une commande de menu pour modifier cette propriété.Provide a menu command to change that property. Cela permet de garantir que les utilisateurs ne peuvent pas apporter de modifications accidentelles.This helps ensure users that they do not make changes accidentally.

  • Interdire l’ajout et la suppression d’éléments et de relations de classes particulières, mais autoriser les modifications de propriété.Disallow addition and deletion of elements and relationships of particular classes, but allow property changes. Cela fournit aux utilisateurs une forme fixe dans laquelle ils peuvent remplir les propriétés.This provides users with a fixed form in which they can fill the properties.

Valeurs de verrouillageLock values

Les verrous peuvent être définis sur un magasin, une partition ou un ModelElement individuel.Locks can be set on a Store, Partition, or individual ModelElement. Les verrous sont une Flags énumération : vous pouvez combiner ses valeurs à l’aide de' | '.Locks is a Flags enumeration: you can combine its values using '|'.

  • Les verrous d’un ModelElement incluent toujours les verrous de sa partition.Locks of a ModelElement always include the Locks of its Partition.

  • Les verrous d’une partition incluent toujours les verrous du magasin.Locks of a Partition always include the Locks of the Store.

    Vous ne pouvez pas définir un verrou sur une partition ou un magasin et désactiver en même temps le verrou sur un élément individuel.You cannot set a lock on a partition or store and at the same time disable the lock on an individual element.

ValeurValue Cela signifie que si IsLocked(Value) a la valeur trueMeaning if IsLocked(Value) is true
NoneNone Aucune restriction.No restriction.
PropriétéProperty Les propriétés de domaine des éléments ne peuvent pas être modifiées.Domain properties of elements cannot be changed. Cela ne s’applique pas aux propriétés générées par le rôle d’une classe de domaine dans une relation.This does not apply to properties that are generated by the role of a domain class in a relationship.
AjouterAdd Impossible de créer des éléments et des liens dans une partition ou un magasin.New elements and links cannot be created in a partition or store.

Non applicable à ModelElement .Not applicable to ModelElement.
DéplacerMove L’élément ne peut pas être déplacé entre des partitions si element.IsLocked(Move) a la valeur true, ou si targetPartition.IsLocked(Move) a la valeur true.Element cannot be moved between partitions if element.IsLocked(Move) is true, or if targetPartition.IsLocked(Move) is true.
SupprimerDelete Un élément ne peut pas être supprimé si ce verrou est défini sur l’élément lui-même, ou sur l’un des éléments dans lequel la suppression se propage, comme des éléments et des formes incorporés.An element cannot be deleted if this lock is set on the element itself, or on any of the elements to which deletion would propagate, such as embedded elements and shapes.

Vous pouvez utiliser element.CanDelete() pour déterminer si un élément peut être supprimé.You can use element.CanDelete() to discover whether an element can be deleted.
RéorganiserReorder L’ordre des liens au niveau d’un rolePlayer ne peut pas être modifié.The ordering of links at a roleplayer cannot be changed.
RolePlayerRolePlayer L’ensemble de liens qui sont associés à cet élément ne peut pas être modifié.The set of links that are sourced at this element cannot be changed. Par exemple, les nouveaux éléments ne peuvent pas être incorporés sous cet élément.For example, new elements cannot be embedded under this element. Cela n’affecte pas les liens pour lesquels cet élément est la cible.This does not affect links for which this element is the target.

Si cet élément est un lien, sa source et sa cible ne sont pas affectées.If this element is a link, its source and target are not affected.
TousAll Or au niveau du bit des autres valeurs.Bitwise OR of the other values.

Stratégies de verrouillageLocking Policies

En tant qu’auteur d’une solution DSL, vous pouvez définir une stratégie de verrouillage.As the author of a DSL, you can define a locking policy. Une stratégie de verrouillage permet de modérer le fonctionnement de SetLocks (), afin que vous puissiez empêcher des verrous spécifiques d’être définis ou d’imposer que des verrous spécifiques soient définis.A locking policy moderates the operation of SetLocks(), so that you can prevent specific locks from being set or mandate that specific locks must be set. En règle générale, vous utilisez une stratégie de verrouillage pour dissuader les utilisateurs ou les développeurs de transgresser accidentellement l’utilisation prévue d’un DSL, de la même manière que vous pouvez déclarer une variable private .Typically, you would use a locking policy to discourage users or developers from accidentally contravening the intended use of a DSL, in the same manner that you can declare a variable private.

Vous pouvez également utiliser une stratégie de verrouillage pour définir des verrous sur tous les éléments qui dépendent du type de l’élément.You can also use a locking policy to set locks on all elements dependent on the element's type. Cela est dû SetLocks(Locks.None) au fait que est toujours appelé lorsqu’un élément est créé ou désérialisé pour la première fois à partir d’un fichier.This is because SetLocks(Locks.None) is always called when an element is first created or deserialized from file.

Toutefois, vous ne pouvez pas utiliser une stratégie pour faire varier les verrous sur un élément pendant sa durée de vie.However, you cannot use a policy to vary the locks on an element during its life. Pour obtenir cet effet, vous devez utiliser des appels à SetLocks() .To achieve that effect, you should use calls to SetLocks().

Pour définir une stratégie de verrouillage, vous devez :To define a locking policy, you have to:

  • Créez une classe qui implémente ILockingPolicy.Create a class that implements ILockingPolicy.

  • Ajoutez cette classe aux services disponibles via le DocData de votre DSL.Add this class to the services that are available through the DocData of your DSL.

Pour définir une stratégie de verrouillageTo define a locking policy

ILockingPolicy a la définition suivante :ILockingPolicy has the following definition:

public interface ILockingPolicy
{
  Locks RefineLocks(ModelElement element, Locks proposedLocks);
  Locks RefineLocks(Partition partition, Locks proposedLocks);
  Locks RefineLocks(Store store, Locks proposedLocks);
}

Ces méthodes sont appelées lorsqu’un appel est effectué à SetLocks() sur un magasin, une partition ou un ModelElement.These methods are called when a call is made to SetLocks() on a Store, Partition, or ModelElement. Dans chaque méthode, vous disposez d’un ensemble de verrous proposés.In each method, you are provided with a proposed set of locks. Vous pouvez retourner l’ensemble proposé, ou vous pouvez ajouter et soustraire des verrous.You can return the proposed set, or you can add and subtract locks.

Par exemple :For example:

using Microsoft.VisualStudio.Modeling;
using Microsoft.VisualStudio.Modeling.Immutability;
namespace Company.YourDsl.DslPackage // Change
{
  public class MyLockingPolicy : ILockingPolicy
  {
    /// <summary>
    /// Moderate SetLocks(this ModelElement target, Locks locks)
    /// </summary>
    /// <param name="element">target</param>
    /// <param name="proposedLocks">locks</param>
    /// <returns></returns>
    public Locks RefineLocks(ModelElement element, Locks proposedLocks)
    {
      // In my policy, users can never delete an element,
      // and other developers cannot easily change that:
      return proposedLocks | Locks.Delete);
    }
    public Locks RefineLocks(Store store, Locks proposedLocks)
    {
      // Only one user can change this model:
      return Environment.UserName == "aUser"
           ? proposedLocks : Locks.All;
    }

Pour vous assurer que les utilisateurs peuvent toujours supprimer des éléments, même si d’autres appels de code SetLocks(Lock.Delete):To make sure that users can always delete elements, even if other code calls SetLocks(Lock.Delete):

return proposedLocks & (Locks.All ^ Locks.Delete);

Pour interdire la modification de toutes les propriétés de chaque élément de MyClass :To disallow change in all the properties of every element of MyClass:

return element is MyClass ? (proposedLocks | Locks.Property) : proposedLocks;

Pour rendre votre stratégie disponible en tant que serviceTo make your policy available as a service

Dans votre DslPackage projet, ajoutez un nouveau fichier qui contient le code qui ressemble à l’exemple suivant :In your DslPackage project, add a new file that contains code that resembles the following example:

using Microsoft.VisualStudio.Modeling;
using Microsoft.VisualStudio.Modeling.Immutability;
namespace Company.YourDsl.DslPackage // Change
{
  // Override the DocData GetService() for this DSL.
  internal partial class YourDslDocData // Change
  {
    /// <summary>
    /// Custom locking policy cache.
    /// </summary>
    private ILockingPolicy myLockingPolicy = null;

    /// <summary>
    /// Called when a service is requested.
    /// </summary>
    /// <param name="serviceType">Service requested</param>
    /// <returns>Service implementation</returns>
    public override object GetService(System.Type serviceType)
    {
      if (serviceType == typeof(SLockingPolicy)
       || serviceType == typeof(ILockingPolicy))
      {
        if (myLockingPolicy == null)
        {
          myLockingPolicy = new MyLockingPolicy();
        }
        return myLockingPolicy;
      }
      // Request is for some other service.
      return base.GetService(serviceType);
    }
}