Implémentation de la commandeCommand implementation

Pour implémenter une commande dans un VSPackage, vous devez effectuer les tâches suivantes :To implement a command in a VSPackage, you must perform the following tasks:

  1. Dans le .vsct de fichiers, configurer un groupe de commandes et puis ajoutez la commande à celui-ci.In the .vsct file, set up a command group and then add the command to it. Pour plus d’informations, consultez fichiers Visual Studio command table (.vsct).For more information, see Visual Studio command table (.vsct) files.

  2. Inscrire la commande avec Visual Studio.Register the command with Visual Studio.

  3. Implémenter la commande.Implement the command.

Les sections suivantes expliquent comment inscrire et implémenter des commandes.The following sections explain how to register and implement commands.

Commandes de s’inscrire avec Visual StudioRegister commands with Visual Studio

Si votre commande doit apparaître dans un menu, vous devez ajouter le ProvideMenuResourceAttribute à votre VSPackage et les utiliser en tant que valeur le nom du menu ou son ID de ressource.If your command is to appear on a menu, you must add the ProvideMenuResourceAttribute to your VSPackage, and use as a value either the name of the menu or its resource ID.

[ProvideMenuResource("Menus.ctmenu", 1)]  
...  
    public sealed class MyPackage : Package  
    {.. ..}  

En outre, vous devez inscrire la commande avec le OleMenuCommandService.In addition, you must register the command with the OleMenuCommandService. Vous pouvez obtenir ce service à l’aide de la GetService méthode si votre VSPackage est dérivée de Package.You can get this service by using the GetService method if your VSPackage is derived from Package.

OleMenuCommandService mcs = GetService(typeof(IMenuCommandService)) as OleMenuCommandService;  
if ( null != mcs )  
{  
    // Create the command for the menu item.  
    CommandID menuCommandID = new CommandID(guidCommandGroup, myCommandID);  
    MenuCommand menuItem = new MenuCommand(MenuItemCallback, menuCommandID );  
    mcs.AddCommand( menuItem );  
}  

Commandes de l’implémenterImplement commands

Il existe plusieurs manières d’implémenter des commandes.There are a number of ways to implement commands. Si vous souhaitez une commande de menu statique, qui est une commande qui s’affiche toujours la même façon et dans le même menu, créer la commande à l’aide de MenuCommand comme indiqué dans les exemples dans la section précédente.If you want a static menu command, which is a command that always appears the same way and on the same menu, create the command by using MenuCommand as shown in the examples in the previous section. Pour créer une commande statique, vous devez fournir un gestionnaire d’événements qui est chargé d’exécuter la commande.To create a static command, you must provide an event handler that is responsible for executing the command. Étant donné que la commande est toujours activée et visible, il est inutile de fournir son état à Visual Studio.Because the command is always enabled and visible, you do not have to provide its status to Visual Studio. Si vous souhaitez modifier l’état d’une commande selon certaines conditions, vous pouvez créer la commande comme une instance de la OleMenuCommand classe et, dans son constructeur, fournissez un gestionnaire d’événements pour exécuter la commande et un QueryStatus gestionnaire pour notifier Visual Studio lorsque l’état de la commande change.If you want to change the status of a command depending on certain conditions, you can create the command as an instance of the OleMenuCommand class and, in its constructor, provide an event handler to execute the command and a QueryStatus handler to notify Visual Studio when the status of the command changes. Vous pouvez également implémenter IOleCommandTarget comme partie d’une classe de commande ou, vous pouvez implémenter IVsHierarchy si vous fournissez une commande en tant que partie d’un projet.You can also implement IOleCommandTarget as part of a command class or, you can implement IVsHierarchy if you are providing a command as part of a project. Les deux interfaces et la OleMenuCommand classe tous les avoir des méthodes de notification de Visual Studio d’un changement de l’état d’une commande et d’autres méthodes qui fournissent l’exécution de la commande.The two interfaces and the OleMenuCommand class all have methods that notify Visual Studio of a change in the status of a command, and other methods that provide the execution of the command.

Lorsqu’une commande est ajoutée au service de commande, il est une chaîne de commandes.When a command is added to the command service, it becomes one of a chain of commands. Lorsque vous implémentez les méthodes de notification et l’exécution de statut de la commande, veillez à fournir uniquement cette commande particulière et pour transmettre tous les autres cas, une session sur les autres commandes dans la chaîne.When you implement the status notification and execution methods for the command, take care to provide only for that particular command and to pass all other cases on to the other commands in the chain. Si vous ne parvenez pas à passer la commande (généralement en retournant OLECMDERR_E_NOTSUPPORTED), Visual Studio peut cesser de fonctionner correctement.If you fail to pass the command on (usually by returning OLECMDERR_E_NOTSUPPORTED), Visual Studio may stop working properly.

Méthodes QueryStatusQueryStatus methods

Si vous implémentez soit le QueryStatus méthode ou le QueryStatusCommand (méthode), recherchez le GUID de la commande jeu auquel appartient la commande et l’ID de la commande.If you are implementing either the QueryStatus method or the QueryStatusCommand method, check for the GUID of the command set to which the command belongs and the ID of the command. Respectez les règles ci-dessous.Follow these guidelines:

  • Si le GUID n’est pas reconnu, votre implémentation de soit la méthode doit retourner OLECMDERR_E_UNKNOWNGROUP.If the GUID is not recognized, your implementation of either method must return OLECMDERR_E_UNKNOWNGROUP.

  • Si votre implémentation de deux méthodes reconnaît le GUID, mais n’a pas implémenté la commande, la méthode doit retourner OLECMDERR_E_NOTSUPPORTED.If your implementation of either method recognizes the GUID but has not implemented the command, then the method should return OLECMDERR_E_NOTSUPPORTED.

  • Si votre implémentation de deux méthodes reconnaît le GUID et la commande, la méthode doit définir le champ Indicateurs de commande de chaque commande (dans le prgCmds paramètre) à l’aide de ce qui suit OLECMDF indicateurs :If your implementation of either method recognizes both the GUID and the command, then the method should set the command-flags field of every command (in the prgCmds parameter) by using the following OLECMDF flags:

    • OLECMDF_SUPPORTED: La commande est prise en charge.OLECMDF_SUPPORTED: The command is supported.

    • OLECMDF_INVISIBLE: La commande ne doit pas être visible.OLECMDF_INVISIBLE: The command should not be visible.

    • OLECMDF_LATCHED: La commande est activée et a été activée.OLECMDF_LATCHED: The command is toggled on and appears to have been checked.

    • OLECMDF_ENABLED: La commande est activée.OLECMDF_ENABLED: The command is enabled.

    • OLECMDF_DEFHIDEONCTXTMENU: La commande doit être masquée s’il apparaît dans un menu contextuel.OLECMDF_DEFHIDEONCTXTMENU: The command should be hidden if it appears on a shortcut menu.

    • OLECMDF_NINCHED: La commande est un contrôleur de menu et n’est pas activée, mais sa liste déroulante n’est pas vide et qu’il est toujours disponible.OLECMDF_NINCHED: The command is a menu controller and is not enabled, but its drop-down menu list is not empty and is still available. (Cet indicateur est rarement utilisé.)(This flag is rarely used.)

  • Si la commande a été définie dans le .vsct de fichiers avec le TextChanges indicateur, définissez les paramètres suivants :If the command was defined in the .vsct file with the TextChanges flag, set the following parameters:

    • Définir le rgwz élément de la pCmdText paramètre vers le nouveau texte de la commande.Set the rgwz element of the pCmdText parameter to the new text of the command.

    • Définir le cwActual élément de la pCmdText paramètre à la taille de la chaîne de commande.Set the cwActual element of the pCmdText parameter to the size of the command string.

En outre, assurez-vous que le contexte actuel n’est pas une fonction d’automatisation, sauf si votre commande est conçu spécifiquement pour gérer les fonctions d’automatisation.Also, make sure that the current context is not an automation function, unless your command is specifically intended to handle automation functions.

Pour indiquer que vous prenez en charge une commande particulière, retourner S_OK.To indicate that you support a particular command, return S_OK. Pour toutes les autres commandes, retourner OLECMDERR_E_NOTSUPPORTED.For all other commands, return OLECMDERR_E_NOTSUPPORTED.

Dans l’exemple suivant, la QueryStatus méthode tout d’abord permet de s’assurer que le contexte n’est pas une fonction d’automation, puis recherche le bon GUID du jeu de commandes et l’ID de commande.In the following example, the QueryStatus method first makes sure that the context is not an automation function, then finds the correct command-set GUID and command ID. La commande elle-même est définie sur activé et la prise en charge.The command itself is set to be enabled and supported. Aucune autre commande n’est pris en charge.No other commands are supported.

public int QueryStatus(ref Guid pguidCmdGroup, uint cCmds, OLECMD[] prgCmds, IntPtr pCmdText)  
{  
    if (!VsShellUtilities.IsInAutomationFunction(m_provider.ServiceProvider))  
    {  
        if (pguidCmdGroup == VSConstants.VSStd2K && cCmds > 0)  
        {  
            // make the Right command visible   
            if ((uint)prgCmds[0].cmdID == (uint)VSConstants.VSStd2KCmdID.RIGHT)  
            {  
                prgCmds[0].cmdf = (int)Microsoft.VisualStudio.OLE.Interop.Constants.MSOCMDF_ENABLED | (int)Microsoft.VisualStudio.OLE.Interop.Constants.MSOCMDF_SUPPORTED;  
                return VSConstants.S_OK;  
            }  
        }  
        return Constants.OLECMDERR_E_NOTSUPPORTED;  
    }  
}  

Méthodes d’exécutionExecution methods

Implémentation de la Exec méthode s’apparente à l’implémentation de la QueryStatus (méthode).Implementation of the Exec method resembles implementation of the QueryStatus method. Tout d’abord, assurez-vous que le contexte n’est pas une fonction d’automatisation.First, make sure that the context is not an automation function. Ensuite, le test pour le GUID et ID de commande.Then, test for both the GUID and the command ID. Si le GUID ou ID de commande n’est pas reconnu, retournez OLECMDERR_E_NOTSUPPORTED.If the GUID or command ID is not recognized, return OLECMDERR_E_NOTSUPPORTED.

Pour gérer la commande, exécuter et retourner S_OK si l’exécution réussit.To handle the command, execute it and return S_OK if the execution succeeds. Votre commande est responsable de la détection d’erreur et de notification ; Par conséquent, retourner un code d’erreur si l’exécution échoue.Your command is responsible for error detection and notification; therefore, return an error code if the execution fails. L’exemple suivant montre comment la méthode d’exécution doit être implémentée.The following example demonstrates how the execution method should be implemented.

public int Exec(ref Guid pguidCmdGroup, uint nCmdID, uint nCmdexecopt, IntPtr pvaIn, IntPtr pvaOut)  
{  
    if (!VsShellUtilities.IsInAutomationFunction(m_provider.ServiceProvider))  
    {  
        if (pguidCmdGroup == VSConstants.GUID_VSStandardCommandSet97)  
        {  
             if (nCmdID ==(uint) uint)VSConstants.VSStd2KCmdID.RIGHT)  
            {  
                //execute the command  
                return VSConstants.S_OK;  
            }  
        }  
    }  
    return Constants.OLECMDERR_E_NOTSUPPORTED;  
}  

Voir aussiSee also

Comment VSPackages ajoute des éléments d’interface utilisateurHow VSPackages add user interface elements