Integrar um aplicativo de área de trabalho empacotado com o Explorador de Arquivos

2025-06-10

Alguns aplicativos do Windows definem extensões do Explorador de Arquivos que adicionam entradas de menu de contexto que permitem que os clientes executem opções relacionadas ao aplicativo. Tecnologias mais antigas de implantação de aplicativos do Windows, como MSI e ClickOnce, definem extensões do Explorador de Arquivos por meio do registro. O registro tem uma série de hives que controlam as extensões do Explorador de Arquivos e outros tipos de extensões do Shell. Esses instaladores normalmente criam uma série de chaves do Registro para configurar os vários itens a serem incluídos no menu de contexto.

Se você empacotar seu aplicativo do Windows usando MSIX, o registro será virtualizado e, portanto, seu aplicativo não poderá registrar extensões do Explorador de Arquivos por meio do registro. Em vez disso, você deve definir suas extensões do Explorador de Arquivos por meio de extensões de pacote, que você define no manifesto do pacote. Este artigo descreve várias maneiras de fazer isso.

Você pode encontrar o código de exemplo completo usado neste artigo no GitHub.

Uma das maneiras mais simples de se integrar ao Explorador de Arquivos é definir uma extensão de pacote que adiciona seu aplicativo à lista de aplicativos disponíveis no menu de contexto quando um usuário clica com o botão direito do mouse em um tipo de arquivo específico no Explorador de Arquivos. Se o usuário abrir seu aplicativo, sua extensão poderá passar parâmetros para seu aplicativo.

Esse cenário tem várias limitações:

Ele funciona apenas em combinação com o recurso de associação de tipo de arquivo. Você pode exibir opções adicionais no menu de contexto somente para tipos de arquivo associados ao aplicativo principal (por exemplo, seu aplicativo dá suporte à abertura de um arquivo clicando duas vezes nele no Explorador de Arquivos).
As opções no menu de contexto serão exibidas somente se o aplicativo estiver definido como padrão para esse tipo de arquivo.
A única ação com suporte é iniciar o executável principal do aplicativo (ou seja, o mesmo executável que está conectado à entrada do menu Iniciar). No entanto, cada ação pode especificar parâmetros diferentes, que você pode usar quando os aplicativos começam a entender qual ação disparou a execução e executar tarefas diferentes.

Apesar dessas limitações, essa abordagem é suficiente para muitos cenários. Por exemplo, se você estiver criando um editor de imagens, poderá adicionar facilmente uma entrada no menu de contexto para redimensionar uma imagem, que iniciará o editor de imagens diretamente com um assistente para iniciar o processo de redimensionamento.

Para dar suporte a esse cenário, adicione um elemento Extension com a categoria windows.fileTypeAssociation ao manifesto do pacote. Esse elemento deve ser adicionado como um filho do elemento Extensões sob o elemento Application.

O exemplo a seguir demonstra um registro para um aplicativo que habilita menus de contexto para arquivos com a .foo extensão. Este exemplo especifica a .foo extensão porque essa é uma extensão falsa que normalmente não está registrada em outros aplicativos em um determinado computador. Se você precisar gerenciar um tipo de arquivo que pode já ter sido usado (como .txt ou .jpg), lembre-se de que você não poderá ver a opção até que seu aplicativo seja definido como padrão para esse tipo de arquivo. Este exemplo é um trecho do arquivo de Package.appxmanifest no exemplo relacionado no GitHub.

<Extensions>
  <uap3:Extension Category="windows.fileTypeAssociation">
    <uap3:FileTypeAssociation Name="foo" Parameters="&quot;%1&quot;">
      <uap:SupportedFileTypes>
        <uap:FileType>.foo</uap:FileType>
      </uap:SupportedFileTypes>
      <uap2:SupportedVerbs>
        <uap3:Verb Id="Resize" Parameters="&quot;%1&quot; /p">Resize file</uap3:Verb>
      </uap2:SupportedVerbs>
    </uap3:FileTypeAssociation>
  </uap3:Extension>
</Extensions>

Este exemplo pressupõe que os seguintes namespaces e aliases sejam declarados no elemento raiz <Package> no manifesto.

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:uap2="http://schemas.microsoft.com/appx/manifest/uap/windows10/2"
  xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
  IgnorableNamespaces="uap uap2 uap3 rescap">
  ...
</Package>

O elemento FileTypeAssociation associa seu aplicativo aos tipos de arquivo que você deseja dar suporte. Para obter mais detalhes, consulte Associe seu aplicativo empacotado a um conjunto de tipos de arquivo. Aqui estão os itens mais importantes relacionados a esse elemento.

Atributo ou elemento	Descrição
Atributo `Name`	Corresponde ao nome da extensão que você deseja registrar menos o ponto (no exemplo anterior). `foo`
Atributo `Parameters`	Contém os parâmetros que você deseja passar para seu aplicativo quando o usuário clica duas vezes em um arquivo com essa extensão. Normalmente, pelo menos, você passa `%1`, que é um parâmetro especial que contém o caminho do arquivo selecionado. Dessa forma, quando você clica duas vezes em um arquivo, o aplicativo conhece seu caminho completo e pode carregá-lo.
elemento SupportedFileTypes	Especifica os nomes da extensão que você deseja registrar, incluindo o ponto (neste exemplo, `.foo`). Você pode especificar várias entradas de `<FileType>` para dar suporte a mais tipos de arquivo.

Para definir a integração do menu de contexto, você também deve adicionar o elemento secundário SupportedVerbs. Esse elemento contém um ou mais elementos Verbo que definem as opções que serão listadas quando um usuário clicar com o botão direito do mouse em um arquivo com a extensão .foo no Explorador de Arquivos. Para obter mais detalhes, consulte Adicionar opções aos menus de contexto de arquivos que têm um determinado tipo de arquivo. Aqui estão os itens mais importantes relacionados ao elemento verbo .

Atributo ou elemento	Descrição
Atributo `Id`	Especifica o identificador exclusivo da ação.
Atributo `Parameters`	Semelhante ao elemento FileTypeAssociation , esse atributo para o elemento Verb contém os parâmetros que são passados para seu aplicativo quando o usuário clica na entrada do menu de contexto. Normalmente, além do `%1` parâmetro especial para obter o caminho do arquivo selecionado, você também passa um ou mais parâmetros para obter o contexto. Isso permite que seu aplicativo entenda que ele foi aberto a partir de uma entrada de menu de contexto.
Valor do elemento	O valor do elemento Verbo contém o rótulo a ser mostrado na opção do menu de contexto (neste exemplo, Redimensionar arquivo).

Acessar os parâmetros de inicialização no código do aplicativo

A maneira como seu aplicativo recebe os parâmetros depende do tipo de aplicativo que você criou. Por exemplo, um aplicativo WPF normalmente processa os argumentos do evento de inicialização no método OnStartup da classe App. Você pode verificar se há parâmetros de inicialização e, com base no resultado, tomar a ação mais apropriada (como abrir uma janela específica do aplicativo em vez da principal).

public partial class App : Application
{
    protected override void OnStartup(StartupEventArgs e)
    {
        if (e.Args.Contains("Resize"))
        {
            // Open a specific window of the app.
        }
        else
        {
            MainWindow main = new MainWindow();
            main.Show();
        }
    }
}

A captura de tela a seguir demonstra a entrada do menu de contexto Redimensionar Arquivo criado pelo exemplo anterior.

Captura de tela do comando Redimensionar arquivo no menu de atalho

Dar suporte a arquivos ou pastas genéricos e executar tarefas complexas

Embora o uso da extensão FileTypeAssociation no manifesto do pacote, conforme descrito na seção anterior, seja suficiente para muitos cenários, você pode achar que ela a limita. Os dois maiores desafios são:

Você pode lidar apenas com tipos de arquivo aos quais está associado. Por exemplo, você não pode lidar com uma pasta genérica.
Você só pode iniciar o aplicativo com uma série de parâmetros. Você não pode executar operações avançadas, como iniciar outro executável ou executar uma tarefa sem abrir o aplicativo principal.

Para atingir essas metas, você deve criar uma extensão shell, que fornece maneiras mais poderosas de se integrar ao Explorador de Arquivos. Nesse cenário, você cria uma DLL que contém tudo o que é necessário para gerenciar o menu de contexto do arquivo, incluindo o rótulo, o ícone, o estado e as tarefas a serem executadas. Como essa funcionalidade é implementada em uma DLL, você pode fazer quase tudo o que pode fazer com um aplicativo normal. Depois de implementar a DLL, você deve registrá-la por meio de extensões definidas no manifesto do pacote.

Observação

O processo descrito nesta seção tem uma limitação. Depois que o pacote MSIX que contém a extensão é instalado em um computador de destino, o Explorador de Arquivos deve ser reiniciado antes que a extensão shell possa ser carregada. Para fazer isso, o usuário pode reiniciar o computador ou reiniciar o processo de explorer.exe usando o Gerenciador de Tarefas .

Implementar a extensão do Shell

As extensões de shell são baseadas em COM (Component Object Model). Sua DLL expõe um ou mais objetos COM registrados no registro do sistema. O Windows descobre esses objetos COM e integra sua extensão ao Explorador de Arquivos. Como você está integrando seu código com o Windows Shell, o desempenho e o volume de memória são importantes. Portanto, esses tipos de extensões normalmente são criados com C++.

Para obter um código de exemplo que ilustra como implementar extensões do Shell, consulte o projeto ExplorerCommandVerb no exemplo relacionado no GitHub. Este projeto é baseado neste exemplo nos exemplos da área de trabalho do Windows e tem várias revisões para tornar o exemplo mais fácil de usar com as versões mais recentes do Visual Studio.

Este projeto contém um monte de código clichê para tarefas diferentes, como menus dinâmicos versus estáticos e registro manual da DLL. A maior parte desse código não será necessária se você estiver empacotando seu aplicativo usando MSIX, pois o suporte ao empacotamento cuidará dessas tarefas para você. O arquivo ExplorerCommandVerb.cpp contém a implementação do menu de contexto e esse é o arquivo de código principal de interesse para este passo a passo.

A função principal é CExplorerCommandVerb::Invoke. Essa é a função que é invocada quando um usuário clica na entrada no menu de contexto. No exemplo, para minimizar o impacto no desempenho, a operação é executada em outro thread, portanto, você realmente encontrará a implementação real em CExplorerCommandVerb::_ThreadProc.

DWORD CExplorerCommandVerb::_ThreadProc()
{
	IShellItemArray* psia;
	HRESULT hr = CoGetInterfaceAndReleaseStream(_pstmShellItemArray, IID_PPV_ARGS(&psia));
	_pstmShellItemArray = NULL;
	if (SUCCEEDED(hr))
	{
		DWORD count;
		psia->GetCount(&count);

		IShellItem2* psi;
		HRESULT hr = GetItemAt(psia, 0, IID_PPV_ARGS(&psi));
		if (SUCCEEDED(hr))
		{
			PWSTR pszName;
			hr = psi->GetDisplayName(SIGDN_DESKTOPABSOLUTEPARSING, &pszName);
			if (SUCCEEDED(hr))
			{
				WCHAR szMsg[128];
				StringCchPrintf(szMsg, ARRAYSIZE(szMsg), L"%d item(s), first item is named %s", count, pszName);

				MessageBox(_hwnd, szMsg, L"ExplorerCommand Sample Verb", MB_OK);

				CoTaskMemFree(pszName);
			}

			psi->Release();
		}
		psia->Release();
	}

	return 0;
}

Quando um usuário clica com o botão direito do mouse em um arquivo ou pasta, essa função exibe uma caixa de mensagem com o caminho completo do arquivo ou pasta selecionado. Se você quiser personalizar a extensão shell de outras maneiras, poderá estender as seguintes funções no exemplo:

Você pode alterar a função GetTitle para personalizar o rótulo da entrada no menu de contexto.
Você pode alterar a função GetIcon para personalizar o ícone exibido próximo à entrada no menu de contexto.
Você pode alterar a função GetTooltip para personalizar a dica de ferramenta que é exibida quando você passa o mouse sobre a entrada no menu de contexto.

Registrar a extensão Shell

Como a extensão shell é baseada em COM, a DLL de implementação deve ser exposta como um servidor COM para que o Windows possa integrá-la ao Explorador de Arquivos. Normalmente, isso é feito atribuindo uma ID exclusiva (chamada CLSID) ao servidor COM e registrando-a em um hive específico do registro do sistema. No projeto ExplorerCommandVerb , o CLSID para a CExplorerCommandVerb extensão é definido no arquivo Dll.h .

class __declspec(uuid("CC19E147-7757-483C-B27F-3D81BCEB38FE")) CExplorerCommandVerb;

Ao empacotar uma DLL de extensão Shell em um pacote MSIX, você segue uma abordagem semelhante. No entanto, o GUID deve ser registrado dentro do manifesto do pacote em vez do registro, conforme explicado aqui .

No manifesto do seu pacote, comece adicionando os seguintes namespaces ao elemento do pacote.

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

Para registrar o CLSID, adicione um com. Elemento de extensão com a categoria windows.comServer ao manifesto do pacote. Esse elemento deve ser adicionado como um filho do elemento Extensões sob o elemento Application. Este exemplo é um trecho do arquivo de Package.appxmanifest no exemplo relacionado no GitHub.

<com:Extension Category="windows.comServer">
  <com:ComServer>
    <com:SurrogateServer DisplayName="ContextMenuSample">
      <com:Class Id="CC19E147-7757-483C-B27F-3D81BCEB38FE" Path="ExplorerCommandVerb.dll" ThreadingModel="STA"/>
    </com:SurrogateServer>
  </com:ComServer>
</com:Extension>

Há dois atributos críticos a serem configurados no elemento com:Class .

Atributo	Descrição
Atributo `Id`	Isso deve corresponder ao CLSID do objeto que você deseja registrar. Neste exemplo, este é o CLSID declarado no `Dll.h` arquivo associado à `CExplorerCommandVerb` classe.
Atributo `Path`	Isso deve conter o nome da DLL que expõe o objeto COM. Este exemplo inclui a DLL na raiz do pacote, para que ele possa apenas especificar o nome da DLL gerada pelo `ExplorerCommandVerb` projeto.

Em seguida, adicione outra extensão que registre o menu de contexto do arquivo. Para fazer isso, adicione um elemento desktop4:Extension com a categoria windows.fileExplorerContextMenus ao manifesto do pacote. Esse elemento também deve ser adicionado como um filho do elemento Extensões sob o elemento Aplicativo.

<desktop4:Extension Category="windows.fileExplorerContextMenus">
  <desktop4:FileExplorerContextMenus>
    <desktop5:ItemType Type="Directory">
      <desktop5:Verb Id="Command1" Clsid="CC19E147-7757-483C-B27F-3D81BCEB38FE" />
    </desktop5:ItemType>
  </desktop4:FileExplorerContextMenus>
</desktop4:Extension>

Há dois atributos críticos a serem configurados no elemento desktop4:Extension .

Atributo ou elemento	Descrição
`Type` atributo de desktop5:ItemType	Isso define o tipo de itens que você deseja associar ao menu de contexto. Pode ser uma estrela (`*`) se você quiser exibi-la para todos os arquivos; pode ser uma extensão de arquivo específica (`.foo`); ou pode estar disponível para pastas (`Directory`).
`Clsid` atributo de desktop5:Verb	Isso deve corresponder ao CLSID que você registrou anteriormente como servidor COM no arquivo de manifesto do pacote.

Configurar a DLL no pacote

Inclua a DLL que implementa a extensão shell (neste exemplo, ExplorerCommandVerb.dll) na raiz do pacote MSIX. Se você estiver usando o projeto de empacotamento de aplicativos do Windows, a solução mais fácil é copiar e colar a DLL no projeto e garantir que a opção copiar para o Diretório de Saída para as propriedades do arquivo DLL esteja definida como Copiar semais recentes.

Para garantir que o pacote sempre inclua a versão mais recente da DLL, você pode adicionar um evento pós-build ao projeto de extensão shell para que, sempre que você compilá-lo, a DLL seja copiada para o Projeto de Empacotamento de Aplicativos do Windows.

Reiniciar o Explorador de Arquivos

Depois de instalar o pacote de extensão shell, você deve reiniciar o Explorador de Arquivos antes que a extensão shell possa ser carregada. Essa é uma limitação das extensões do Shell implantadas e registradas por meio de pacotes MSIX.

Para testar a extensão do Shell, reinicie o computador ou use o Gerenciador de Tarefas para reiniciar o processo de explorer.exe usando . Depois de fazer isso, você poderá ver a entrada no menu de contexto.