Hinzufügen eines Kontextmenübefehls für den Datei-Explorer zu einer verpackten Desktop-App

Windows 11 Apps erweitern das kontextmenü des modernen Datei-Explorers, indem IExplorerCommand implementiert und der Befehl mit App-Identität registriert wird. Dies gilt für verpackte Desktop-Apps und für entpackte Win32-Apps, die ein sparse-Paket verwenden.

Eine Dateizuordnung kann eine App unter „Öffnen mit“ verfügbar machen oder ein Bearbeitungsverben für einen Dateityp hinzufügen, den die App verarbeitet. Sie enthält nicht die allgemeine Kontextmenüerweiterung, die in diesem Artikel beschrieben wird. Verwenden Sie zum Hinzufügen eines Befehls für beliebige Dateien, Ordner oder Ordnerhintergründe IExplorerCommand.

Informationen zum Design des Kontextmenüs in Windows 11 sowie Anleitungen dazu, wann ein Befehl hinzugefügt werden sollte, finden Sie unter Erweitern des Kontextmenüs und des Dialogfelds „Teilen“ in Windows 11.

Funktionsweise von Kontextmenüerweiterungen

Eine Kontextmenüerweiterung umfasst die folgenden Teile:

1. Eine native DLL implementiert eine oder mehrere COM-Klassen, die IExplorerCommand zur Verfügung stellen.
2. Das Paketmanifest registriert jede COM-Klasse als windows.comServer Erweiterung.
3. Das Paketmanifest registriert den Befehl als windows.fileExplorerContextMenus Erweiterung und ordnet einen Shellelementtyp der CLSID der COM-Klasse zu.

Der Datei-Explorer aktiviert die COM-Klasse beim Erstellen des Kontextmenüs. Ihre IExplorerCommand-Implementierung liefert den Titel, das Symbol, den Zustand und die Aktion. Befehle derselben App können in einem App-spezifischen Flyout gruppiert werden; implementieren Sie EnumSubCommands, um untergeordnete Befehle bereitzustellen.

Implementieren von IExplorerCommand

Implementieren Sie IExplorerCommand in einer systemeigenen COM-DLL. C++ ist die übliche Wahl, da der Befehl im Shell-Integrationspfad ausgeführt wird. Die folgende gekürzte Implementierung stellt einen Befehlstitel bereit, aktiviert den Befehl und empfängt die ausgewählten Elemente, wenn der Benutzer ihn aufruft.

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

Verwenden Sie das an Invoke übergebene IShellItemArray, um die aktuelle Auswahl aufzulisten. GetState kann Zustände wie ECS_HIDDEN, ECS_DISABLED oder ECS_ENABLED zurückgeben, um zu steuern, ob der Befehl angezeigt wird und ausgewählt werden kann. Den vollständigen Vertrag finden Sie unter "IExplorerCommand".

Weisen Sie die COM-Klasse einer CLSID zu, und stellen Sie sicher, dass dieselbe CLSID im Paketmanifest verwendet wird. Beispiel:

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

Registrieren des Befehls im Paketmanifest

Deklarieren Sie die Namespaces com, desktop4 und desktop5 auf dem Stammelement Package und fügen Sie sie IgnorableNamespaces hinzu.

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

Registrieren Sie die DLL zunächst unter dem Anwendungselement Extensions als COM-Server. com:Class/@Id ist die CLSID des Befehls und Path der paketrelative Pfad der 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>

Ordnen Sie dann die CLSID dem Kontext zu, in dem der Befehl angezeigt werden soll.

<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 identifiziert die Zielshellelemente. Verwenden Sie * für Dateien, Directory für ausgewählte Ordner oder Directory\Background für den Hintergrund eines Ordners. Sie können mehrere ItemType Einträge für dieselbe CLSID registrieren, wenn ein Befehl mehrere Kontexte unterstützt.

Das desktop5:Verb/@Id identifiziert die Manifestregistrierung. desktop5:Verb/@Clsid muss mit dem com:Class/@Id Wert und der CLSID für die COM-Klasse übereinstimmen.

Das vollständige Manifestschema finden Sie unter "desktop4:FileExplorerContextMenus " und "com:Class".

Packen der DLL

Fügen Sie die Befehls-DLL und alle Ressourcen, die sie benötigt, in das Paket unter dem von com:Class/@Path angegebenen Pfad ein. Wenn Sie ein Windows Application Packaging Project verwenden, fügen Sie die DLL dem project hinzu, und konfigurieren Sie sie so, dass sie in die Paketausgabe kopiert wird. Konfigurieren Sie eine Buildabhängigkeit oder einen Kopiervorgang nach dem Build, sodass das Paket die aktuelle DLL enthält.

Die DLL-Architektur muss mit der Architektur des Datei-Explorers übereinstimmen, die sie lädt. Erstellen und verpacken Sie die entsprechende Architektur für das Zielgerät.

Verwenden Sie ein Sparse-Paket für eine nicht paketierte App

Eine nicht paketierte Win32-App kann dieselben IExplorerCommand und Manifestregistrierungen verwenden, indem sie ein Sparse-Paket installiert, das der App eine Paketidentität verleiht. Ein „Sparse Package“ enthält keine App-Binärdateien; stattdessen verweist es auf die extern installierte App.

Zusätzlich zu den zuvor gezeigten COM- und Kontextmenüerweiterungen deklariert ein Sparse-Paketmanifest in der Regel uap10:AllowExternalContent und konfiguriert die Anwendung als Win32-Anwendung. Das folgende Beispiel zeigt die relevanten Sparse-Package-Deklarationen.

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

Siehe Sparse packages für Verpackungs- und Registrierungsanforderungen für nicht paketierte Apps.

Testen der Erweiterung

Installieren oder registrieren Sie das Paket, öffnen Sie dann den Datei-Explorer, und klicken Sie mit der rechten Maustaste auf ein Element, das einem der registrierten Elementtypen zugeordnet ist. Wenn der Befehl nach der Installation oder Aktualisierung eines Pakets nicht angezeigt wird, starten Sie den Datei-Explorer neu, oder melden Sie sich ab und wieder an, damit die Shell die Erweiterungsregistrierung erneut lädt.

Verwenden Sie "Weitere Optionen anzeigen ", um ältere Kontextmenüerweiterungen zu prüfen. Ein Befehl, der über windows.fileExplorerContextMenus registriert und mit IExplorerCommand implementiert wurde, wird im Windows-11-Kontextmenü angezeigt.

Dateitypzuordnungen

Registrieren Sie eine Dateitypzuordnung , wenn die App diesen Dateityp öffnet oder bearbeitet. Es kann die App über „Öffnen mit“ verfügbar machen und ein Bearbeitungsverb für zugeordnete Dateitypen hinzufügen. Verwenden Sie den Kontextmenümechanismus in diesem Artikel für Befehle, die für generische Dateien, Ordner oder Hintergründe gelten, oder für Befehle, die Vorgänge ausführen, ohne die normale Dateiöffnungsumgebung der App zu öffnen.