Como implantar uma solução do VSTO ao usar o Windows Installer

Artigo
06/05/2024

Resumo

Saiba como implantar um suplemento do Microsoft Visual Studio Tools para Office (VSTO) ou uma solução em nível de documento ao usar um projeto do Instalador do Visual Studio.

Wouter van Vugt, Code-Counsel

Ted Pattison, Ted Pattison Group

O presente artigo foi atualizado pela Microsoft com permissão dos autores originais.

Aplicável a: Visual Studio Tools para Office, Microsoft Office e Microsoft Visual Studio.

É possível desenvolver uma solução do VSTO e implantá-la ao usar um pacote do Windows Installer. Esta discussão inclui etapas para a implantação de um Suplemento do Office simples.

Métodos de implantação

A tecnologia ClickOnce pode ser usada com facilidade para criar configurações para os Suplementos e para as soluções. No entanto, não é possível instalar Suplementos que requerem privilégios administrativos, como Suplementos em nível do computador, usando essa tecnologia.

Os Suplementos que requerem privilégios administrativos podem ser instalados ao usar o Windows Installer, mas requerem mais esforço para criar a configuração.

Para obter uma visão geral de como implantar uma solução do VSTO ao usar a tecnologia ClickOnce, confira Deploy an Office solution by using ClickOnce.

Como implantar soluções do Office com direcionamento ao runtime do VSTO

Os pacotes para a tecnologia ClickOnce e para o Windows Installer precisam realizar as mesmas tarefas rudimentares ao instalar uma solução do Office.

Instalar os componentes de requisitos prévios no computador do usuário.
Implantar os componentes específicos para a solução.
Para Suplementos, criar entradas do Registro.
Ter confiança na solução para permitir sua execução.

Componentes de requisitos prévios obrigatórios no computador de destino

Veja a seguir a lista de softwares que devem ser instalados no computador para a execução de soluções do VSTO:

O Microsoft Office 2010 ou versões mais recentes.
O Microsoft .NET Framework 4 ou versões mais recentes.
Microsoft Visual Studio 2010 Tools for Office Runtime. O runtime fornece um ambiente que gerencia Suplementos e soluções em nível de documento. Uma versão do Runtime é fornecida com o Microsoft Office, mas talvez você deseje redistribuir uma versão específica com o suplemento.
Os assemblies de Interoperabilidade Primário para o Microsoft Office, se você não estiver usando os Tipos de Interoperabilidade Incorporados.
Os assemblies de utilitários referenciados por projetos.

Componentes específicos para a solução

O pacote de instalação deve instalar estes componentes no computador do usuário:

O documento do Microsoft Office, se você criar uma solução em nível de documento.
O assembly de personalização e os assemblies obrigatórios.
Os componentes adicionais, como os arquivos de configuração.
O manifesto do aplicativo (.manifest).
O manifesto de implantação (.vsto).

Entradas do Registro para os Suplementos

O Microsoft Office usa as entradas do Registro para localizar e carregar Suplementos. Essas entradas do Registro devem ser criadas como parte do processo de implantação. Para obter mais informações sobre essas entradas do Registro, confira Registry entries for VSTO Add-ins.

Os Suplementos do Outlook que exibem regiões do formulário personalizadas requerem entradas do Registro adicionais que permitem a identificação das regiões do formulário. Para obter mais informações sobre as entradas do Registro, confira Registry entries for Outlook form regions.

As soluções em nível de documento não requerem entradas do Registro. Em vez disso, as propriedades dentro do documento são usadas para localizar a personalização. Para obter mais informações sobre essas propriedades, confira Custom Document Properties Overview.

Confiança na solução do VSTO

Para realizar a execução de uma personalização, uma solução deve ser confiável para o computador. O Suplemento pode ser confiável ao assinar o manifesto com um certificado, ao criar uma relação de confiança com uma lista de inclusão ou ao ser instalado em um local confiável no computador.

Para obter mais informações sobre como obter um certificado para assinatura, confira ClickOnce Deployment and Authenticode. Para obter mais informações sobre as soluções confiáveis, confira Trusting Office Solutions by Using Inclusion Lists. É possível adicionar uma entrada da lista de inclusão com uma ação personalizada no arquivo do Windows Installer. Para obter mais informações sobre como habilitar a lista de inclusão, confira How to: Configure Inclusion List Security.

Se nenhuma das opções for usada, uma solicitação de confiança será exibida ao usuário para permitir que ele decida se deseja confiar na solução.

Para obter mais informações sobre a segurança relacionada às soluções em nível de documento, confira Granting Trust to Documents.

Como criar um instalador básico

Os modelos de projeto para a Configuração e para a Implantação estão inclusos na extensão Microsoft Visual Studio Installer Projects que está disponível para download.

Para criar um instalador para uma solução do Office, estas tarefas devem ser realizadas:

Adicionar os componentes da Solução do Office que serão implantados.
Para Suplementos no nível de aplicativo, configurar chaves do Registro.
Configurar os componentes de requisitos prévios para que possam ser instalados nos computadores dos usuários finais.
Configurar as condições de inicialização para verificar se os componentes de requisitos prévios obrigatórios estão disponíveis. As condições de inicialização podem ser usadas para bloquear a instalação se todos os requisitos prévios obrigatórios não estiverem instalados.

A primeira etapa é criar o projeto de configuração.

Para criar o projeto de Configuração do Suplemento

Abra o projeto de Suplemento do Office que você deseja implantar. Para este exemplo, usaremos um Suplemento do Excel chamado ExcelAddIn.
Com o projeto do Office aberto, no menu Arquivo, expanda Adicionar e clique em Novo Projeto para adicionar um novo projeto.

Na caixa de diálogo Adicionar um Novo Projeto, selecione o modelo Projeto de Configuração.
Clique em Avançar.

Na caixa Nome, digite OfficeAddInSetup.

Clique em Criar para criar o novo projeto de configuração.

O Visual Studio abre o Gerenciador do Sistema de Arquivos para o novo projeto de configuração. O Gerenciador do Sistema de Arquivos permite adicionar arquivos ao projeto de configuração.

Captura de tela do Gerenciador do Sistema de Arquivos para o projeto de configuração

Figura 1: o Gerenciador do Sistema de Arquivos para o projeto de configuração

O projeto de configuração precisa implantar o ExcelAddIn. É possível configurar o projeto de configuração para esta tarefa ao adicionar a saída do projeto ExcelAddIn para o projeto de configuração.

Para adicionar a saída do projeto ExcelAddIn

No Gerenciador de Soluções, clique com o botão direito do mouse em OfficeAddInSetup, clique em Adicionar e, em seguida, em Saída do Projeto.
Na caixa de diálogo Adicionar Grupo de Saída do Projeto, selecione ExcelAddIn na lista de projetos e Saída Principal.
Clique em OK para adicionar a saída do projeto ao projeto de configuração.

Figura 2: caixa de diálogo Adicionar Grupo de Saída do Projeto para o Projeto de Configuração

O projeto de configuração precisa implantar o manifesto de implantação e o manifesto do aplicativo. Adicione esses dois arquivos ao projeto de configuração como arquivos independentes da pasta de saída do projeto ExcelAddIn.

Para adicionar os manifestos de implantação e do aplicativo

No Gerenciador de Soluções, clique com o botão direito do mouse em OfficeAddInSetup, clique em Adicionar e escolha Arquivo.
Na caixa de diálogo Adicionar Arquivos, navegue até o diretório de saída ExcelAddIn. Geralmente, o diretório de saída é a subpasta bin\release do diretório raiz do projeto, dependendo da configuração da compilação selecionada.
Selecione os arquivos ExcelAddIn.vsto e ExcelAddIn.dll.manifest e clique em Abrir para adicionar esses dois arquivos ao projeto de configuração.

Figura 3: manifestos do aplicativo e de implantação para o Suplemento no Gerenciador de Soluções

Fazer referência ao ExcelAddIn inclui todos os componentes requeridos pelo ExcelAddIn. Esses componentes devem ser excluídos e implantados usando pacotes de requisitos prévios para permitir que sejam registrados corretamente. Além disso, os Termos de Licença de Software devem ser exibidos e aceitos antes do início da instalação.

Para excluir as dependências do projeto ExcelAddIn

No Gerenciador de Soluções, no nó OfficeAddInSetup, selecione todos os itens de dependência abaixo do item Dependências Detectadas, exceto Microsoft .NET Framework ou outros assemblies que terminem com *.Utilities.dll. Os assemblies de Utilitários devem ser implantados em conjunto com o aplicativo.
Clique com o botão direito do mouse no grupo e selecione Propriedades.
Na janela Propriedades, altere a propriedade Excluir para Verdadeiro a fim de excluir os assemblies dependentes do projeto de configuração. Certifique-se de não excluir nenhum assembly de Utilitários.

Figura 4: exclusão de dependências

É possível configurar o pacote do Windows Installer para instalar componentes de requisitos prévios ao adicionar um programa de Instalação, também conhecido como um inicializador. Este programa de instalação pode instalar os componentes de requisitos prévios, um processo chamado de inicialização.

Para o ExcelAddIn, estes requisitos prévios devem ser instalados antes que a execução do Suplemento possa ocorrer de forma adequada:

A versão do Microsoft .NET Framework destinada à Solução do Office.
O Runtime do Microsoft Visual Studio 2010 Tools para o Office.

Para configurar componentes dependentes como requisitos prévios

No Gerenciador de Soluções, clique com o botão direito do mouse no projeto OfficeAddInSetup e selecione Propriedades.
A caixa de diálogo Páginas de Propriedades do OfficeAddInSetup será exibida.
Clique no botão Requisitos Prévios.
Na caixa de diálogo Requisitos Prévios, selecione a versão correta do .NET Framework e do Runtime do Microsoft Visual Studio Tools para Office.

Figura 5: caixa de diálogo Requisitos Prévios

Observação

Alguns dos pacotes de requisitos prévios configurados em seu projeto de Configuração do Visual Studio são dependentes da configuração da compilação selecionada. Você deve selecionar os componentes de requisitos prévios adequados para cada configuração da compilação usada.

O Microsoft Office localiza os Suplementos ao usar chaves do Registro. As chaves no hive HKEY_CURRENT_USER são usadas para efetuar o registro do suplemento para cada usuário individual. As chaves no hive HKEY_LOCAL_MACHINE são usadas para efetuar o registro do suplemento para todos os usuários do computador. Para obter mais informações sobre chaves do Registro, confira Registry entries for VSTO Add-ins.

Para configurar o Registro

No Gerenciador de Soluções, clique com o botão direito do mouse em OfficeAddInSetup.
Expanda a Exibição.
Clique em Registro para abrir a janela do Editor do Registro.
No editor do Registro (OfficeAddInSetup), expanda HKEY_LOCAL_MACHINE e, em seguida, Software.
Exclua a chave [Fabricante] que é encontrada em HKEY_LOCAL_MACHINE\Software.
Expanda HKEY_CURRENT_USER e, em seguida, Software.
Exclua a chave [Fabricante] que é encontrada em HKEY_CURRENT_USER\Software.
Para adicionar chaves do Registro para a instalação do suplemento, clique com o botão direito do mouse na chave Hive do Usuário/Computador e selecione Nova Chave. Use o texto Software para o nome da nova chave. Clique com o botão direito do mouse na chave de Software recém-criada e crie uma nova chave com o texto Microsoft.
Use um processo semelhante para criar toda a hierarquia de chaves obrigatória para o registro do suplemento:

Hive do Usuário/Computador\Software\Microsoft\Office\Excel\Suplementos\SampleCompany.ExcelAddIn

O Nome da Empresa costuma ser usado como um prefixo para o nome do suplemento a fim de fornecer exclusividade.
Clique com o botão direito do mouse na chave SampleCompany.ExcelAddIn, selecione Novo e clique em Valor da sequência. Use o texto Descrição para o Nome.
Use esta etapa para adicionar mais três valores:
- FriendlyName do tipo Sequência
- LoadBehavior do tipo DWORD
- Manifesto do tipo Sequência
Clique com o botão direito do mouse no valor Descrição no Editor do Registro e clique em Janela Propriedades. Na Janela Propriedades, insira Demonstração de Suplemento do Excel para a propriedade Valor.
Selecione a chave FriendlyName no Editor do Registro. Na Janela Propriedades, altere a propriedade Valor para Demonstração do Suplemento do Excel.
Selecione a chave LoadBehavior no Editor do Registro. Na Janela Propriedades, altere a propriedade Valor para 3.. O valor 3 para LoadBehavior indica que o suplemento deve ser carregado na inicialização do aplicativo host. Para obter mais informações sobre o comportamento de carregamento, confira Registry entries for VSTO Add-ins.
Selecione a chave Manifesto no Editor do Registro. Na Janela Propriedades, altere a propriedade Valor para file:///[TARGETDIR]ExcelAddIn.vsto|vstolocal.

Figura 6: configurações das chaves do Registro

O runtime do VSTO usa essa chave do Registro para localizar o manifesto de implantação. A macro [TARGETDIR] será substituída pela pasta na qual o suplemento está instalado. A macro incluirá o caractere \ à direita, portanto, o nome do arquivo do manifesto de implantação deve ser ExcelAddIn.vsto sem o caractere \. O Postfix vstolocal informa ao runtime do VSTO que o suplemento deve ser carregado desta localização em vez do cache da tecnologia ClickOnce. A remoção desse Postfix fará com que o runtime copie a personalização para o cache da tecnologia ClickOnce.

Aviso

Você deve ter muito cuidado ao usar o Editor do Registro no Visual Studio. Por exemplo, se você definir acidentalmente DeleteAtUninstall para a chave errada, poderá excluir uma parte ativa do Registro, deixando o computador do usuário em um estado divergente ou, pior ainda, avariado.

As versões de 64 bits do Office usarão o hive de Registro de 64 bits para procurar Suplementos. Para efetuar o registro de Suplementos no hive de Registro de 64 bits, a plataforma de destino do projeto de configuração deve ser definida apenas como 64 bits.

Selecione o projeto OfficeAddInSetup no gerenciador de soluções.
Acesse a janela Propriedades e defina a propriedade TargetPlatform como x64.

A instalação de um Suplemento para as versões de 32 bits e de 64 bits do Office exigirá a criação de dois pacotes do MSI separados. Um pacote para 32 bits e outro para 64 bits.

Captura de tela da janela Propriedades mostrando a Plataforma de Destino para o registro de Suplementos com o Office de 64 bits

Figura 7: a Plataforma de Destino para o registro de Suplementos com o Office de 64 bits

Se o pacote do MSI for usado para instalar o Suplemento ou a solução, ele poderá ser instalado sem que os requisitos prévios obrigatórios sejam instalados. É possível usar as Condições de Inicialização no MSI para bloquear a instalação do Suplemento se os requisitos prévios não estiverem instalados.

Configurar uma condição de inicialização para detectar o runtime do VSTO

No Gerenciador de Soluções, clique com o botão direito do mouse em OfficeAddInSetup.
Expanda a Exibição.
Clique em Condições de Inicialização.
No editor de Condições de Inicialização (OfficeAddInSetup), clique com o botão direito do mouse em Requisitos no Computador de Destino e, em seguida, clique em Adicionar Condição de Inicialização do Registro. Esse critério de pesquisa pode realizar pesquisas no Registro para uma chave que o runtime do VSTO instala. Em seguida, o valor da chave ficará disponível para as diversas partes do instalador por meio de uma propriedade nomeada. A condição de inicialização usa a propriedade definida pelo critério de pesquisa para verificar um determinado valor.
No editor Condições de Inicialização (OfficeAddInSetup), selecione o critério de pesquisa Pesquisar por RegistryEntry1, clique com o botão direito do mouse no critério e selecione Janela Propriedades.
Na janela Propriedades, defina estas propriedades:
1. Defina o valor de (Nome) como Pesquisar pelo VSTO 2010 Runtime.
2. Altere o valor de Propriedade para VSTORUNTIMEREDIST.
3. Defina o valor de RegKey como SOFTWARE\Microsoft\VSTO Runtime Setup\v4R.
4. Deixe a propriedade Raiz definida como vsdrrHKLM.
5. Altere a propriedade Valor para Versão.
No editor Condições de Inicialização (OfficeAddInSetup), selecione a condição de inicialização Condition1, clique com o botão direito do mouse na condição e selecione Janela Propriedades.
Na janela Propriedades, defina estas propriedades:
1. Defina o (Nome) para Verificar a disponibilidade do Runtime do VSTO 2010.
2. Altere o valor da Condição para VSTORUNTIMEREDIST>=“10.0.30319”
3. Deixe a propriedade InstallURL em branco.
4. Defina a Mensagem como O Runtime do Visual Studio 2010 Tools para Office não está instalado. Faça a execução de Setup.exe para instalar o Suplemento.
  
  Figura 8: Janela Propriedades para a condição de inicialização Verificar a Disponibilidade do Runtime

A condição de inicialização, apresentada acima, verifica explicitamente a presença do runtime do VSTO quando ele é instalado pelo pacote de inicialização.

Configurar uma condição de inicialização para detectar o runtime do VSTO instalado pelo Office

No editor de Condições de Inicialização (OfficeAddInSetup), clique com o botão direito do mouse em Pesquisar o Computador de Destino e, em seguida, clique em Adicionar Pesquisa do Registro.
Selecione o critério de pesquisa Pesquisar por RegistryEntry1, clique com o botão direito do mouse no critério e selecione Janela Propriedades.
Na janela Propriedades, defina estas propriedades:
1. Defina o valor de (Nome) como Pesquisar pelo Runtime do VSTO para Office.
2. Altere o valor de Propriedade para OfficeRuntime.
3. Defina o valor de RegKey como SOFTWARE\Microsoft\VSTO Runtime Setup\v4.
4. Deixe a propriedade Raiz definida como vsdrrHKLM.
5. Altere a propriedade Valor para Versão.
No editor Condições de Inicialização (OfficeAddInSetup), selecione a condição de inicialização Verificar a disponibilidade do Runtime do VSTO 2010 definida anteriormente, clique com o botão direito do mouse na condição e selecione Janela Propriedades.
Altere o valor da propriedade Condição para VSTORUNTIMEREDIST >=“10.0.30319” OU OFFICERUNTIME>=“10.0.21022”. Os números de versão podem ser diferentes para você, dependendo das versões do runtime requeridas pelo seu Suplemento.

Figura 9: a Janela Propriedades para a condição de inicialização Verificar a Disponibilidade do Runtime por meio do Pacote Redistribuível ou do Office

Se um Suplemento for direcionado para o .NET Framework 4 ou para versões mais recentes, os tipos dentro dos Assemblies de Interoperabilidade Primários (PIA), que são referenciados, poderão ser incorporados ao assembly do VSTO.

Para verificar se os Tipos de Interoperabilidade serão incorporados ao seu Suplemento, execute as seguintes etapas:

Expandir o Nó de Referências no Gerenciador de Soluções.
Selecionar uma das referências do PIA, por exemplo, Office.
Realizar a exibição as janelas de propriedades ao clicar em F4 ou ao selecionar Propriedades no menu de contexto Assemblies.
Verificar o valor da propriedade Tipos de Interoperabilidade Incorporados.

Se o valor estiver definido como Verdadeiro, os Tipos estão sendo incorporados e você pode ignorar e prosseguir para a seção Para desenvolver o projeto de configuração.

Para obter mais informações, confira Equivalência de tipo e tipos de interoperabilidade inseridos.

Para configurar condições de inicialização para detectar isso em PIAs do Office

No editor de Condições de Inicialização (OfficeAddInSetup), clique com o botão direito do mouse em Requisitos no Computador de Destino e, em seguida, clique em Adicionar Condição de Inicialização do Windows Installer. Esta condição de inicialização pesquisa por um PIA do Office ao pesquisar o ID do componente específico.
Clique com o botão direito do mouse em Procurar por Component1 e clique na Janela Propriedades para mostrar as propriedades da condição de inicialização.
Na Janela Propriedades, defina estas propriedades:
1. Altere o valor da propriedade (Nome) para Pesquisar pelo PIA Compartilhado do Office.
2. Altere o valor de ComponentID para a ID do Componente do componente do Office que você está usando. É possível encontrar a lista de IDs de Componentes na tabela abaixo, por exemplo, {64E2917E-AA13-4CA4-BFFE-EA6EDA3AFCB4}.
3. Altere o valor da propriedade Propriedade para HASSHAREDPIA.
No editor Condições de Inicialização (OfficeAddInSetup), clique com o botão direito do mouse em Condition1 e clique na Janela Propriedades para mostrar as propriedades da condição de inicialização.
Altere estas propriedades de Condition1:
1. Altere o (Nome) para Verificar a disponibilidade do PIA Compartilhado do Office.
2. Altere a Condição para HASSHAREDPIA.
3. Deixe InstallURL em branco.
4. Altere a Mensagem para Um componente necessário para interagir com o Excel não está disponível. Faça a execução de setup.exe.
Figura 10: a Janela Propriedades para a condição de inicialização do Verificar o PIA Compartilhado do Office

IDs de Componentes dos Assemblies de Interoperabilidade Primários para o Microsoft Office

Assembly de interoperabilidade primário	Office 2010	Office 2013	Office 2013 (64 bits)	Office 2016	Office 2016 (64 bits)
Excel	{EA7564AC-C67D-4868-BE5C-26E4FC2223FF}	{C8A65ABE-3270-4FD7-B854-50C8082C8F39}	{E3BD1151-B9CA-4D45-A77E-51A6E0ED322A}	{C845E028-E091-442E-8202-21F596C559A0}	{C4ACE6DB-AA99-401F-8BE6-8784BD09F003}
InfoPath	{4153F732-D670-4E44-8AB7-500F2B576BDA}	{0F825A16-25B2-4771-A497-FC8AF3B355D8}	{C5BBD36E-B320-47EF-A512-556B99CB7E41}	-	-
Outlook	{1D844339-3DAE-413E-BC13-62D6A52816B2}	{F9F828D5-9F0B-46F9-9E3E-9C59F3C5E136}	{7824A03F-28CC-4371-BC54-93D15EFC1E7F}	{2C6C511D-4542-4E0C-95D0-05D4406032F2}	{7C6D92EF-7B45-46E5-8670-819663220E4E}
PowerPoint	{EECBA6B8-3A62-44AD-99EB-8666265466F9}	{813139AD-6DAB-4DDD-8C6D-0CA30D073B41}	{05758318-BCFD-4288-AD8D-81185841C235}	{9E73CEA4-29D0-4D16-8FB9-5AB17387C960}	{E0A76492-0FD5-4EC2-8570-AE1BAA61DC88}
Visio	{3EA123B5-6316-452E-9D51-A489E06E2347}	{C1713368-12A8-41F1-ACA1-934B01AD6EEB}	{2CC0B221-22D2-4C15-A9FB-DE818E51AF75}	{A4C55BC1-B94C-4058-B15C-B9D4AE540AD1}	{2D4540EC-2C88-4C28-AE88-2614B5460648}
Word	{8B74A499-37F8-4DEA-B5A0-D72FC501CEFA}	{9FE736B7-B1EE-410C-8D07-082891C3DAC8}	{13C07AF5-B206-4A48-BB5B-B8022333E3CA}	{30CAC893-3CA4-494C-A5E9-A99141352216}	{DC5CCACD-A7AC-4FD3-9F70-9454B5DE5161}
Microsoft Forms 2.0	{B2279272-3FD2-434D-B94E-E4E0F8561AC4}	{B2279272-3FD2-434D-B94E-E4E0F8561AC4}	{A5A30117-2D2A-4C5C-B3C8-8897AC32C2AC}	-	-
Microsoft Graph	{011B9112-EBB1-4A6C-86CB-C2FDC9EA7B0E}	{52DA4B37-B8EB-4B7F-89C1-824654CE4C70}	{24706F33-F0CE-4EB4-BC91-9E935394F510}	-	-
Marcação Inteligente	{7102C98C-EF47-4F04-A227-FE33650BF954}	{487A7921-EB3A-4262-BB5B-A5736B732486}	{74EFC1F9-747D-4867-B951-EFCF29F51AF7}	-	-
Office Compartilhado	{64E2917E-AA13-4CA4-BFFE-EA6EDA3AFCB4}	{6A174BDB-0049-4D1C-86EF-3114CB0C4C4E}	{76601EBB-44A7-49EE-8DE3-7B7B9D7EBB05}	{68477CB0-662A-48FB-AF2E-9573C92869F7}	{625F5772-C1B3-497E-8ABE-7254EDB00506}
Project	{957A4EC0-E67B-4E86-A383-6AF7270B216A}	{1C50E422-24FA-44A9-A120-E88280C8C341}	{706D7F44-8231-489D-9B25-3025ADE9F114}	{0B6EDA1D-4A15-4F88-8B20-EA6528978E4E}	{107BCD9A-F1DC-4004-A444-33706FC10058}

Captura de tela das condições de inicialização Finais

Figura 11: condições de inicialização Finais

É possível otimizar ainda mais as condições de inicialização para a instalação do ExcelAddIn. Por exemplo, pode ser útil verificar se o aplicativo de destino real do Office está instalado.

Para desenvolver o projeto de configuração

No Gerenciador de Soluções, clique com o botão direito do mouse no projeto OfficeAddInSetup e clique em Compilar.
Usando o Windows Explorer, navegue até o diretório de saída do projeto OfficeAddInSetup e acesse a pasta Liberar ou Depurar, dependendo da configuração da compilação selecionada. Copie todos os arquivos da pasta para uma localização que os usuários possam acessar.

Para realizar um teste da configuração do ExcelAddIn

Navegue até a localização para a qual você copiou OfficeAddInSetup.
Efetue um clique duplo no arquivo setup.exe para instalar o suplemento OfficeAddInSetup. Aceite todos os Termos de Licença de Software exibidos e conclua o Assistente de Instalação para instalar o suplemento no computador do usuário.

A solução Excel do Office deve ser instalada e executada usando a localização especificada durante a configuração.

Requisitos adicionais para soluções em nível de documento

A implantação de soluções em nível de documento requer algumas etapas de configuração diferentes no projeto de configuração do Windows Installer.

Veja a seguir uma lista de etapas básicas obrigatórias para implantar uma solução em nível de documento:

Criar o Projeto de Configuração do Visual Studio.
Adicionar a saída principal da solução em nível de documento. A saída principal também inclui o documento do Microsoft Office.
Adicionar os manifestos de implantação e do aplicativo como arquivos soltos.
Excluir os componentes dependentes do pacote de instalação (exceto os assemblies de utilitários).
Configurar os pacotes de requisitos prévios.
Configurar as condições de inicialização.
Realizar a compilação do projeto de configuração e copiar os resultados para a localização de implantação.
Implantar a solução em nível de documento no computador do usuário ao executar a configuração.
Atualizar as propriedades do documento personalizadas, se necessário.

Como alterar a localização do documento implantado

As propriedades dentro de um documento do Office são usadas para localizar soluções em nível de documento. Se o documento estiver instalado na mesma pasta que o assembly do VSTO, alterações não serão necessárias. No entanto, se ele estiver instalado em uma pasta diferente, essas propriedades precisarão ser atualizadas durante a configuração.

Para obter mais informações sobre essas propriedades do documento, confira Custom Document Properties Overview.

Para alterar essas propriedades, é necessário usar uma ação personalizada durante a configuração.

O exemplo apresentado a seguir usa uma solução em nível de documento chamada ExcelWorkbookProject e um projeto de configuração chamado ExcelWorkbookSetup. O projeto ExcelWorkbookSetup é configurado ao usar etapas semelhantes às descritas acima, exceto para definir as chaves do Registro.

Para adicionar o projeto de ação personalizada à solução do Visual Studio

Adicione um novo projeto do Console .NET à solução ao clicar com o botão direito do mouse no Projeto de Implantação de Documentos do Office no Gerenciador de Soluções.
Expanda Adicionar e clique em Novo Projeto.
Selecione o modelo Aplicativo de Console e nomeie o projeto como AddCustomizationCustomAction.

Figura 12: Gerenciador de Soluções - AddCustomizationCustomAction
Adicione uma Referência para estes assemblies:
1. System.ComponentModel
2. System.Configuration.Install
3. Microsoft.VisualStudio.Tools.Applications
4. Microsoft.VisualStudio.Tools.Applications.ServerDocument
Copie este código em Program.cs ou Program.vb

    using System;
    using System.IO;
    using System.Collections;
    using System.ComponentModel;
    using System.Configuration.Install;
    using Microsoft.VisualStudio.Tools.Applications;
    using Microsoft.VisualStudio.Tools.Applications.Runtime;

    namespace AddCustomizationCustomAction
    {
        [RunInstaller(true)]
        public class AddCustomizations : Installer
        {
            public AddCustomizations() : base() { }

            public override void Install(IDictionary savedState)
            {
                base.Install(savedState);

                //Get the CustomActionData Parameters
                string documentLocation = Context.Parameters.ContainsKey("documentLocation") ? Context.Parameters["documentLocation"] : String.Empty;
                string assemblyLocation = Context.Parameters.ContainsKey("assemblyLocation") ? Context.Parameters["assemblyLocation"] : String.Empty;
                string deploymentManifestLocation = Context.Parameters.ContainsKey("deploymentManifestLocation") ? Context.Parameters["deploymentManifestLocation"] : String.Empty;
                Guid solutionID = Context.Parameters.ContainsKey("solutionID") ? new Guid(Context.Parameters["solutionID"]) : new Guid();

                string newDocLocation = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments), Path.GetFileName(documentLocation));

                try
                {
                    //Move the file and set the Customizations
                    if (Uri.TryCreate(deploymentManifestLocation, UriKind.Absolute, out Uri docManifestLocationUri))
                    {
                        File.Move(documentLocation, newDocLocation);
                        ServerDocument.RemoveCustomization(newDocLocation);
                        ServerDocument.AddCustomization(newDocLocation, assemblyLocation,
                                                        solutionID, docManifestLocationUri,
                                                        true, out string[] nonpublicCachedDataMembers);
                    }
                    else
                    {
                        LogMessage("The document could not be customized.");
                    }
                }
                catch (ArgumentException)
                {
                    LogMessage("The document could not be customized.");
                }
                catch (DocumentNotCustomizedException)
                {
                    LogMessage("The document could not be customized.");
                }
                catch (InvalidOperationException)
                {
                    LogMessage("The customization could not be removed.");
                }
                catch (IOException)
                {
                    LogMessage("The document does not exist or is read-only.");
                }
            }

            public override void Rollback(IDictionary savedState)
            {
                base.Rollback(savedState);
                DeleteDocument();
            }
            public override void Uninstall(IDictionary savedState)
            {
                base.Uninstall(savedState);
                DeleteDocument();
            }
            private void DeleteDocument()
            {
                string documentLocation = Context.Parameters.ContainsKey("documentLocation") ? Context.Parameters["documentLocation"] : String.Empty;

                try
                {
                    File.Delete(Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments), Path.GetFileName(documentLocation)));
                }
                catch (Exception)
                {
                    LogMessage("The document doesn't exist or is read-only.");
                }
            }
            private void LogMessage(string Message)
            {
                if (Context.Parameters.ContainsKey("LogFile"))
                {
                    Context.LogMessage(Message);
                }
            }

            static void Main() { }
            }
    }

Para adicionar a personalização ao documento, é necessário ter a ID da solução em nível de documento do VSTO. Esse valor é recuperado do arquivo de projeto do Visual Studio.

Para recuperar a ID da solução

No menu Compilar, clique em Compilar Solução para compilar a solução em nível de documento e adicionar a propriedade ID da solução ao arquivo de projeto.
No Gerenciador de Soluções, clique com o botão direito do mouse no projeto em nível de documento ExcelWorkbookProject.
Clique em UnloadProject para obter acesso ao arquivo de projeto do Visual Studio.

Figura 13: como descarregar a solução de documento do Excel
No Gerenciador de Soluções, clique com o botão direito do mouse em ExcelWorkbookProject e clique em EditExcelWorkbookProject.vbproj ou em Edit ExcelWorkbookProject.csproj.
No editor ExcelWorkbookProject, localize o elemento SolutionID no elemento PropertyGroup.
Copie o valor GUID deste elemento.

Figura 14: como recuperar o elemento SolutionID
No Gerenciador de Soluções, clique com o botão direito do mouse em ExcelWorkbookProject e clique em Recarregar Projeto.
Clique em Sim na caixa de diálogo que aparece para fechar o editor ExcelWorkbookProject.
A ID da Solução será usada na Ação Personalizada Instalar.

A última etapa é configurar a ação personalizada para as etapas Instalar e Desinstalar.

Para configurar o projeto de configuração

No Gerenciador de Soluções, clique com o botão direito do mouse em ExcelWorkbookSetup, expanda Adicionar e clique em Saída do Projeto.
Na caixa de diálogo Adicionar Grupo de Saída do Projeto, na lista Projeto, clique em AddCustomizationCustomAction.
Selecione Saída Principal e clique em OK para fechar a caixa de diálogo e adicionar a assembly que contém a ação personalizada ao projeto de configuração.

Figura 15: Ação Personalizada do Manifesto do Documento - Adicionar Grupo de Saída do Projeto
No Gerenciador de Soluções, clique com o botão direito do mouse em ExcelWorkbookSetup.
Expanda a Exibição e clique em Ações Personalizadas.
No editor de Ações Personalizadas (ExcelWorkbookSetup), clique com o botão direito do mouse em Ações Personalizadas e clique em Adicionar Ação Personalizada.
Na caixa de diálogo Selecionar Item no Projeto, na lista Examinar, clique em Pasta do Aplicativo. Selecione Saída Principal de AddCustomizationCustomAction(active) e clique em OK para adicionar a ação personalizada à etapa Instalar.
No nó Instalar, clique com o botão direito do mouse em Saída principal de AddCustomizationCustomAction(Active) e clique em Renomear. Nomeie a ação personalizada como Copiar documento para Meus Documentos e anexar a personalização.
No nó Desinstalar, clique com o botão direito do mouse em Saída principal de AddCustomizationCustomAction(Active) e clique em Renomear. Nomeie a ação personalizada como Remover documento da pasta Documentos.

Figura 16: Ações Personalizadas do Manifesto do Documento
No editor Ações Personalizadas (ExcelWorkbookSetup), clique com o botão direito do mouse em Copiar documento para Meus Documentos e anexar personalização e clique em Janela Propriedades.
Na janela PropriedadesCustomActionData, insira a localização da DLL de personalização, o manifesto de implantação e a localização do documento do Microsoft Office. O SolutionID também é necessário.

Se desejar efetuar o registro em log de erros de configuração em um arquivo, inclua um parâmetro LogFile. s

/assemblyLocation="[INSTALLDIR]ExcelWorkbookProject.dll" /deploymentManifestLocation="[INSTALLDIR]ExcelWorkbookProject.vsto" /documentLocation="[INSTALLDIR]ExcelWorkbookProject.xlsx" /solutionID="Your Solution ID" /LogFile="[TARGETDIR]Setup.log"

Captura de tela da janela Propriedades de Ação Personalizada para Copiar Documento para Meus Documentos

Figura 17: Ação Personalizada para Copiar Documento para Meus Documentos

A Ação Personalizada para Desinstalar precisa do nome do documento. É possível fornecer isso ao usar o mesmo parâmetro documentLocation no CustomActionData.
```
/documentLocation="[INSTALLDIR]ExcelWorkbookProject.xlsx"
```
Compile e implante o projeto ExcelWorkbookSetup.
Procure na pasta Meus Documentos e abra o arquivo ExcelWorkbookProject.xlsx.

Recursos adicionais

How to: Install the Visual Studio Tools for Office Runtime

Assemblies de interoperabilidade primários do Office

Registry entries for VSTO Add-ins

Visão geral de propriedades de documento personalizadas

Specifying Form Regions in the Windows Registry

Concedendo confiança a documentos

Sobre os autores

Wouter van Vugt é um Microsoft MVP no escopo de tecnologias Office Open XML e atua como consultor independente com foco na criação de Aplicativos de Negócios do Office (OBAs) com o SharePoint, o Microsoft Office e as tecnologias .NET relacionadas. O Wouter é um contribuidor frequente de sites de comunidades de desenvolvedores como o MSDN. Ele publicou diversos white papers e artigos, bem como um livro eletrônico disponível on-line intitulado Open XML: Explained. Wouter é o fundador da Code-Counsel, uma empresa holandesa com foco no fornecimento de conteúdo técnico de ponta por meio de diversos canais. É possível descobrir mais sobre o Wouter ao ler o blog dele.

Ted Pattison é MVP do SharePoint, autor, treinador e fundador do Ted Pattison Group. No outono de 2005, Ted foi contratado pelo grupo de divulgação da plataforma de desenvolvedores da Microsoft para a criação do currículo de treinamento de desenvolvedor Ascend para o Windows SharePoint Services 3.0 e para o Microsoft Office SharePoint Server 2007. Desde esse momento, Ted tem se concentrado inteiramente em instruir desenvolvedores profissionais nas tecnologias do SharePoint 2007. Ted terminou de escrever um livro para a Microsoft Press intitulado Inside Windows SharePoint Services 3.0, que se concentra em como usar o SharePoint como uma plataforma de desenvolvimento para desenvolver soluções de negócios. Ted também escreve uma coluna com foco em desenvolvedores para a MSDN Magazine intitulada Office Space.

Compartilhar via

Como implantar uma solução do VSTO ao usar o Windows Installer

Resumo

Métodos de implantação

Como implantar soluções do Office com direcionamento ao runtime do VSTO

Componentes de requisitos prévios obrigatórios no computador de destino

Componentes específicos para a solução

Entradas do Registro para os Suplementos

Confiança na solução do VSTO

Como criar um instalador básico

Para criar o projeto de Configuração do Suplemento

Para adicionar a saída do projeto ExcelAddIn

Para adicionar os manifestos de implantação e do aplicativo

Para excluir as dependências do projeto ExcelAddIn

Para configurar o Registro

Configurar uma condição de inicialização para detectar o runtime do VSTO

Configurar uma condição de inicialização para detectar o runtime do VSTO instalado pelo Office

Para configurar condições de inicialização para detectar isso em PIAs do Office

IDs de Componentes dos Assemblies de Interoperabilidade Primários para o Microsoft Office

Para desenvolver o projeto de configuração

Requisitos adicionais para soluções em nível de documento

Como alterar a localização do documento implantado

Para configurar o projeto de configuração

Recursos adicionais

Sobre os autores

Comentários

Comentários

Recursos adicionais