Partager via

Comment : Créer et gérer des commandes dans les VSPackages (c#)

  • Article

Ajouter une commande à un VSPackage comporte deux étapes. d'abord, la commande est définie comme un élément XML dans le fichier de .vsct. Il est implémenté en code. Les informations entrées dans le fichier de .vsct déterminent l'apparence de la commande, de son positionnement dans l'environnement de développement intégré (IDE) (IDE), et une partie de son comportement. La commande est alors définie dans le code, en général comme MenuCommand objet ou d' OleMenuCommand , et ses gestionnaires d'événements sont implémentés.

Les commandes qu'un VSPackage rend disponibles à l'IDE doivent être visibles et actives avant qu'un utilisateur puisse les utiliser. Lorsque des commandes sont créées dans un fichier de .vsct à l'aide de le modèle de projet de package Visual Studio, elles sont visibles et activées par défaut. Définir certaines balises de commande, telles que DynamicItemStart, peut modifier le comportement par défaut. La visibilité, l'état actif, et d'autres propriétés d'une commande peuvent également être modifiés dans le code au moment de l'exécution en accédant à l'objet d' OleMenuCommand associé à la commande.

Création d'une commande

tous les commandes, groupes de commandes, menus, barres d'outils, et fenêtres Outil sont définis dans le fichier de .vsct. Si votre VSPackage aucun fichier de .vsct, vous devez en ajouter un. Pour plus d'informations, consultez Tableau de commande Visual Studio (. fichiers de Vsct).

Si vous créez un VSPackage à l'aide de le modèle de package, sélectionnez Commande de menu pour créer un fichier de .vsct et pour définir une commande de menu par défaut. Pour plus d'informations, consultez Procédure pas - à - pas : Créer une commande de menu à l'aide de le modèle de package Visual Studio.

Pour ajouter une commande à l'IDE

  1. ouvrez le fichier de .vsct.

  2. dans la section d' Symbols , recherchez l'élément de GuidSymbol qui contient les groupes et les commandes.

  3. Créez un élément d' IDSymbol pour chaque menu, groupe, ou commande que vous souhaitez ajouter, comme indiqué dans l'exemple suivant.

    <GuidSymbol name="guidButtonGroupCmdSet" value="{f69209e9-975a-4543-821d-1f4a2c52d737}">
  <IDSymbol name="MyMenuGroup" value="0x1020" />
  <IDSymbol name="cmdidMyCommand" value="0x0100" />
</GuidSymbol>

    Les attributs d' name des éléments d' GuidSymbol et d' IDSymbol fournissent un GUID : Paires d'ID pour chaque nouveau menu, groupe, ou commande. guid représente un jeu de commandes qui est défini pour votre VSPackage. Vous pouvez définir plusieurs jeux de commandes. Chaque paire GUID : Les paires d'ID doivent être uniques.

  4. Dans la section de boutons , créez un élément de bouton pour définir la commande, comme illustré dans l'exemple suivant.

    <Button guid="guidButtonGroupCmdSet" id="cmdidMyCommand" priority="0x0100" type="Button">
  <Parent guid="guidButtonGroupCmdSet" id="MyMenuGroup" />
  <Icon guid="guidImages" id="bmpPic1" />
  <Strings>
    <CommandName>cmdidMyCommand</CommandName>
    <ButtonText>My Command name</ButtonText>
  </Strings>
</Button>

    1. Définissez les champs d' guid et d' id pour correspondre à un GUID : ID de la nouvelle.

    2. Définissez l'attribut priority.

      L'attribut d' priority est utilisé par le .vsct pour déterminer l'emplacement du bouton parmi les autres objets de son groupe parent.

      Les commandes qui ont des valeurs de priorité moindre sont affichées ci-dessus, ou à gauche de, les commandes qui ont des valeurs plus élevée. Les valeurs en double élevée sont autorisées, mais la position relative des commandes qui ont la priorité égale est déterminée par l'ordre dans lequel les VSPackages sont traités au moment de l'exécution, et laquelle la commande ne peut pas être prédéterminée.

      En omettant les jeux d'attributs d' priority sa valeur à 0.

    3. Définissez l'attribut type. dans la plupart des cas, sa valeur sera « Bouton ». Pour obtenir les descriptions des autres types valides de bouton, consultez Button, élément.

  5. Dans la définition de bouton, créez un élément de chaînes qui contient un élément de ButtonText pour contenir le nom du menu tel qu'il apparaît dans l'IDE, et d'un élément de CommandName pour contenir le nom de la commande utilisée pour accéder au menu dans la fenêtre de Commande .

    Si la chaîne de texte du bouton inclut «&« , l'utilisateur peut ouvrir le menu en appuyant sur la touche ALT le caractère qui suit immédiatement »&».

    Ajouter un élément d' Tooltip entraînera l'affichage du texte contenu lorsqu'un utilisateur pointe le pointeur sur le bouton.

  6. ajoutez un élément d' icône pour spécifier l'icône, le cas échéant, pour être affiché avec la commande. Les icônes sont requises pour les boutons des barres d'outils mais pas pour les éléments de menu. guid et id de l'élément d' Icon doivent correspondre à celles d'un élément de bitmap défini dans la section d' Bitmaps .

  7. Ajoutez les balises de commande, si nécessaire, pour modifier l'apparence et le comportement du bouton. Pour ce faire, ajoutez un élément de CommandFlag dans la définition de menu.

  8. définissez le groupe parent de la commande. Le groupe parent peut être un groupe que vous créez, un groupe d'un autre package, ou un groupe de l'IDE. Par exemple, ajouter votre commande dans la barre d'outils modification de Visual Studio, en regard de les boutons de Commentaire et de supprimez le commentaire , définit le parent au guidStdEditor : IDG_VS_EDITTOOLBAR_COMMENT. Si le parent est un groupe défini par l'utilisateur, il doit être l'enfant d'un menu, une barre d'outils, ou d'une fenêtre Outil qui s'affiche dans l'IDE.

    Vous pouvez le faire de deux façons, selon votre conception :

    • Dans l'élément d' Button , créez un élément de parent et définissez ses champs d' guid et d' id au GUID et à l'ID du groupe qui hébergera la commande, également connu sous le nom de groupe parent principal.

      l'exemple suivant définit une commande qui apparaîtra sur un menu défini par l'utilisateur.

      <Button guid="guidTopLevelMenuCmdSet" id="cmdidTestCommand" priority="0x0100" type="Button">
  <Parent guid="guidTopLevelMenuCmdSet" id="MyMenuGroup" />
  <Icon guid="guidImages" id="bmpPic1" />
  <Strings>
    <CommandName>cmdidTestCommand</CommandName>
    <ButtonText>Test Command</ButtonText>
  </Strings>
</Button>

    • Vous pouvez omettre l'élément d' Parent si la commande doit être positionné à l'aide de positionnement de commande. Créez un élément de CommandPlacements avant la section d' Symbols , puis ajoutez un élément de CommandPlacement qui a guid et id de la commande, de priority, et d'un parent, comme indiqué dans l'exemple suivant.

      <CommandPlacements>
  <CommandPlacement guid="guidButtonGroupCmdSet" id="cmdidMyCommand" priority="0x105">
    <Parent guid="guidButtonGroupCmdSet" id="MyMenuGroup" />
  </CommandPlacement>
</CommandPlacements>

      Création de plusieurs positionnements de commande qui ont la même paire GUID : L'ID et ont des causes de parents un menu à apparaître dans plusieurs emplacements. Pour plus d'informations, consultez l'élément de CommandPlacements .

    Pour plus d'informations sur les groupes de commandes et le parentage, consultez Comment : Créer des groupes personnalisés de boutons.

À ce stade, la commande n'est visible dans l'IDE, mais n'aura pas de fonctionnalité. Si la commande a été créée par le modèle de package, par défaut elle dispose d'un gestionnaire clic qui affiche un message.

gérer la nouvelle commande

La plupart des commandes dans le code managé peuvent être gérées par managed package (MPF) en associant la commande avec un objet d' MenuCommand ou l'objet d' OleMenuCommand et en implémentant ses gestionnaires d'événements.

Pour le code qui utilise l'interface d' IOleCommandTarget directement pour la gestion de commande, vous devez implémenter l'interface d' IOleCommandTarget et ses méthodes. les deux méthodes les plus importantes sont QueryStatus et Exec.

pour gérer la nouvelle commande à l'aide de MPF

  1. Obtenez l'instance d' OleMenuCommandService , comme indiqué dans l'exemple suivant.

    OleMenuCommandService mcs = 
    GetService(typeof(IMenuCommandService)) as OleMenuCommandService;

  2. Créez un objet d' CommandID qui a comme paramètres GUID et l'ID de la commande de gérer, comme indiqué dans l'exemple suivant.

    CommandID menuCommandID = 
    new CommandID(GuidList.guidButtonGroupCmdSet, 
        (int)PkgCmdIDList.cmdidMyCommand);

    Le modèle de package Visual Studio fournit deux collections, GuidList et PkgCmdIDList, maintenir le GUID et les ID des commandes. Ceux-ci sont remplis automatiquement pour les commandes qui sont ajoutées par le modèle, mais pour les commandes que vous ajoutez manuellement, vous devez également ajouter l'entrée d'ID à la classe d' PkgCmdIdList .

    Sinon, vous pouvez remplir l'objet d' CommandID à l'aide de la valeur de chaîne brut de GUID et de la valeur entière de l'ID.

  3. Instanciez MenuCommand ou l'objet d' OleMenuCommand qui spécifient la méthode qui gère la commande avec CommandID, comme indiqué dans l'exemple suivant.

    MenuCommand menuItem = 
    new MenuCommand(MenuItemCallback, menuCommandID);

    MenuCommand est pertinent pour les commandes statiques. les affichages dynamiques d'élément de menu ont besoin des gestionnaires d'événements de QueryStatus. OleMenuCommand ajoute l'événement d' BeforeQueryStatus , qui se produit lorsque le menu hôte de la commande est ouvert, et d'autres propriétés, telles que Text.

    Les commandes créées par le modèle de package sont passées par défaut à un objet d' OleMenuCommand dans la méthode d' Initialize() de classe de package.

  4. MenuCommand est pertinent pour les commandes statiques. les affichages dynamiques d'élément de menu ont besoin des gestionnaires d'événements de QueryStatus. OleMenuCommand ajoute l'événement d' BeforeQueryStatus , qui se produit lorsque le menu hôte de la commande est ouvert, et d'autres propriétés, telles que Text.

    Les commandes créées par le modèle de package sont passées par défaut à un objet d' OleMenuCommand dans la méthode d' Initialize() de classe de package. L'Assistant Visual Studio applique la méthode d' Initialize à l'aide de MenuCommand. Pour les affichages dynamiques d'élément de menu, vous devez remplacer ce nom par OleMenuCommand, comme indiqué dans l'étape suivante. En outre, pour remplacer le texte d'un élément de menu, vous devez ajouter une balise d'ordre de TextChanges au bouton de commande de menu dans le fichier de .vsct, comme indiqué dans l'exemple suivant

    <Button guid="guidMenuTextCmdSet" id="cmdidMyCommand" priority="0x0100" type="Button">
  <Parent guid="guidMenuTextCmdSet" id="MyMenuGroup" />
  <Icon guid="guidImages" id="bmpPic1" />
  <CommandFlag>TextChanges</CommandFlag>
  <Strings>
    <CommandName>cmdidMyCommand</CommandName>
    <ButtonText>My Command name</ButtonText>
  </Strings>
</Button>

  5. passez la nouvelle commande de menu à la méthode d' AddCommand dans l'interface d' IMenuCommandService . Cela est accompli par défaut pour les commandes créées par le modèle de package, comme indiqué dans l'exemple suivant

    mcs.AddCommand( menuItem );

  6. Implémentez la méthode qui gère la commande.

Pour implémenter QueryStatus à l'aide de les classes de MPF

  1. L'événement de QueryStatus se produit avant qu'une commande s'affiche. Cela permet aux propriétés de cette commande pour être dans le gestionnaire d'événements défini avant d'atteindre l'utilisateur. Uniquement commandes qui sont ajoutées comme des objets d' OleMenuCommand peuvent accéder à cette méthode.

    Ajoutez un objet d' EventHandler à l'événement d' BeforeQueryStatus dans l'objet d' OleMenuCommand qui est créé pour gérer la commande, comme illustré dans l'exemple suivant (menuItem est l'instance de OleMenuCommand ).

    Dim menuCommandID As CommandID = New CommandID(GuidList.guidMenuTextCmdSet, CInt(PkgCmdIDList.cmdidMyTextCommand))
Dim menuItem As OleMenuCommand = New OleMenuCommand(New EventHandler(AddressOf MenuItemCallback), menuCommandID)
AddHandler menuItem.BeforeQueryStatus, AddressOf OnBeforeQueryStatus
mcs.AddCommand(menuItem)

    // Create the command for the menu item.
CommandID menuCommandID = new CommandID(GuidList.guidMenuTextCmdSet, (int)PkgCmdIDList.cmdidMyCommand);
OleMenuCommand menuItem = new OleMenuCommand(MenuItemCallback, menuCommandID );
menuItem.BeforeQueryStatus +=
    new EventHandler(OnBeforeQueryStatus);
mcs.AddCommand(menuItem);

    L'objet d' EventHandler prend le nom d'une méthode appelée lorsque l'état de la commande de menu est interrogé.

  2. Implémentez la méthode de gestionnaire d'état de requête pour la commande. Le paramètre d' objectsender peut être casté à un objet d' OleMenuCommand , qui est utilisé pour définir différents attributs de la commande de menu, y compris le texte. Le tableau suivant affiche les propriétés de la classe d' MenuCommand (ce que la classe OleMenuCommand de MPF dérive) qui correspondent aux balises d' OLECMDF .

    propriété de MenuCommand

    balise d'OLECMDF

    Checked = true

    OLECMDF_LATCHED

    Visible = false

    OLECMDF_INVISIBLE

    Enabled = true

    OLECMDF_ENABLED

    Pour modifier le texte d'une commande de menu, utilisez la propriété d' Text sur l'objet d' OleMenuCommand , comme indiqué dans l'exemple suivant.

    Private Sub OnBeforeQueryStatus(ByVal sender As Object, ByVal e As EventArgs)
    Dim myCommand As OleMenuCommand = TryCast(sender, OleMenuCommand)
    If myCommand IsNot Nothing Then
        myCommand.Text = "New Text" 
    End If 
End Sub

    private void OnBeforeQueryStatus(object sender, EventArgs e)
{
    var myCommand = sender as OleMenuCommand;
    if (null != myCommand)
    {
        myCommand.Text = "New Text";
    }
}

Le MPF gère automatiquement le cas de groupes non managée ou inconnus. À moins qu'une commande a été ajoutée à OleMenuCommandService à l'aide de la méthode d' AddCommand , la commande n'est pas prise en charge.

Gestion des commandes à l'aide de l'interface d'IOleCommandTarget

Pour le code qui utilise l'interface d' IOleCommandTarget directement, le VSPackage doit implémenter l' QueryStatus et des méthodes d' Exec d'interface d' IOleCommandTarget . Si le VSPackage implémente une hiérarchie de projet, l' QueryStatusCommand et les méthodes d' ExecCommand d'interface d' IVsUIHierarchy doivent être implémentés à la place.

L' QueryStatus et des méthodes d' Exec sont conçus pour recevoir un jeu de commandes unique GUID et un tableau d'identificateurs de commande comme entrée. Nous vous recommandons de prise en charge des VSPackages entièrement ce concept de plusieurs identificateurs dans un appel à. Toutefois, à condition que un VSPackage n'est pas appelé à partir de l'autre des VSPackages, vous pouvez supposer que le tableau de commande contient uniquement un ID de commande car l' QueryStatus et les méthodes d' Exec sont exécutés dans un ordre bien définie. Pour plus d'informations sur le routage, consultez Command Routing in VSPackages.

Pour le code qui utilise l'interface d' IOleCommandTarget directement pour la gestion de commande, vous devez implémenter la méthode d' QueryStatus dans le VSPackage comme suit pour gérer les commandes.

Pour implémenter la méthode de QueryStatus

  1. S_OK de retour pour les commandes valides.

  2. définissez l'élément d' cmdf du paramètre d' prgCmds .

    La valeur de l'élément d' cmdf à l'union logique des valeurs de l'énumération d' OLECMDF , combinée à l'aide de l'opérateur logique OR (|opérateur).

    Utilisez l'énumération appropriée, en fonction de l'état de la commande :

    • si la commande est prise en charge :

      prgCmds[0].cmdf = OLECMDF_SUPPORTED;

    • si la commande est invisible à l'heure actuelle :

      prgCmds[0].cmdf |= OLECMDF_INVISIBLE;

    • Si la commande est basculer vers sur et semble avoir cliqué :

      prgCmds[0].cmdf |= OLECMDF_LATCHED;

      Dans le cas de traiter les commandes hébergées sur un menu de type MenuControllerLatched, la première commande qui est marquée par la balise d' OLECMDF_LATCHED est celui par défaut qui est affichée par le menu sur la mise en route. Pour plus d'informations sur les types de menu d' MenuController , consultez Menu, élément.

    • si la commande est actuellement activée :

      prgCmds[0].cmdf |= OLECMDF_ENABLED;

    • si la commande fait partie d'un menu contextuel et est masquée par défaut :

      prgCmds[0] cmdf |= OLECMDF_DEFHIDEONCTXMENU

    • Si la commande utilise la balise d' TEXTCHANGES , affectez à l'élément d' rgwz du paramètre d' pCmdText au nouveau texte de la commande et affectez à l'élément d' cwActual du paramètre d' pCmdText à la taille de la chaîne du contrôle.

    Pour les conditions d'erreur, la méthode d' QueryStatus doit traiter les cas d'erreur suivante :

    • Si le GUID est inconnu ou OLECMDERR_E_UNKNOWNGROUPnon pris en charge et de retour.

    • Si le GUID est connu mais l'ID de commande est inconnu ou OLECMDERR_E_NOTSUPPORTEDnon pris en charge et de retour.

L'implémentation d'un VSPackage de la méthode d' Exec doit également retourner codes d'erreur spécifiques, selon que la commande est pris en charge et si la commande a été exécutée avec succès.

Pour implémenter la méthode d'exec

  • si la commande GUID est OLECMDERR_E_UNKNOWNGROUPinconnu et de retour.

  • si GUID est connu mais l'ID de commande est OLECMDERR_E_NOTSUPPORTEDinconnu et de retour.

  • Si GUID et l'ID de commande correspondent à un GUID : Les paires d'ID qui sont utilisées par la commande dans le fichier de .vsct, exécutent le code associé à la commande et retourner S_OK.

Voir aussi

Concepts

Référence du schéma XML VSCT

Autres ressources

Tâches courantes avec des commandes, des menus, et les barres d'outils

Walkthrough: Adding a Command to a Visual Studio Menu