Aggiungere un comando al menu contestuale di Esplora file per un'app desktop pacchettizzata

Le app di Windows 11 estendono il moderno menu contestuale di Esplora file implementando IExplorerCommand e registrando il comando tramite l'identità dell'app. Questo vale per le app desktop in pacchetto e per le app Win32 non in pacchetto che usano un pacchetto sparse.

Un'associazione di tipi di file può rendere disponibile un'app in Apri con o aggiungere un verbo di modifica per un tipo di file gestito dall'app. Non fornisce l'estensione del menu di scelta rapida per utilizzo generico descritta in questo articolo. Per aggiungere un comando per file, cartelle o sfondi di cartelle arbitrari, usare IExplorerCommand.

Per informazioni sulla progettazione del menu di scelta rapida Windows 11 e indicazioni su quando aggiungere un comando, vedere Estensione del menu di scelta rapida e della finestra di dialogo di condivisione in Windows 11.

Funzionamento delle estensioni del menu di scelta rapida

Un'estensione del menu di scelta rapida include queste parti:

  1. Una DLL nativa implementa una o più classi COM che espongono IExplorerCommand.
  2. Il manifesto del pacchetto registra ogni classe COM come windows.comServer estensione.
  3. Il manifesto del pacchetto registra il comando come windows.fileExplorerContextMenus estensione e associa un tipo di elemento della shell al CLSID della classe COM.

Esplora file attiva la classe COM quando crea il menu di scelta rapida. L'implementazione IExplorerCommand fornisce il titolo, l'icona, lo stato e l'azione. I comandi della stessa app possono essere raggruppati in un menu a comparsa attribuito all'app; implementa EnumSubCommands per fornire comandi secondari.

Important

Esplora file carica il codice delle estensioni della shell nell'ambito dell'esperienza della shell. Mantieni rapidi GetTitle, GetIcon, GetState e altri metodi per la creazione dei menu. Non eseguire operazioni dispendiose nel percorso dell'interfaccia utente di Esplora file. Eseguire operazioni di lunga durata dopo che viene chiamato Invoke.

Implementare IExplorerCommand

Implementare IExplorerCommand in una DLL COM nativa. C++ è la scelta consueta perché il comando viene eseguito nel percorso di integrazione della shell. L'implementazione abbreviata seguente fornisce un titolo di comando, abilita il comando e riceve gli elementi selezionati quando l'utente lo richiama.

class EditCommand final : public IExplorerCommand
{
public:
    IFACEMETHODIMP GetTitle(IShellItemArray*, PWSTR* title)
    {
        return SHStrDup(L"Edit with Contoso", title);
    }

    IFACEMETHODIMP GetState(
        IShellItemArray*, BOOL, EXPCMDSTATE* state)
    {
        *state = ECS_ENABLED;
        return S_OK;
    }

    IFACEMETHODIMP Invoke(IShellItemArray* items, IBindCtx*)
    {
        // Obtain selected items from items and start the app or operation.
        return S_OK;
    }

    IFACEMETHODIMP GetIcon(IShellItemArray*, PWSTR* icon)
    {
        return SHStrDup(L"ContosoCommand.dll,-101", icon);
    }

    IFACEMETHODIMP GetToolTip(IShellItemArray*, PWSTR* tooltip)
    {
        *tooltip = nullptr;
        return E_NOTIMPL;
    }

    IFACEMETHODIMP GetCanonicalName(GUID* canonicalName)
    {
        *canonicalName = GUID_NULL;
        return S_OK;
    }

    IFACEMETHODIMP GetFlags(EXPCMDFLAGS* flags)
    {
        *flags = ECF_DEFAULT;
        return S_OK;
    }

    IFACEMETHODIMP EnumSubCommands(IEnumExplorerCommand** commands)
    {
        *commands = nullptr;
        return E_NOTIMPL;
    }
};

Usa IShellItemArray passato a Invoke per enumerare la selezione corrente. GetState può restituire stati come ECS_HIDDEN, ECS_DISABLEDo ECS_ENABLED per controllare se il comando viene visualizzato e può essere selezionato. Per il contratto completo, vedere IExplorerCommand.

Assegnare alla classe COM un CLSID e assicurarsi che lo stesso CLSID venga usato nel manifesto del pacchetto. Per esempio:

class __declspec(uuid("01234567-89AB-CDEF-0123-456789ABCDEF"))
    EditCommand;

Registrare il comando nel manifesto del pacchetto

Dichiara gli spazi dei nomi com, desktop4 e desktop5 sull'elemento radice Package e aggiungili a IgnorableNamespaces.

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10"
  xmlns:desktop4="http://schemas.microsoft.com/appx/manifest/desktop/windows10/4"
  xmlns:desktop5="http://schemas.microsoft.com/appx/manifest/desktop/windows10/5"
  IgnorableNamespaces="com desktop4 desktop5">
  <!-- ... -->
</Package>

Nell'elemento dell'applicazione Extensions registrare prima la DLL come server COM. com:Class/@Id è il CLSID del comando ed Path è il percorso relativo al pacchetto della DLL.

<com:Extension Category="windows.comServer">
  <com:ComServer>
    <com:SurrogateServer DisplayName="Contoso commands">
      <com:Class
        Id="01234567-89AB-CDEF-0123-456789ABCDEF"
        Path="ContosoCommand.dll"
        ThreadingModel="STA" />
    </com:SurrogateServer>
  </com:ComServer>
</com:Extension>

Associare quindi CLSID al contesto in cui deve essere visualizzato il comando.

<desktop4:Extension Category="windows.fileExplorerContextMenus">
  <desktop4:FileExplorerContextMenus>
    <desktop5:ItemType Type="*">
      <desktop5:Verb
        Id="EditWithContoso"
        Clsid="01234567-89AB-CDEF-0123-456789ABCDEF" />
    </desktop5:ItemType>
  </desktop4:FileExplorerContextMenus>
</desktop4:Extension>

desktop5:ItemType/@Type identifica gli elementi della shell di destinazione. Usare * per i file, Directory per le cartelle selezionate o Directory\Background per lo sfondo di una cartella. È possibile registrare più voci ItemType per lo stesso CLSID quando un comando supporta più contesti.

desktop5:Verb/@Id identifica la registrazione del manifest. desktop5:Verb/@Clsid deve corrispondere al com:Class/@Id valore e al CLSID nella classe COM.

Per lo schema manifesto completo, vedere desktop4:FileExplorerContextMenus e com:Class.

Creare il pacchetto della DLL

Includere la DLL del comando e tutte le risorse necessarie nel pacchetto nel percorso specificato da com:Class/@Path. Se si usa un Windows Application Packaging Project, aggiungere la DLL al progetto e configurarla in modo che venga copiata nell'output del pacchetto. Configurare una dipendenza di compilazione o una copia post-compilazione in modo che il pacchetto contenga la DLL corrente.

L'architettura della DLL deve corrispondere all'architettura di Esplora file che la carica. Compilare e creare il pacchetto dell'architettura appropriata per il dispositivo di destinazione.

Usa un pacchetto sparse per un'app senza pacchetto

Un'app Win32 senza pacchetto può usare le stesse registrazioni IExplorerCommand e del manifesto installando un pacchetto sparse che assegna all'app un'identità di pacchetto. Un pacchetto sparse non contiene i file binari dell'app; fa riferimento all'app installata esternamente.

Oltre alle estensioni COM e del menu contestuale illustrate in precedenza, un manifest del pacchetto sparse in genere dichiara uap10:AllowExternalContent e configura l'applicazione come applicazione Win32. Nell'esempio seguente vengono illustrate le dichiarazioni di pacchetto sparse pertinenti.

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap10="http://schemas.microsoft.com/appx/manifest/uap/windows10/10"
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
  IgnorableNamespaces="uap10 rescap">

  <Properties>
    <uap10:AllowExternalContent>true</uap10:AllowExternalContent>
  </Properties>

  <Applications>
    <Application
      Id="ContosoApp"
      Executable="ContosoApp.exe"
      uap10:TrustLevel="mediumIL"
      uap10:RuntimeBehavior="win32App">
      <!-- VisualElements and the COM/context-menu Extensions go here. -->
    </Application>
  </Applications>

  <Capabilities>
    <rescap:Capability Name="runFullTrust" />
    <rescap:Capability Name="unvirtualizedResources" />
  </Capabilities>
</Package>

Vedi Pacchetti sparse per i requisiti di creazione di pacchetti e registrazione per le app non in pacchetto.

Testare l'estensione

Installare o registrare il pacchetto, quindi aprire Esplora file e fare clic con il pulsante destro del mouse su un elemento corrispondente a uno dei tipi di elemento registrati. Se il comando non viene visualizzato dopo l'installazione o l'aggiornamento di un pacchetto, riavviare Esplora file o disconnettersi e tornare indietro in modo che la shell ricarica la registrazione dell'estensione.

Usare Mostra altre opzioni solo per esaminare le estensioni legacy del menu di scelta rapida. Un comando registrato tramite windows.fileExplorerContextMenus e implementato con IExplorerCommand viene visualizzato nel menu di scelta rapida Windows 11.

Associazioni di tipi di file

Registrare un'associazione di tipo di file quando l'app apre o modifica il tipo di file. Può rendere l'app disponibile tramite Apri con e può aggiungere un verbo di modifica per i tipi di file associati. Usare il meccanismo del menu di scelta rapida in questo articolo per i comandi che si applicano a file, cartelle o sfondi generici o per i comandi che eseguono operazioni senza aprire la normale esperienza di apertura file dell'app.

  • Last updated on