Adicionar um comando de menu de contexto do Explorador de Arquivos a um aplicativo de área de trabalho empacotado

Aplicativos do Windows 11 ampliam o menu de contexto moderno do Explorador de Arquivos implementando IExplorerCommand e registrando o comando usando a identidade do aplicativo. Isso se aplica a aplicativos de área de trabalho empacotados e a aplicativos Win32 descompactados que usam um pacote esparso.

Uma associação de tipo de arquivo pode disponibilizar um aplicativo no Open com ou adicionar um verbo de edição para um tipo de arquivo que o aplicativo manipula. Ele não fornece a extensão de menu de contexto de uso geral descrita neste artigo. Para adicionar um comando para arquivos arbitrários, pastas ou planos de fundo de pasta, use IExplorerCommand.

Para obter orientações e informações sobre o design do menu de contexto no Windows 11 sobre quando adicionar um comando, consulte Estender o menu de contexto e a caixa de diálogo Compartilhar no Windows 11.

Como funcionam as extensões de menu de contexto

Uma extensão de menu de contexto tem estas partes:

1. Uma DLL nativa implementa uma ou mais classes COM que expõem IExplorerCommand.
2. O manifesto do pacote registra cada classe COM como uma windows.comServer extensão.
3. O manifesto do pacote registra o comando como uma windows.fileExplorerContextMenus extensão e associa um tipo de item de shell ao CLSID da classe COM.

O Explorador de Arquivos ativa a classe COM quando cria o menu de contexto. Sua IExplorerCommand implementação fornece o título, o ícone, o estado e a ação. Os comandos de um mesmo aplicativo podem ser agrupados em um submenu atribuído ao aplicativo; implemente EnumSubCommands para fornecer comandos filho.

Implementar IExplorerCommand

Implementar IExplorerCommand em uma DLL COM nativa. C++ é a opção usual porque o comando é executado no caminho de integração do Shell. A implementação abreviada a seguir fornece um título de comando, habilita o comando e recebe os itens selecionados quando o usuário o invoca.

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

Use o IShellItemArray fornecido a Invoke para enumerar a seleção atual. GetState pode retornar estados como ECS_HIDDEN, ECS_DISABLEDou ECS_ENABLED para controlar se o comando aparece e pode ser selecionado. Para obter o contrato completo, consulte IExplorerCommand.

Atribua à classe COM um CLSID e verifique se o mesmo CLSID é usado no manifesto do pacote. Por exemplo:

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

Registrar o comando no manifesto do pacote

Declare os namespaces com, desktop4 e desktop5 no elemento raiz Package e adicione-os 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>

No elemento de aplicativo Extensions , primeiro registre a DLL como um servidor COM. com:Class/@Id é o CLSID do comando e Path é o caminho relativo ao pacote da 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>

Em seguida, associe o CLSID ao contexto no qual o comando deve aparecer.

<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 os itens de Shell de destino. Use * para arquivos, Directory para pastas selecionadas ou Directory\Background para a tela de fundo de uma pasta. Você pode registrar várias ItemType entradas para o mesmo CLSID quando um comando dá suporte a vários contextos.

O desktop5:Verb/@Id identifica o registro do manifesto. desktop5:Verb/@Clsid deve corresponder ao com:Class/@Id valor e ao CLSID na classe COM.

Para obter o esquema de manifesto completo, consulte desktop4:FileExplorerContextMenus e com:Class.

Empacotar a DLL

Inclua a DLL de comando e todos os recursos necessários no pacote no caminho especificado por com:Class/@Path. Se você usar um Projeto de Empacotamento de Aplicativos do Windows, adicione a DLL ao projeto e configure-a para ser copiada para a saída do pacote. Configure uma dependência de compilação ou uma cópia pós-compilação para que o pacote contenha a DLL atual.

A arquitetura de DLL deve corresponder à arquitetura do Explorador de Arquivos que a carrega. Crie e empacote a arquitetura apropriada para o dispositivo de destino.

Usar um pacote esparso para um aplicativo não empacotado

Um aplicativo Win32 não empacotado pode usar os mesmos IExplorerCommand e os registros de manifesto instalando um pacote esparso que forneça a identidade do pacote do aplicativo. Um pacote esparso não contém os binários do aplicativo; em vez disso, ele faz referência ao aplicativo instalado externamente.

Além do COM e das extensões de menu de contexto mostradas anteriormente, um manifesto de pacote esparso uap10:AllowExternalContent normalmente declara e configura o aplicativo como um aplicativo Win32. O exemplo a seguir mostra as declarações sparse-package relevantes.

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

Consulte Pacotes esparsos para ver os requisitos de empacotamento e registro para aplicativos não empacotados.

Testar a extensão

Instale ou registre o pacote, abra o Explorador de Arquivos e clique com o botão direito do mouse em um item correspondente a um dos tipos de item registrados. Se o comando não aparecer depois de instalar ou atualizar um pacote, reinicie o Explorador de Arquivos ou saia e entre novamente para que o shell recarregue o registro de extensão.

Use Mostrar mais opções apenas para inspecionar extensões herdadas do menu de contexto. Um comando registrado por meio de windows.fileExplorerContextMenus e implementado com IExplorerCommand aparece no menu de contexto do Windows 11.

Associações de tipo de arquivo

Registre uma associação de tipo de arquivo quando o aplicativo abrir ou editar esse tipo de arquivo. Ele pode disponibilizar o aplicativo por meio do Open com e pode adicionar um verbo de edição para tipos de arquivo associados. Use o mecanismo de menu de contexto neste artigo para comandos que se aplicam a arquivos genéricos, pastas ou planos de fundo ou para comandos que executam operações sem abrir a experiência normal de abertura de arquivo do aplicativo.