Implantando uma solução VSTO usando o Windows Installer

Resumo

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

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: Ferramentas do Visual Studio para Office, Microsoft Office, Microsoft Visual Studio.

Você pode desenvolver uma solução VSTO e implantar a solução usando um pacote do Windows Installer. Essa discussão inclui etapas para implantar um suplemento simples do Office.

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 complementos que exigem privilégios administrativos, como complementos em nível de máquina.

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

Implantando soluções do Office direcionadas ao runtime do VSTO

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

1. Instale componentes de pré-requisito no computador do usuário.
2. Implante os componentes específicos para a solução.
3. Para complementos, crie entradas de registros.
4. 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.
• As Ferramentas do Microsoft Visual Studio 2010 para Office Runtime. O runtime fornece um ambiente que gerencia suplementos e soluções de nível de documento. Uma versão do Runtime é enviada com o Microsoft Office, mas talvez você queira redistribuir uma versão específica com seu suplemento.
• Os assemblies de interoperabilidade primários do Microsoft Office, caso você não esteja usando tipos de interoperabilidade embutidos.
• Todos os assemblies de utilitários referenciados por os 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, caso você crie uma solução de nível de documento.
• O conjunto de personalização e quaisquer conjuntos que ele requer.
• 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 de registro para localizar e carregar suplementos. Essas entradas do Registro devem ser criadas como parte do processo de implantação. Para mais informações sobre estas entradas do Registro, veja Entradas do Registro para Suplementos VSTO.

Os suplementos do Outlook que exibem regiões de formulário personalizado exigem entradas adicionais do Registro que permitem que as regiões do 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 no nível do documento não exigem 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, consulte Visão geral das propriedades do documento personalizado.

Confiando na solução VSTO

Para que uma personalização seja executada, uma solução deve ser confiável pelo computador. O complemento pode ser confiável assinando o manifesto com um certificado, criando uma relação de confiança por meio de uma lista de inclusão, ou instalando em um local confiável no computador.

Para obter mais informações sobre como obter um certificado para assinatura, consulte ClickOnce Deployment and Authenticode. Para obter mais informações sobre soluções confiáveis, consulte Soluções confiáveis 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 de nível de documento, consulte Como conceder confiança a documentos.

Criando um instalador básico

Os modelos de projeto de Instalação e Implantação estão incluídos na extensão Projetos do Instalador do Microsoft Visual Studio que está disponível para download.

Para criar um instalador para uma solução do Office, essas 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 eles 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.

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

Para criar o projeto de Instalação do AddIn

1. Abra o Projeto AddIn do Office que você deseja implantar. Para este exemplo, estamos usando um Suplemento do Excel chamado ExcelAddIn.

2. Com o Office Project Open, no menu Arquivo , expanda Adicionar e clique em Novo Projeto para adicionar um novo projeto.

3. Na caixa Nome , digite OfficeAddInSetup.

O Visual Studio abre o Explorador do Sistema de Arquivos para o novo projeto de instalação. O Explorador do Sistema de Arquivos permite que você adicione arquivos ao projeto de instalação.

Figura 1: Explorador do Sistema de Arquivos para o projeto de instalação

O projeto de instalação precisa implantar o ExcelAddIn. Você pode configurar o projeto de instalação para essa tarefa adicionando a saída do projeto ExcelAddIn ao projeto de instalação.

Para adicionar a saída do projeto ExcelAddIn

1. No Gerenciador de Soluções, clique com o botão direito do mouse em OfficeAddInSetup, clique em Adicionar e, em seguida , na Saída do Projeto.

2. Na caixa de diálogo Adicionar Grupo de Saída do Projeto , selecione o ExcelAddIn na lista de projetos e a Saída Primária.

3. 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 Configuraçã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 aplicação

1. No Gerenciador de Soluções, clique com o botão direito do mouse em OfficeAddInSetup, clique em Adicionar e clique em Arquivo.

2. Na caixa de diálogo Adicionar Arquivos , navegue até o diretório de saída do ExcelAddIn . Normalmente, o diretório de saída é a subpasta bin\release do diretório raiz do projeto, dependendo da configuração de build selecionada.

3. Selecione o ExcelAddIn.vsto e o 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 do Complemento no Gerenciador de Soluções

Fazer referência ao ExcelAddIn inclui todos os componentes necessários para o ExcelAddIn. Esses componentes devem ser excluídos e implantados usando pacotes de pré-requisito 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 de projeto do ExcelAddIn

1. No Gerenciador de Soluções, no nó OfficeAddInSetup , selecione todos os itens de dependência abaixo do item Dependências Detectadas , exceto o Microsoft .NET Framework ou qualquer assembly que termine com *.Utilities.dll. Os assemblies utilitários devem ser implantados junto com seu aplicativo.

2. Clique com o botão direito do mouse no grupo e selecione Propriedades.

3. Na janela Propriedades, altere a propriedade Excluir para Verdadeiro, a fim de excluir os assemblies dependentes do projeto de instalação. Certifique-se de não excluir nenhum conjunto de utilidades.

   

   Figura 4: Excluindo dependências

Você pode configurar seu pacote do Windows Installer para instalar componentes de pré-requisito adicionando um programa de instalação, também conhecido como bootstrapper. Esse programa de instalação pode instalar os componentes de pré-requisito, um processo chamado inicialização.

Para o ExcelAddIn, esses pré-requisitos devem ser instalados antes que o Suplemento possa ser executado corretamente:

• A versão do Microsoft .NET Framework direcionada à Solução do Office.
• Microsoft Visual Studio 2010 Tools for Office Runtime.

Para configurar componentes dependentes como pré-requisitos

1. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto OfficeAddInSetup e selecione Propriedades.

2. A caixa de diálogo Páginas de Propriedades do OfficeAddInSetup é exibida.

3. Clique no botão Pré-requisitos .

4. Na caixa de diálogo Pré-requisitos, selecione a versão correta do .NET Framework e as Ferramentas do Microsoft Visual Studio para Office Runtime.

   

   Figura 5: Caixa de diálogo Pré-requisitos

   Observação

   Alguns dos pacotes de pré-requisito configurados no projeto de instalação do Visual Studio dependem da configuração de build selecionada. Você deve selecionar os componentes de pré-requisito corretos para cada configuração de build que você usa.

O Microsoft Office localiza complementos usando chaves do Registro. As chaves no hive HKEY_CURRENT_USER são usadas para registrar o suplemento para cada usuário individual. As chaves no HKEY_LOCAL_MACHINE hive são usadas para registrar o suplemento para todos os usuários do computador. Para obter mais informações sobre chaves do Registro, consulte as entradas do Registro para suplementos VSTO.

Para configurar o registro

1. No Gerenciador de Soluções, clique com o botão direito do mouse em OfficeAddInSetup.

2. Expandir Exibição.

3. Clique no Registro para abrir a janela do editor do Registro.

4. No editor do Registro (OfficeAddInSetup), expanda HKEY_LOCAL_MACHINE e, em seguida, Software.

5. Exclua a chave [Fabricante] encontrada emHKEY_LOCAL_MACHINE\Software.

6. Expanda HKEY_CURRENT_USER e, em seguida, Software.

7. Exclua a chave [Fabricante] encontrada emHKEY_CURRENT_USER\Software.

8. Para adicionar chaves do Registro para a instalação do suplemento, clique com o botão direito na chave User/Machine Hive 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.

9. Use um processo semelhante para criar toda a hierarquia de chaves necessária para o registro do suplemento:

   User/Machine Hive\Software\Microsoft\Office\Excel\Addins\SampleCompany.ExcelAddIn

   O Nome da Empresa geralmente é usado como um prefixo para o nome do suplemento para fornecer exclusividade.

10. Clique com o botão direito do mouse na chave SampleCompany.ExcelAddIn , selecione Novo e clique no valor da cadeia de caracteres. Use o texto Description para o Nome.

11. Use esta etapa para adicionar mais três valores:

    • FriendlyName do tipo String
    • LoadBehavior do tipo DWORD
    • Manifesto do tipo Cadeia de caracteres

12. 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 o Suplemento de Demonstração do Excel para a propriedade Value.

13. Selecione a chave FriendlyName no editor do Registro. Na janela Propriedades, altere a propriedade Value para Excel Demo AddIn.

14. Selecione a chave LoadBehavior no editor do Registro. Na janela Propriedades, altere a propriedade Value para 3. O valor 3 do LoadBehavior indica que o suplemento deve ser carregado na inicialização do aplicativo host. Para obter mais informações sobre o comportamento de carga, consulte as entradas do Registro para suplementos VSTO.

15. Selecione a chave manifesto no editor do Registro. Na janela Propriedades, altere a propriedade Value para file:///[TARGETDIR]ExcelAddIn.vsto|vstolocal

    

    Figura 6: Configurando 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 tempo de execução do VSTO que o Add-in deve carregar desse local em vez do cache ClickOnce. Remover esse postfix fará com que o runtime copie a personalização para o cache ClickOnce.

As versões de 64 bits do Office usarão a ramificação do Registro de 64 bits para procurar Add-ins. Para registrar Add-ins na ramificação do Registro de 64 bits, a plataforma de destino do projeto de instalação deve ser configurada como exclusivamente de 64 bits.

1. Selecione o projeto OfficeAddInSetup no gerenciador de soluções.
2. Vá para a janela Propriedades e defina a propriedade TargetPlatform comox64.

A instalação de um suplemento para 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 complementos com o Office 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 as condições de inicialização no MSI para impedir que o Suplemento seja instalado se os pré-requisitos não estiverem instalados.

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

1. No Gerenciador de Soluções, clique com o botão direito do mouse em OfficeAddInSetup.

2. Expandir Exibição.

3. Clique em Condições de Inicialização.

4. 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 pesquisar no Registro uma chave que o runtime do VSTO instala. Em seguida, o valor da chave está disponível para as diferentes partes do instalador por meio de uma propriedade nomeada. A condição de inicialização usa a propriedade definida pela condição de pesquisa para verificar um determinado valor.

5. No editor Condições de Inicialização (OfficeAddInSetup), selecione a condição Pesquisar por RegistroEntry1, clique com o botão direito do mouse na condição e selecione Janela de Propriedades.

6. Na janela Propriedades , defina estas propriedades:

   1. Defina o valor de (Nome) para pesquisar o RUNtime do VSTO 2010.
   2. Altere o valor da Propriedade para VSTORUNTIMEREDIST.
   3. Definir o valor de RegKey como SOFTWARE\Microsoft\VSTO Runtime Setup\v4R
   4. Deixe a propriedade Root definida como vsdrrHKLM.
   5. Altere a propriedade Value para Version.

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

8. Na janela Propriedades, defina estas propriedades:

   1. Defina o (Nome) para verificar a disponibilidade do VSTO 2010 Runtime.

   2. Altere o valor da Condição para VSTORUNTIMEREDIST>="10.0.30319"

   3. Deixe a propriedade InstallURL em branco.

   4. Defina a mensagem como As Ferramentas do Visual Studio 2010 para Office Runtime não estão instaladas. Execute Setup.exe para instalar o Suplemento.

      

      Figura 8: Janela de Propriedades para a condição de verificação de disponibilidade do runtime

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

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

1. No editor Condições de Inicialização (OfficeAddInSetup ), clique com o botão direito do mouse em Pesquisar Máquina de Destino e clique em Adicionar Pesquisa do Registro.

2. Selecione a condição de pesquisa RegistryEntry1, clique com o botão direito do mouse na condição e selecione Janela de Propriedades.

3. Na janela Propriedades , defina estas propriedades:

   1. Defina o valor de (Nome) para Search for Office VSTO Runtime.
   2. Altere o valor da propriedade para OfficeRuntime.
   3. Defina o valor de RegKey como SOFTWARE\Microsoft\VSTO Runtime Setup\v4.
   4. Deixe a propriedade Root definida como vsdrrHKLM.
   5. Altere a propriedade Value para Version.

4. No editor Launch Conditions (Condições de Inicialização - OfficeAddInSetup), selecione a condição Verificar disponibilidade do VSTO 2010 Runtime definida anteriormente, clique com o botão direito do mouse na condição e selecione Janela de Propriedades.

5. Altere o valor da propriedade Condition para VSTORUNTIMEREDIST >="10.0.30319" OR OFFICERUNTIME>="10.0.21022". Os números de versão talvez sejam diferentes, dependendo das versões do runtime necessárias para o complemento.

   

   Figura 9: Propriedades do Windows para verificar a disponibilidade do runtime por meio da condição de inicialização do Redist ou do Office

Se um suplemento for direcionado ao .NET Framework 4 ou mais recente, os Tipos dentro dos Assemblies de Interoperabilidade Primário (PIA), referenciados, poderão ser inseridos no assembly VSTO.

Para verificar se os Tipos de Interoperabilidade serão incorporados em seu Complemento, siga estas etapas:

1. Expandir o nó de referências no Gerenciador de Soluções
2. Selecione uma das referências PIA, por exemplo, Office.
3. Exiba as janelas de propriedades pressionando F4 ou selecionando Propriedades no menu de contexto Assemblies.
4. Verifique o valor da propriedade Incorporar Tipos de Interoperabilidade.

Se o valor for definido como True, os Tipos estarão sendo inseridos e você poderá pular para a seção Para compilar 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

1. 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. Esta condição de inicialização procura por um PIA do Office ao pesquisar a ID específica do componente.

2. Clique com o botão direito do mouse em Pesquisar componente1 e clique em Janela Propriedades para mostrar as propriedades da condição de inicialização.

3. Na Janela Propriedades, defina estas propriedades:

   1. Alterar o valor da propriedade (Name) para Pesquisar PIA Compartilhado do Office
   2. Altere o valor da ComponentID para a ID do componente do Office que você está usando. Você pode encontrar a lista de IDs de componente na tabela abaixo, por exemplo {64E2917E-AA13-4CA4-BFFE-EA6EDA3AFCB4}.
   3. Altere o valor da propriedade Property para HASSHAREDPIA.

4. No editor Condições de Inicialização (OfficeAddInSetup ), clique com o botão direito do mouse em Condição1 e clique em Janela Propriedades para mostrar as propriedades da condição de inicialização.

5. Altere estas propriedades da Condição1:

   1. Altere o (Nome) para Verificar a disponibilidade do Office Shared PIA.
   2. Altere a condição para HASSHAREDPIA.
   3. Deixe InstallUrl em branco.
   4. Altere a Mensagem para Componente obrigatório para interação com o Excel não está disponível. Por favor, execute o setup.exe.

   

   Figura 10: Janela Propriedades para verificar a condição de inicialização pia compartilhada do Office

IDs de Componente dos Assemblies de Interoperabilidade Primária para o Microsoft Office

Figura 11: Condições finais de inicialização

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 compilar o projeto de configuração

1. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto OfficeAddInSetup e clique em Compilar.
2. Usando o Windows Explorer, navegue até o diretório de saída do projeto OfficeAddInSetup e vá para a pasta Versão ou Depuração, dependendo da configuração de build selecionada. Copie todos os arquivos da pasta para um local que os usuários possam acessar.

Para testar a configuração do ExcelAddIn

1. Navegue até o local onde você copiou OfficeAddInSetup.
2. Clique duas vezes no arquivo setup.exe para instalar o suplemento OfficeAddInSetup . Aceite os Termos de Licença de 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 instalar e executar a partir do local especificado durante a instalação.

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

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

Aqui está uma lista das etapas básicas necessárias para implantar uma solução no nível do documento:

• Crie o Projeto de Instalação do Visual Studio.
• Adicione a saída primária da solução no nível do documento. A saída primária também inclui o documento do Microsoft Office.
• Adicione os manifestos de implantação e de aplicativo como arquivos soltos.
• Exclua os componentes dependentes do pacote do instalador (exceto para assemblies de utilitários).
• Configurar pacotes de pré-requisitos.
• Configure as condições de inicialização.
• Crie o projeto de instalação e copie os resultados para o local da implantação.
• Implante a solução no nível do 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 de 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 pastas diferentes, essas propriedades precisarão ser atualizadas durante a instalação.

Para obter mais informações sobre essas propriedades de documento, consulte Visão geral das propriedades do documento personalizado.

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 personalizado à sua solução do Visual Studio

1. Adicione um novo projeto do Console do .NET à solução clicando com o botão direito do mouse no Projeto de Implantação de Documentos do Office no Gerenciador de Soluções

2. Expanda Adicionar e clique em Novo Projeto.

3. Selecione o modelo de Aplicativo de Console e nomeie o projeto AddCustomizationCustomAction.

   

   Figura 12: Gerenciador de Soluções – AddCustomizationCustomAction

4. Adicione uma referência a estes assemblies:

   1. System.ComponentModel
   2. System.Configuration.Install
   3. Microsoft.VisualStudio.Tools.Applications
   4. Microsoft.VisualStudio.Tools.Applications.ServerDocument

5. Copie esse código para 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, você precisa 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

1. No menu Compilar , clique em Criar Solução para criar a solução no nível do documento e adicionar a propriedade ID da solução ao arquivo de projeto.

2. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto no nível do documento ExcelWorkbookProject

3. Clique em UnloadProject para acessar o arquivo de projeto de dentro do Visual Studio.

   

   Figura 13: Solução de descarregamento de documentos do Excel

4. No Gerenciador de Soluções, clique com o botão direito do mouse em ExcelWorkbookProject e clique em EditExcelWorkbookProject.vbproj ou Editar ExcelWorkbookProject.csproj.

5. No editor do ExcelWorkbookProject , localize o elemento SolutionID dentro do elemento PropertyGroup .

6. Copie o valor GUID desse elemento.

   

   Figura 14: Recuperando a SolutionID

7. No Gerenciador de Soluções, clique com o botão direito do mouse em ExcelWorkbookProject e clique em Recarregar Projeto.

8. Clique em Sim na caixa de diálogo que aparece para fechar o editor excelWorkbookProject .

9. 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 Instalar e Desinstalar .

Para configurar o projeto de instalação

1. No Gerenciador de Soluções, clique com o botão direito do mouse em ExcelWorkbookSetup, expanda Adicionar e clique em Saída do Projeto.

2. Na caixa de diálogo Adicionar Grupo de Saída do Projeto, na lista Projeto, clique em AddCustomizationCustomAction.

3. Selecione Saída Primária e clique em OK para fechar a caixa de diálogo e adicione o assembly que contém a ação personalizada ao projeto de instalação.

   

   Figura 15: Ação Personalizada do Manifesto de Documento – Adicionar Grupo de Resultados do Projeto

4. No Gerenciador de Soluções, clique com o botão direito do mouse em ExcelWorkbookSetup.

5. Expanda Exibição e clique em Ações Personalizadas.

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

7. Na caixa de diálogo Selecionar Item no Projeto, na lista Pesquisar em, clique em Pasta de Aplicativo. Selecione Saída Primária de AddCustomizationCustomAction(ativo) e clique em OK para adicionar a ação personalizada à etapa Instalar.

8. No nó de instalação, clique com o botão direito na saída primária de AddCustomizationCustomAction(Active) e clique em Renomear. Nomeie a ação personalizada Copiar documento para Meus Documentos e anexar personalização.

9. No nó Desinstalar, clique com o botão direito do mouse na 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

10. No editor Ações Personalizadas (ExcelWorkbookSetup), clique com o botão direito do mouse em Copiar documento para Meus Documentos e anexar a personalização e clique em Janela de Propriedades.

11. Na janela PropriedadesCustomActionData, insira o local da DLL de personalização, o manifesto de implantação e o local do documento do Microsoft Office. A SolutionID também é necessária.

12. Se você quiser registrar 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

13. A Ação Personalizada para Desinstalação precisa do nome do documento, você pode fornecer isso usando o mesmo parâmetro documentLocation no CustomActionData

    /documentLocation="[INSTALLDIR]ExcelWorkbookProject.xlsx"
    

14. Compile e implante o projeto ExcelWorkbookSetup .

15. Procure na pasta Meus Documentos e abra o arquivo ExcelWorkbookProject.xlsx.

Recursos adicionais

Como instalar as Ferramentas do Visual Studio para Office Runtime

Assemblies de interoperabilidade primária do Office

Entradas do Registro para VSTO Add-ins

Visão geral das propriedades do documento personalizado

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 do Office Open XML e um consultor independente com foco na criação de OBAs (Aplicativos Comerciais do Office) com o SharePoint, o Microsoft Office e tecnologias relacionadas do .NET. O Wouter é um colaborador frequente para sites da comunidade de desenvolvedores, como o MSDN. Ele publicou vários white papers e artigos, bem como um livro disponível online intitulado Open XML: Explained. 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 saber 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 Evangelism da Plataforma de Desenvolvedores da Microsoft para criar o currículo de treinamento do desenvolvedor Ascend para o Windows SharePoint Services 3.0 e o Microsoft Office SharePoint Server 2007. Desde então, Ted tem se concentrado inteiramente em educar desenvolvedores profissionais sobre 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.