Implementación de comandos

Para implementar un comando en un VSPackage, debe realizar las siguientes tareas:

1. En el archivo .vsct , configure un grupo de comandos y agregue el comando a él. Para obtener más información, vea Archivos de tabla de comandos (.vsct) de Visual Studio.

2. Registre el comando con Visual Studio.

3. Implemente el comando .

En las secciones siguientes se explica cómo registrar e implementar comandos.

Registro de comandos con Visual Studio

Si el comando va a aparecer en un menú, debe agregar el ProvideMenuResourceAttribute a su VSPackage y usar como valor el nombre del menú o su identificador de recurso.

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

Además, debe registrar el comando con OleMenuCommandService. Puede obtener este servicio mediante el GetService método si el VSPackage se deriva de Package.

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

Implementación de comandos

Hay varias maneras de implementar comandos. Si desea un comando de menú estático, que es un comando que siempre aparece de la misma manera y en el mismo menú, cree el comando usando MenuCommand como se muestra en los ejemplos de la sección anterior. Para crear un comando estático, debe proporcionar un controlador de eventos responsable de ejecutar el comando. Dado que el comando siempre está habilitado y visible, no es necesario proporcionar su estado a Visual Studio. Si desea cambiar el estado de un comando en función de determinadas condiciones, puede crear el comando como una instancia de la OleMenuCommand clase y, en su constructor, proporcionar un controlador de eventos para ejecutar el comando y un QueryStatus controlador para notificar a Visual Studio cuando cambie el estado del comando. También puede implementar IOleCommandTarget como parte de una clase de comandos o puede implementar IVsHierarchy si proporciona un comando como parte de un proyecto. Las dos interfaces y la OleMenuCommand clase tienen todos métodos que notifican a Visual Studio un cambio en el estado de un comando y otros métodos que proporcionan la ejecución del comando.

Cuando se agrega un comando al servicio de comandos, se convierte en una cadena de comandos. Al implementar los métodos de notificación de estado y ejecución para el comando, asegúrese de atender únicamente a ese comando en particular y de derivar todos los demás casos a los otros comandos de la cadena. Si no logras pasar el comando (normalmente devolviendo OLECMDERR_E_NOTSUPPORTED), Visual Studio podría dejar de funcionar correctamente.

Métodos QueryStatus

Si va a implementar el QueryStatus método o el QueryStatusCommand método , compruebe el GUID del conjunto de comandos al que pertenece el comando y el identificador del comando. Siga estas instrucciones:

• Si no se reconoce el GUID, la implementación de cualquiera de los métodos debe devolver OLECMDERR_E_UNKNOWNGROUP.

• Si la implementación de cualquiera de los métodos reconoce el GUID pero no ha implementado el comando , el método debe devolver OLECMDERR_E_NOTSUPPORTED.

• Si la implementación de cualquiera de los métodos reconoce el GUID y el comando, el método debe establecer el campo de marcas de comandos de cada comando (en el prgCmds parámetro) mediante las marcas siguientes OLECMDF :

  • OLECMDF_SUPPORTED: Se admite el comando.

  • OLECMDF_INVISIBLE: el comando no debe estar visible.

  • OLECMDF_LATCHED: el comando está activado y parece que se ha comprobado.

  • OLECMDF_ENABLED: el comando está habilitado.

  • OLECMDF_DEFHIDEONCTXTMENU: el comando debe ocultarse si aparece en un menú contextual.

  • OLECMDF_NINCHED: el comando es un controlador de menú y no está habilitado, pero su lista de menús desplegables no está vacía y sigue estando disponible. (Esta marca rara vez se usa).

• Si el comando se definió en el archivo .vsct con la TextChanges marca , establezca los parámetros siguientes:

  • Establezca el elemento rgwz del parámetro pCmdText en el nuevo texto del comando.

  • Establezca el elemento cwActual del parámetro pCmdText en el tamaño de la cadena de comandos.

Además, asegúrese de que el contexto actual no es una función de automatización, a menos que el comando esté diseñado específicamente para controlar las funciones de automatización.

Para indicar que admite un comando determinado, devuelva S_OK. Para todos los demás comandos, devuelva OLECMDERR_E_NOTSUPPORTED.

En el ejemplo siguiente, el QueryStatus método primero garantiza que el contexto no es una función de automatización y, a continuación, busca el GUID y el identificador de comando correctos del conjunto de comandos. El propio comando está configurado para estar habilitado y soportado. No se admite ningún otro comando.

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étodos de ejecución

La implementación del Exec método es similar a la implementación del QueryStatus método . En primer lugar, asegúrese de que el contexto no es una función de automatización. A continuación, realice pruebas de ambos, el GUID y el identificador de comando. Si no se reconoce el GUID o el identificador de comando, devuelva OLECMDERR_E_NOTSUPPORTED.

Para controlar el comando, ejecútelo y devuelva S_OK si la ejecución se realiza correctamente. El comando es responsable de la detección y notificación de errores; por lo tanto, devuelve un código de error si se produce un error en la ejecución. En el ejemplo siguiente se muestra cómo se debe implementar el método de ejecución.

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)VSConstants.VSStd2KCmdID.RIGHT)
            {
                // execute the command
                return VSConstants.S_OK;
            }
        }
    }
    return Constants.OLECMDERR_E_NOTSUPPORTED;
}

Contenido relacionado

• Cómo VSPackages agrega elementos de la interfaz de usuario