Implantando uma solução VSTO usando o Windows Installer
Resumo
Saiba como implantar um suplemento do Microsoft Visual Studio Tools for Office (VSTO) ou uma solução em nível de documento usando um projeto do Visual Studio Installer.
Wouter van Vugt, Advogado de Código
Ted Pattison, Grupo Ted Pattison
Este artigo foi atualizado pela Microsoft com permissão dos autores originais.
Aplica-se a: Visual Studio Tools for Office, Microsoft Office, Microsoft Visual Studio.
Você pode desenvolver uma solução VSTO e implantar a solução usando um pacote do Windows Installer. Esta discussão inclui etapas para implantar um Suplemento do Office simples.
Métodos de implantação
O ClickOnce pode ser facilmente usado para criar configurações para seus suplementos e soluções. No entanto, ele não pode instalar suplementos que exigem privilégios administrativos, como suplementos no nível do computador.
Os suplementos que exigem privilégios administrativos podem ser instalados usando o Windows Installer, mas exigem mais esforço para criar a instalação.
Para obter uma visão geral de como implantar uma solução VSTO usando o ClickOnce, consulte Implantar uma solução do Office usando o ClickOnce.
Implantando soluções do Office destinadas ao tempo de execução do VSTO
Os pacotes ClickOnce e Windows Installer precisam fazer as mesmas tarefas rudimentares ao instalar uma solução do Office.
- Instale os componentes de pré-requisito no computador do usuário.
- Implante os componentes específicos para a solução.
- Para Suplementos, crie entradas do Registro.
- Confie na solução para permitir que ela seja executada.
Componentes de pré-requisito necessários no computador de destino
Aqui está a lista de softwares que devem ser instalados no computador para executar soluções VSTO:
- Microsoft Office 2010 ou mais recente.
- O Microsoft .NET Framework 4 ou mais recente.
- Microsoft Visual Studio 2010 Tools for Office Runtime. O tempo de execução 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ê queira redistribuir uma versão específica com seu suplemento.
- Os assemblies de interoperabilidade primária para o Microsoft Office, se você não estiver usando tipos de interoperabilidade incorporados.
- Quaisquer montagens de utilitários referenciadas por projetos.
Componentes específicos para a solução
O pacote do instalador deve instalar esses 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 quaisquer montagens necessárias.
- Componentes adicionais, como arquivos de configuração.
- O manifesto do aplicativo (. manifest).
- O manifesto de implantação (.vsto).
Entradas do Registro para suplementos
O Microsoft Office usa 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, consulte Entradas do Registro para suplementos VSTO.
Os suplementos do Outlook que exibem regiões de formulário personalizadas exigem entradas de registro adicionais que permitem que as regiões de formulário sejam identificadas. Para obter mais informações sobre entradas do Registro, consulte Entradas do Registro para regiões de formulário do Outlook.
As soluções em nível de documento não exigem nenhuma entrada 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, consulte Visão geral das propriedades personalizadas do documento.
Confiando na solução VSTO
Para que uma personalização seja executada, uma solução deve ser confiável para a máquina. O suplemento pode ser confiável assinando o manifesto com um certificado, criando uma relação de confiança com uma lista de inclusão ou instalando-o em um local confiável na máquina.
Para obter mais informações sobre como obter um certificado para assinatura, consulte Implantação do ClickOnce e Authenticode. Para obter mais informações sobre soluções confiáveis, consulte Confiando em soluções do Office usando listas de inclusão. Você pode adicionar uma entrada de 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, consulte Como configurar a segurança da lista de inclusão.
Se nenhuma das opções for usada, um prompt de confiança será exibido ao usuário para permitir que ele decida se deseja confiar na solução.
Para obter mais informações sobre segurança relacionada a soluções em nível de documento, consulte Concedendo confiança a documentos.
Criando um instalador básico
Os modelos de projeto de instalação e implantação estão incluídos com a 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:
- Adicione os componentes da Solução do Office que serão implantados.
- Para suplementos no nível do aplicativo, configure as chaves do Registro.
- Configure os componentes de pré-requisito para que possam ser instalados nos computadores dos usuários finais.
- Configure as condições de inicialização para verificar se os componentes de pré-requisito necessários estão disponíveis. As condições de inicialização podem ser usadas para bloquear a instalação se todos os pré-requisitos necessários não estiverem instalados.
O primeiro passo é criar o projeto de instalação.
Para criar o projeto de instalação do AddIn
- Abra o Projeto AddIn do Office que você deseja implantar. Para este exemplo, estamos usando um suplemento do Excel chamado ExcelAddIn.
- Com o Office Project Open, 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 Instalação.
- Clique em Avançar.
- Na caixa Nome, digite OfficeAddInSetup.
- Clique em Criar para criar o novo projeto de instalação.
O Visual Studio abre o Gerenciador do Sistema de Arquivos para o novo projeto de instalação. O Gerenciador do Sistema de Arquivos permite que você adicione arquivos ao projeto de instalação.
Figura 1: File System Explorer para o projeto de instalação
O projeto de instalação precisa implantar o ExcelAddIn. Você pode configurar o projeto de instalação para esta tarefa adicionando a saída do projeto ExcelAddIn ao projeto de instalaçã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 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 Primária.
Clique em OK para adicionar a saída do projeto ao projeto de instalação.
Figura 2: Caixa de diálogo Adicionar grupo de saída do projeto de instalação
O projeto de instalação precisa implantar o manifesto de implantação e o manifesto do aplicativo. Adicione esses dois arquivos ao projeto de instalação como arquivos autônomos da pasta de saída do projeto ExcelAddIn.
Para adicionar os manifestos de implantação e de aplicativo
No Gerenciador de Soluções, clique com o botão direito do mouse em OfficeAddInSetup, clique em Adicionar e clique em Arquivo.
Na caixa de diálogo Adicionar arquivos, navegue até o diretório de saída ExcelAddIn. Normalmente, o diretório de saída é a subpasta bin\release do diretório raiz do projeto, dependendo da configuração de compilação selecionada.
Selecione os arquivos ExcelAddIn.vsto e ExcelAddIn.dll.manifest e clique em Abrir para adicionar esses dois arquivos ao projeto de instalação.
Figura 3: Manifestos de aplicativo e implantação para o suplemento no Gerenciador de Soluções
Referenciar o ExcelAddIn inclui todos os componentes que o ExcelAddIn requer. Esses componentes devem ser excluídos e implantados usando pacotes de pré-requisitos para permitir que sejam registrados corretamente. Além disso, os Termos de Licença para 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 qualquer assembly que termine com *. Utilitários.dll. Os assemblies de utilitários devem ser implantados junto com seu aplicativo.
Clique com o botão direito do mouse no grupo e selecione Propriedades.
Na janela Propriedades, altere a propriedade Exclude para True para excluir os assemblies dependentes do projeto de instalação. Certifique-se de não excluir nenhum assembly de utilitários.
Figura 4: Excluindo dependências
Você pode configurar o pacote do Windows Installer para instalar componentes de pré-requisito adicionando um programa de instalação, também conhecido como bootstrapper. Este programa de instalação pode instalar os componentes de pré-requisito, um processo chamado bootstrapping.
Para o ExcelAddIn, esses pré-requisitos devem ser instalados para que o suplemento possa ser executado corretamente:
- A versão do Microsoft .NET Framework que a solução do Office destina.
- Ferramentas do Microsoft Visual Studio 2010 para Office Runtime.
Para configurar componentes dependentes como pré-requisitos
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 OfficeAddInSetup é exibida.
Clique no botão Pré-requisitos .
Na caixa de diálogo Pré-requisitos, selecione a versão correta do .NET Framework e o Microsoft Visual Studio Tools for Office Runtime.
Figura 5: Caixa de diálogo Pré-requisitos
Observação
Alguns dos pacotes de pré-requisitos configurados em seu projeto de instalação do Visual Studio dependem da configuração de compilação selecionada. Você deve selecionar os componentes de pré-requisito corretos para cada configuração de compilação usada.
O Microsoft Office localiza suplementos usando chaves do Registro. As chaves na seção HKEY_CURRENT_USER são usadas para registrar o suplemento para cada usuário individual. As chaves sob a seção HKEY_LOCAL_MACHINE são usadas para registrar o suplemento para todos os usuários da máquina. Para obter mais informações sobre chaves do Registro, consulte Entradas do Registro para suplementos VSTO.
Para configurar o registro
No Gerenciador de Soluções, clique com o botão direito do mouse em OfficeAddInSetup.
Expanda Exibir.
Clique em Registro para abrir a janela do editor do Registro .
No editor Registry(OfficeAddInSetup), expanda HKEY_LOCAL_MACHINE e, em seguida, Software.
Exclua a chave [Fabricante] encontrada em HKEY_LOCAL_MACHINE\Software.
Expanda HKEY_CURRENT_USER e, em seguida, Software.
Exclua a chave [Fabricante] 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 Usuário/Máquina, selecione Nova Chave. Use o texto Software para o nome da nova chave. Clique com o botão direito do mouse na chave Software recém-criada e crie uma nova chave com o texto Microsoft.
Use um processo semelhante para criar toda a hierarquia de chaves necessária para o registro do suplemento:
Usuário/Máquina Hive\Software\Microsoft\Office\Excel\Addins\SampleCompany.ExcelAddIn
O Nome da Empresa é frequentemente usado como um prefixo para o nome do suplemento para fornecer exclusividade.
Clique com o botão direito do mouse na chave SampleCompany.ExcelAddIn , selecione Novo e clique em Valor da cadeia de caracteres. Use o texto Descrição para o Nome.
Use esta etapa para adicionar mais três valores:
- FriendlyName do tipo String
- LoadBehavior do tipo DWORD
- Manifesto do tipo String
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 Excel Demo AddIn para a propriedade Value.
Selecione a chave FriendlyName no editor do Registro. Na janela Propriedades, altere a propriedade Value para Excel Demo AddIn.
Selecione a chave LoadBehavior no editor do Registro. Na janela Propriedades, altere a propriedade Value para 3. O valor 3 para o LoadBehavior indica que o suplemento deve ser carregado na inicialização do aplicativo host. Para obter mais informações sobre o comportamento de carregamento, consulte Entradas do Registro para suplementos VSTO.
Selecione a chave Manifest no editor do Registro. Na janela Propriedades, altere a propriedade Value para file:///[TARGETDIR]ExcelAddIn.vsto|vstolocal
Figura 6: Configurando chaves do Registro
O tempo de execução do VSTO usa essa chave do Registro para localizar o manifesto de implantação. A macro [TARGETDIR] será substituída pela pasta onde 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 tempo de execução do VSTO que o suplemento deve ser carregado desse local em vez do cache ClickOnce. A remoção desse postfix fará com que o tempo de execução copie a personalização para o cache do ClickOnce.
Aviso
Você deve ter muito cuidado com o Editor do Registro no Visual Studio. Por exemplo, se você acidentalmente definir DeleteAtUninstall para a chave errada, você pode excluir uma parte ativa do registro, deixando o computador do usuário em um estado inconsistente, ou ainda pior, quebrado.
As versões de 64 bits do Office usarão o hive do Registro de 64 bits para procurar suplementos. Para registrar suplementos na seção do Registro de 64 bits, a plataforma de destino do projeto de instalação deve ser definida como somente 64 bits.
- Selecione o projeto OfficeAddInSetup no gerenciador de soluções.
- Vá para a janela Propriedades e defina a propriedade TargetPlatform como x64.
A instalação de um suplemento para as versões de 32 bits e 64 bits do Office exigirá que você crie dois pacotes MSI separados. Um para 32 bits e outro para 64 bits.
Figura 7: Plataforma de destino para registrar suplementos com o Office de 64 bits
Se o pacote MSI for usado para instalar o suplemento ou a solução, ele poderá ser instalado sem que os pré-requisitos necessários sejam instalados. Você pode usar Condições de Inicialização no MSI para bloquear a instalação do suplemento se os pré-requisitos não estiverem instalados.
Configurar uma condição de inicialização para detectar o VSTO Runtime
No Gerenciador de Soluções, clique com o botão direito do mouse em OfficeAddInSetup.
Expanda Exibir.
Clique em Condições de Inicialização.
No editor Condições de Inicialização(OfficeAddInSetup), clique com o botão direito do mouse em Requisitos no Computador de Destino e clique em Adicionar Condição de Inicialização do Registro. Essa condição de pesquisa pode procurar no Registro uma chave que o tempo de execução do VSTO instale. O valor da chave é então disponível para as várias partes do instalador através de uma propriedade nomeada. A condição de inicialização usa a propriedade definida pela condição de pesquisa para verificar um determinado valor.
No editor Condições de Inicialização(OfficeAddInSetup), selecione a condição de pesquisa Pesquisar RegistryEntry1, clique com o botão direito do mouse na condição e selecione Janela Propriedades.
Na janela Propriedades, defina estas propriedades:
- Defina o valor de (Name) como Search for VSTO 2010 Runtime.
- Altere o valor de Property para VSTORUNTIMEREDIST.
- Defina o valor de RegKey como SOFTWARE\Microsoft\VSTO Runtime Setup\v4R
- Deixe a propriedade Root definida como vsdrrHKLM.
- Altere a propriedade Value para Version.
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:
Defina o (Name) para Verificar a disponibilidade do VSTO 2010 Runtime.
Altere o valor da condição para VSTORUNTIMEREDIST>="10.0.30319"
Deixe a propriedade InstallURL em branco.
Defina a mensagem como O Visual Studio 2010 Tools for Office Runtime não está instalado. Execute a instalação.exe para instalar o suplemento.
Figura 8: Janela Propriedades para a condição de inicialização Verify Runtime Availability
A condição de inicialização acima verifica explicitamente a presença do tempo de execução do VSTO quando ele é instalado pelo pacote bootstrapper.
Configurar uma condição de inicialização para detectar o VSTO Runtime instalado pelo Office
No editor Condições de Inicialização(OfficeAddInSetup), clique com o botão direito do mouse em Search Target Machine e clique em Add Registry Search (Adicionar Pesquisa do Registro).
Selecione a condição de pesquisa Pesquisar RegistryEntry1 , clique com o botão direito do mouse na condição e selecione Janela Propriedades.
Na janela Propriedades, defina estas propriedades:
- Defina o valor de (Name) como Search for Office VSTO Runtime.
- Altere o valor de Property para OfficeRuntime.
- Defina o valor de RegKey como SOFTWARE\Microsoft\VSTO Runtime Setup\v4.
- Deixe a propriedade Root definida como vsdrrHKLM.
- Altere a propriedade Value para Version.
No editor Condições de Inicialização(OfficeAddInSetup), selecione a condição de inicialização Verificar disponibilidade do VSTO 2010 Runtime definida anteriormente, clique com o botão direito do mouse na condição e selecione Janela Propriedades.
Altere o valor da propriedade Condition 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 tempo de execução que seu suplemento exige.
Figura 9: Propriedades do Windows para a condição Verificar disponibilidade do tempo de execução por meio do Redist ou da inicialização do Office
Se um suplemento tem como destino o .NET Framework 4 ou mais recente, os tipos dentro dos assemblies de interoperabilidade primários (PIA), que são referenciados, podem ser incorporados ao assembly VSTO.
Para verificar se os tipos de interoperabilidade serão incorporados em seu suplemento executando as seguintes etapas:
- Expandir o nó Referências no Gerenciador de Soluções
- Selecione uma das referências do PIA, por exemplo, Office.
- Exiba as janelas de propriedades pressionando F4 ou selecionando Propriedades no menu de contexto Assemblies.
- Verifique o valor da propriedade Embed Interop Types.
Se o valor estiver definido como True, os Tipos estão sendo incorporados e você pode pular para a seção Para criar o projeto de instalação.
Para obter mais informações, consulte Equivalência de tipos e tipos de interoperabilidade incorporados
Para configurar condições de inicialização para detectar isso para PIAs do Office
No editor Condições de Inicialização(OfficeAddInSetup), clique com o botão direito do mouse em Requisitos no Computador de Destino e clique em Adicionar Condição de Inicialização do Windows Installer. Essa condição de inicialização procura um PIA do Office pesquisando a ID do componente específico.
Clique com o botão direito do mouse em Procurar Componente1 e clique em Janela de Propriedades para mostrar as propriedades da condição de inicialização.
Na janela Propriedades, defina estas propriedades:
- Altere o valor da propriedade (Name) para Search for Office Shared PIA
- Altere o valor de ComponentID para Component Id para o componente do Office que você está usando. Você pode encontrar a lista de IDs de componentes na tabela abaixo, por exemplo {64E2917E-AA13-4CA4-BFFE-EA6EDA3AFCB4}.
- Altere o valor da propriedade Property para HASSHAREDPIA.
No editor Condições de Inicialização(OfficeAddInSetup), clique com o botão direito do mouse em Condition1 e clique em Janela de Propriedades para mostrar as propriedades da condição de inicialização.
Altere estas propriedades de Condition1:
- Altere o (Nome) para Verificar a disponibilidade do PIA compartilhado do Office.
- Altere a condição para HASSHAREDPIA.
- Deixe InstallUrl em branco.
- Alterar a mensagem para um componente necessário para interagir com o Excel não está disponível. Execute a instalação.exe.
Figura 10: Janela Propriedades para a condição de inicialização Verificar PIA compartilhado do Office
IDs de componente dos assemblies de interoperabilidade primários para o Microsoft Office
| Montagem de interoperabilidade primária | 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} | - | - |
| Escritório 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} |
| Projeto | {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} |
Figura 11: Condições finais de lançamento
Você pode refinar ainda mais as condições de inicialização para a instalação do ExcelAddIn. Por exemplo, talvez seja útil verificar se o aplicativo do Office de destino real está instalado.
Para criar o projeto de instalaçã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 vá para a pasta Release ou Debug, dependendo da configuração de compilação selecionada. Copie todos os arquivos da pasta para um local que os usuários possam acessar.
Para testar a instalação do ExcelAddIn
- Navegue até o local para o qual você copiou OfficeAddInSetup .
- Clique duas vezes no arquivo .exe instalação para instalar o suplemento OfficeAddInSetup . Aceite os Termos de Licença para Software exibidos e conclua o assistente de configuração para instalar o suplemento no computador do usuário.
A solução do Excel Office deve ser instalada e executada a partir do local especificado durante a instalaçã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 instalação do Windows Installer.
Aqui está uma lista de etapas básicas necessárias para implantar uma solução em nível de documento:
- Crie o projeto de instalação do Visual Studio.
- Adicione a saída principal da sua solução em nível de documento. A saída principal também inclui o documento do Microsoft Office.
- Adicione os manifestos de implantação e aplicativo como arquivos soltos.
- Exclua os componentes dependentes do pacote do instalador (exceto para quaisquer assemblies de utilitários).
- Configurar pacotes de pré-requisitos.
- Configurar condições de inicialização.
- Crie o projeto de instalação e copie os resultados para o local de implantação.
- Implante a solução em nível de documento no computador do usuário executando a instalação.
- Atualize as propriedades personalizadas do documento, se necessário.
Alterando o local 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 VSTO, nenhuma alteração será necessária. No entanto, se ele estiver instalado em pasta diferente, essas propriedades precisarão ser atualizadas durante a instalação.
Para obter mais informações sobre essas propriedades do documento, consulte Visão geral das propriedades personalizadas do documento.
Para alterar essas propriedades, você precisa usar uma ação personalizada durante a instalação.
O exemplo a seguir usa uma solução de nível de documento chamada ExcelWorkbookProject e um projeto de instalação chamado ExcelWorkbookSetup. O projeto ExcelWorkbookSetup é configurado usando as mesmas etapas descritas acima, exceto para definir as chaves do Registro.
Para adicionar o projeto de ação personalizada à sua solução do Visual Studio
Adicione um novo projeto do Console .NET à solução clicando com o botão direito do mouse no Projeto de Implantação de Documento do Office no Gerenciador de Soluções
Expanda Adicionar e clique em Novo Projeto.
Selecione o modelo Aplicativo de Console e nomeie o projeto AddCustomizationCustomAction.
Figura 12: Gerenciador de Soluções - AddCustomizationCustomAction
Adicione uma referência a estes assemblies:
- System.ComponentModel
- System.Configuration.Install
- Microsoft.VisualStudio.Tools.Applications
- Microsoft.VisualStudio.Tools.Applications.ServerDocument
Copie este código para Programa.cs ou Programa.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, você precisa ter a ID da solução de nível de documento 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 criar 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 de nível de documento ExcelWorkbookProject
Clique em UnloadProject para acessar o arquivo de projeto de dentro do Visual Studio.
Figura 13: Descarregando 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 dentro do elemento PropertyGroup.
Copie o valor GUID deste elemento.
Figura 14: Recuperando o 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 de Instalação.
A última etapa é configurar a ação personalizada para as etapas de Instalação e Desinstalação .
Para configurar o projeto de instalaçã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 primária e clique em OK para fechar a caixa de diálogo e adicionar o assembly que contém a ação personalizada ao projeto de instalação.
Figura 15: Ação personalizada de manifesto de documento - Adicionar grupo de saída do projeto
No Gerenciador de Soluções, clique com o botão direito do mouse em ExcelWorkbookSetup.
Expanda Exibir e clique em Ações Personalizadas.
No editor 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 primária 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 primária de AddCustomizationCustomAction(Active) e clique em Renomear. Nomeie a ação personalizada Copiar documento para Meus Documentos e anexe personalização.
No nó Desinstalar, clique com o botão direito do mouse em Saída primária de AddCustomizationCustomAction(Active) e clique em Renomear. Nomeie a ação personalizada 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 anexe personalização e clique em Janela Propriedades.
Na janela Propriedades de CustomActionData, insira o local da DLL de personalização, o manifesto de implantação e o local do documento do Microsoft Office. O SolutionID também é necessário.
Se você deseja registrar quaisquer erros de instalaçã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"
Figura 17: Ação personalizada para copiar documento para meus documentos
A Ação Personalizada para Desinstalação precisa do nome do documento, você pode fornecê-lo usando o mesmo parâmetro documentLocation no CustomActionData
/documentLocation="[INSTALLDIR]ExcelWorkbookProject.xlsx"Compile e implante o projeto ExcelWorkbookSetup .
Examine a pasta Meus documentos e abra o arquivo ExcelWorkbookProject.xlsx .
Recursos adicionais
Como: Instalar o Visual Studio Tools for Office Runtime
Assemblies de interoperabilidade primários do Office
Entradas do Registro para suplementos VSTO
Visão geral de propriedades de documento personalizadas
Especificando regiões de formulário no Registro do Windows
Concedendo confiança a documentos
Sobre os autores
Wouter van Vugt é um MVP da Microsoft com tecnologias Office Open XML e um consultor independente com foco na criação de Office Business Applications (OBAs) com SharePoint, Microsoft Office e tecnologias .NET relacionadas. Wouter é um colaborador frequente de sites da comunidade de desenvolvedores, como o MSDN. Ele publicou vários white papers e artigos, bem como um livro disponível on-line intitulado Open XML: Explained e-book. Wouter é o fundador da Code-Counsel, uma empresa holandesa focada em fornecer conteúdo técnico de ponta por meio de uma variedade de canais. Você pode descobrir mais sobre Wouter lendo seu blog.
Ted Pattison é MVP do SharePoint, autor, treinador e fundador do Ted Pattison Group. No outono de 2005, Ted foi contratado pelo grupo Developer Platform Evangelism da Microsoft para criar o currículo de treinamento de desenvolvedor Ascend para Windows SharePoint Services 3.0 e Microsoft Office SharePoint Server 2007. Desde então, Ted tem se concentrado inteiramente em educar desenvolvedores profissionais sobre as 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 criar soluções de negócios. Ted também escreve uma coluna focada no desenvolvedor para a MSDN Magazine intitulada Office Space.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de