Condividi tramite

Procedura: Creare e gestire i comandi in Vspackage (c#)

  • Articolo

Aggiunta di un comando a un pacchetto VS è un processo in due fasi. Innanzitutto, il comando viene definito come un elemento XML nel file di .vsct. Viene distribuito nel codice. Le informazioni inserite nel file di .vsct determinano l'aspetto del comando, ovvero la posizione dell'(IDE) IDE e di parte del comportamento. Il comando viene quindi definita nel codice, in genere come MenuCommand o oggetto di OleMenuCommand e i relativi gestori eventi vengono implementati.

I controlli che un VSPackage rende disponibili dell'IDE devono essere visibili e attivati prima che l'utente possa utilizzarli. Quando i controlli vengono creati in un file di .vsct tramite il modello di progetto del pacchetto di Visual Studio, sono visibili e attivati per impostazione predefinita. Impostare i flag di comando, ad esempio DynamicItemStart, può modificarne il comportamento predefinito. La visibilità, lo stato attivato e altre proprietà di un comando possono essere modificati nel codice in fase di esecuzione accesso all'oggetto di OleMenuCommand associato al comando.

creare un comando

Tutti i controlli, gruppi di controlli, menu, barre degli strumenti e le finestre degli strumenti sono definiti nel file di .vsct. Se il package VS non dispone di un file di .vsct, è necessario aggiungerne uno. Per ulteriori informazioni, vedere Tabella dei comandi di Visual Studio (. file di Vsct).

Se si crea un VSPackage utilizzando il modello importa pacchetto, comando di menu selezionato per creare un file di .vsct e per definire un comando di menu predefinito. Per ulteriori informazioni, vedere procedura dettagliata: Creazione di un comando di menu utilizzando il modello importa pacchetto Visual Studio.

Per aggiungere un comando all'IDE

  1. aprire il file di .vsct.

  2. Nella sezione di Symbols , individuare l'elemento di GuidSymbol che contiene i gruppi e controlli.

  3. Creare un elemento di IDSymbol per ogni menu, gruppo, o ordinare che si desidera aggiungere, come illustrato nell'esempio seguente.

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

    Gli attributi di name degli elementi di IDSymbol e di GuidSymbol forniscono il GUID: coppia di ID per ogni nuovo menu, gruppo, o comando. guid rappresenta un comando impostato definito per il package VS. È possibile definire set più di comando. ogni GUID: la coppia di ID deve essere univoca.

  4. Nella sezione di pulsanti , creare un elemento di pulsante per definire il comando, come illustrato nell'esempio seguente.

    <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. Impostare guid e id sistema in base al GUID: ID di nuovo.

    2. Impostare l'attributo priority.

      L'attributo di priority viene utilizzato dal .vsct per determinare la posizione del pulsante tra gli altri oggetti nel gruppo padre.

      I controlli con valori di priorità inferiore vengono visualizzati su, o a sinistra di, controlli con valori con priorità più alta. I valori di priorità duplicati sono consentiti, ma la posizione relativa dei menu con priorità uguale è determinata dall'ordine in cui vengono elaborati in fase di esecuzione e in quale ordine non può essere predeterminato.

      Omettendo i set di attributi priority il valore su 0.

    3. Impostare l'attributo type. Nella maggior parte dei casi, il relativo valore verrà “Pulsante„. Per le descrizioni di altri tipi validi del pulsante, vedere Elemento Button.

  5. Nella definizione del pulsante, creare un elemento di stringhe contenente un elemento di ButtonText per contenere il nome del menu nell'IDE e di un elemento di CommandName per contenere il nome del comando utilizzato per accedere al menu nella finestra di commando.

    Se la stringa di testo del pulsante include “&„ il carattere, l'utente può aprire il menu premendo ALT più il carattere immediatamente successivo a “&„.

    L'aggiunta di un elemento di Tooltip modo il testo contenuto a essere visualizzato quando l'utente posiziona il puntatore sul pulsante.

  6. Aggiungere un elemento di icona per specificare l'icona, se disponibile, per essere visualizzata con il comando. Le icone sono obbligatorie per i pulsanti sulle barre degli strumenti ma non per le voci di menu. guid e id dell'elemento di Icon devono corrispondere a quelle di un elemento di bitmap definito nella sezione di Bitmaps .

  7. Aggiungere i flag di comando, in base alle proprie esigenze, per modificare l'aspetto e il comportamento del pulsante. A tale scopo, aggiungere un elemento di CommandFlag nella definizione del menu.

  8. Impostare il gruppo padre del comando. Il gruppo padre può essere un gruppo creato, un gruppo da un altro pacchetto, o un gruppo dall'IDE. Ad esempio, aggiungere il comando nella barra degli strumenti di modifica di Visual Studio, accanto ai pulsanti di rimuovere il commento e di commento , imposta il padre a guidStdEditor: IDG_VS_EDITTOOLBAR_COMMENT. Se l'oggetto padre è un gruppo definito dall'utente, deve essere il figlio di un menu, una barra degli strumenti, o di una finestra degli strumenti visualizzato nell'IDE.

    È possibile procedere in due modi, in base alla progettazione:

    • Nell'elemento di Button , creare un elemento di Elemento padre e impostare i relativi campi di id e di guid al GUID e sull'ID del gruppo che ospiterà il comando, anche noti come il gruppo padre principale.

      Nell'esempio seguente viene definito un comando che verrà visualizzato in un menu definito dall'utente.

      <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>

    • È possibile omettere l'elemento di Parent se il comando deve essere inserito mediante la posizione del comando. Creare un elemento di CommandPlacements prima della sezione di Symbols e aggiungere un elemento di CommandPlacement che ha guid e id di comando, di prioritye di un oggetto padre, come illustrato nell'esempio seguente.

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

      Creando più percorsi di comando che hanno lo stesso GUID: L'ID e ha cause diverse di padre un menu da visualizzare in più posizioni. Per ulteriori informazioni, vedere l'elemento di CommandPlacements .

    Per ulteriori informazioni sui gruppi di controlli e sull'elemento padre, vedere Procedura: Creare gruppi riutilizzabili di pulsanti.

In questa fase, il comando sarà visibile nell'IDE, ma non disporrà di funzionalità. Se il comando è stato creato dal modello del pacchetto, per impostazione predefinita il gestore click visualizzato un messaggio.

gestire il nuovo comando

La maggior parte dei controlli nel codice gestito possono essere gestiti dal pacchetto gestito Framework (MPF) associa il comando a un oggetto di MenuCommand o l'oggetto di OleMenuCommand e implementare i gestori eventi.

Per il codice che utilizza direttamente l'interfaccia IOleCommandTarget il package VS necessario implementare sia i metodi QueryStatus e Exec dell'interfaccia IOleCommandTarget. i due metodi più importanti sono QueryStatus e Exec.

Per gestire il nuovo comando utilizzando MPF

  1. Ottenere l'istanza di OleMenuCommandService , come illustrato nell'esempio seguente.

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

  2. Creare un oggetto di CommandID che ha come parametri il GUID e l'ID di comando gestire, come illustrato nell'esempio seguente.

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

    Il modello del pacchetto Visual Studio fornisce due raccolte, GuidList e PkgCmdIDList, per utilizzare i GUID e gli ID dei controlli. Questi vengono popolati automaticamente per i controlli aggiunti dal modello, ma per i controlli aggiunti manualmente, è inoltre necessario aggiungere una voce di ID alla classe di PkgCmdIdList .

    In alternativa, è possibile popolare l'oggetto di CommandID utilizzando il valore stringa non elaborato il GUID e il valore intero identificazione

  3. Creare un'istanza di MenuCommand o l'oggetto di OleMenuCommand che specificano il metodo che gestisce il comando insieme a CommandID, come illustrato nell'esempio seguente.

    MenuCommand menuItem = 
    new MenuCommand(MenuItemCallback, menuCommandID);

    MenuCommand è appropriato per i controlli statici. Le visualizzazioni dinamiche della voce di menu richiedono gestori eventi di QueryStatus. OleMenuCommand aggiunge l'evento di BeforeQueryStatus , che si verifica quando il menu host di comando è aperto e altre proprietà, quali Text.

    I controlli creati dal modello del pacchetto vengono passati per impostazione predefinita a un oggetto di OleMenuCommand nel metodo di Initialize() della classe del pacchetto.

  4. MenuCommand è appropriato per i controlli statici. Le visualizzazioni dinamiche della voce di menu richiedono gestori eventi di QueryStatus. OleMenuCommand aggiunge l'evento di BeforeQueryStatus , che si verifica quando il menu host di comando è aperto e altre proprietà, quali Text.

    I controlli creati dal modello del pacchetto vengono passati per impostazione predefinita a un oggetto di OleMenuCommand nel metodo di Initialize() della classe del pacchetto. La procedura guidata di Visual Studio implementa il metodo di Initialize utilizzando MenuCommand. For dynamic menu item displays, you must change this to OleMenuCommand, as is shown in the next step. Inoltre, per modificare il testo della voce di menu, è necessario aggiungere un flag di comando di TextChanges sul pulsante del comando di menu nel file di .vsct, come illustrato nel seguente esempio

    <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. Passare il nuovo comando di menu al metodo di AddCommand interfaccia di IMenuCommandService . Questa operazione viene eseguita per impostazione predefinita per i controlli creati dal modello del pacchetto, come illustrato nell'esempio

    mcs.AddCommand( menuItem );

  6. implementare il metodo che gestisce il comando.

Per implementare QueryStatus utilizzo di classi di MPF

  1. L'evento di QueryStatus si verifica prima che un comando per la visualizzazione. Questo consente alle proprietà del comando essere nel gestore eventi impostato prima di raggiungere l'utente. Solo controlli aggiunti anche se gli oggetti di OleMenuCommand possono accedere a questo metodo.

    Aggiungere un oggetto di EventHandler all'evento di BeforeQueryStatus nell'oggetto di OleMenuCommand creato per gestire il comando, come illustrato nell'esempio (menuItemistanza di 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'oggetto di EventHandler viene fornito il nome di un metodo chiamato quando lo stato del comando di menu viene eseguita la query.

  2. Implementare il metodo di gestione dello stato di query per il comando. Il parametro di objectsender possibile eseguire il cast su un oggetto di OleMenuCommand , utilizzato per impostare i vari attributi del comando di menu, compreso il testo. Nella tabella seguente sono elencate le proprietà della classe di MenuCommand (dalla classe OleMenuCommand di MPF deriva) che corrispondono ai flag di OLECMDF .

    proprietà di MenuCommand

    flag di OLECMDF

    Checked = true

    OLECMDF_LATCHED

    Visible = false

    OLECMDF_INVISIBLE

    Enabled = true

    OLECMDF_ENABLED

    Per modificare il testo di un comando di menu, utilizzare la proprietà di Text l'oggetto di OleMenuCommand , come illustrato nell'esempio seguente.

    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";
    }
}

Il MPF gestisce automaticamente il caso dei gruppi non supportati o sconosciuti. A meno che un comando sia stato aggiunto a OleMenuCommandService tramite il metodo di AddCommand , il comando non è supportato.

Comandi di gestione tramite l'interfaccia di IOleCommandTarget

For code that uses the IOleCommandTarget interface directly, the VSPackage must implement both the QueryStatus and Exec methods of the IOleCommandTarget interface. If the VSPackage implements a project hierarchy, the QueryStatusCommand and ExecCommand methods of the IVsUIHierarchy interface should be implemented instead.

Sia l'entity_M:Microsoft.VisualStudio.OLE.Interop.IOleCommandTarget.QueryStatus(System.Guid@, System.UInt32, Microsoft.VisualStudio.OLE.Interop.OLECMD[], System.IntPtr) che i metodi di Exec sono progettati per ricevere un unico comando GUID definita e una matrice di ID di comandi come input. È consigliabile supporto di package VS completamente questo concetto di più ID in una chiamata a. However, as long as a VSPackage is not called from other VSPackages, you can assume that the command array contains only one command ID because the QueryStatus and Exec methods are executed in a well-defined order. Per ulteriori informazioni sul routing, vedere Command Routing in VSPackages.

Per il codice che utilizza l'interfaccia di IOleCommandTarget direttamente per la gestione del comando, è necessario implementare il metodo di QueryStatus nel package VS come segue per gestire i comandi.

Per implementare il metodo di QueryStatus

  1. S_OK di tornare ai comandi validi.

  2. Impostare l'elemento di cmdf del parametro di prgCmds .

    Il valore dell'elemento di cmdf è un'unione logica di valori dall'enumerazione di OLECMDF , combinata utilizzando il OR logico (|operatore).

    Utilizzare l'enumerazione appropriata, in base allo stato del comando:

    • se il comando è supportato:

      prgCmds[0].cmdf = OLECMDF_SUPPORTED;

    • Se il comando è invisibile al momento:

      prgCmds[0].cmdf |= OLECMDF_INVISIBLE;

    • Se il comando viene passato su ed è possibile fare clic su:

      prgCmds[0].cmdf |= OLECMDF_LATCHED;

      Nel caso dei comandi di elaborazione ospitati su un menu di tipo MenuControllerLatched, il primo comando contrassegnato dal flag di OLECMDF_LATCHED è il comando predefinito che viene visualizzato dal menu nella destinazione. Per ulteriori informazioni sui tipi di menu di MenuController , vedere Elemento Menu.

    • Se il comando è attualmente attivato:

      prgCmds[0].cmdf |= OLECMDF_ENABLED;

    • Se il comando fa parte di un menu di scelta rapida e viene nascosto per impostazione predefinita:

      prgCmds[0] cmdf |= OLECMDF_DEFHIDEONCTXMENU

    • Se il comando utilizza il flag di TEXTCHANGES , impostare l'elemento di rgwz del parametro di pCmdText al nuovo testo del comando e impostare l'elemento di cwActual del parametro di pCmdText alle dimensioni della stringa di comando.

    For error conditions, the QueryStatus method must handle the following error cases:

    • Se il GUID è sconosciuto o OLECMDERR_E_UNKNOWNGROUPnon supportato e restituire.

    • Se il GUID è definito ma l'ID di comando è sconosciuto o OLECMDERR_E_NOTSUPPORTEDnon supportato e restituire.

L'implementazione di un VSPackage del metodo di Exec inoltre necessario restituire i codici di errore specifici, come se il comando è supportato e se il comando è stato gestito correttamente.

Per implementare il metodo exec

  • Se il comando GUID è OLECMDERR_E_UNKNOWNGROUPsconosciuto e restituire.

  • Se GUID è definito ma l'ID di comando è sconosciuto, restituire OLECMDERR_E_NOTSUPPORTED.

  • Se GUID e l'ID di comando corrispondono al GUID: La coppia ID utilizzata dal comando nel file di .vsct, viene eseguito il codice associato al comando e tornare S_OK.

Vedere anche

Concetti

Riferimento XML Schema VSCT

Altre risorse

Attività comuni con i controlli, i menu e le barre degli strumenti

Walkthrough: Adding a Command to a Visual Studio Menu