Compartilhar via

Arquitetura de personalizações em nível de documento

  • Artigo

O Visual Studio 2013 inclui projetos para criar personalizações em nível de documento para o Microsoft Office Word e o Microsoft Office Excel. Este tópico descreve os seguintes aspectos das personalizações em nível de documento:

Entender as personalizações

Quando você usa as ferramentas de desenvolvedor do Office no Visual Studio para criar uma personalização em nível de documento, você cria um assembly de código gerenciado que está associado a um documento específico. Diz-se que um documento ou pasta de trabalho com um assembly vinculado tem extensões de código gerenciadas. Para obter mais informações, consulte Projetar e criar soluções do Office.

Quando um usuário abre o documento, o assembly é carregado pelo aplicativo Microsoft Office. Depois que o assembly é carregado, a personalização pode responder a eventos enquanto o documento está aberto. A personalização também pode chamar o modelo de objeto para automatizar e estender o aplicativo enquanto o documento está aberto, e pode usar qualquer uma das classes no .NET Framework.

O assembly se comunica com os componentes COM do aplicativo por meio do assembly de interoperabilidade primário do aplicativo. Para obter mais informações, consulte Assemblies de interoperabilidade primária do Office e Visão geral de desenvolvimento de soluções do Office (VSTO).

Se um usuário abrir várias personalizações em nível de documento ao mesmo tempo, cada assembly será carregado em um domínio de aplicativo diferente. Isso significa que uma solução que se comporta incorretamente não pode fazer com que outras soluções falhem. As personalizações em nível de documento são projetadas para funcionar com um único documento em um único domínio de aplicativo. Eles não são projetados para comunicação entre documentos. Para obter mais informações sobre domínios de aplicativo, consulte Domínios de aplicativo.

Observação

As personalizações em nível de documento que você cria usando as ferramentas de desenvolvedor do Office no Visual Studio são projetadas para serem usadas somente quando o aplicativo é iniciado por um usuário final. Se o aplicativo for iniciado programaticamente, por exemplo, usando automação, a personalização pode não funcionar conforme o esperado.

Experiências de tempo de design e tempo de execução

Para entender a arquitetura das personalizações em nível de documento, ele ajuda a entender as experiências de design de uma solução e de execução de uma solução.

Momento do design

A experiência em tempo de design inclui as seguintes etapas:

  1. O desenvolvedor cria um projeto de nível de documento no Visual Studio. O projeto inclui o documento e o assembly que é executado atrás do documento. O documento pode já existir (criado por um designer) ou um novo documento pode ser criado junto com o projeto.

  2. O designer — seja o desenvolvedor que cria o projeto ou outra pessoa — cria a aparência final do documento para o usuário final.

Runtime

A experiência de tempo de execução inclui as seguintes etapas:

  1. O usuário final abre um documento ou pasta de trabalho que tenha extensões de código gerenciadas.

  2. O documento ou pasta de trabalho carrega o assembly compilado.

  3. O assembly responde a eventos à medida que o usuário trabalha no documento ou na pasta de trabalho.

Comparação entre a perspectiva do desenvolvedor e do usuário final

Como o desenvolvedor trabalha principalmente no Visual Studio e o usuário final trabalha no Word ou no Excel, há duas maneiras de entender as personalizações em nível de documento.

Perspectiva do desenvolvedor Perspectiva do usuário final
Usando o Visual Studio, o desenvolvedor escreve código que é acessível para o Word e Excel.

Embora possa parecer que o desenvolvedor está criando um arquivo executável que executa o Word ou Excel, o processo realmente funciona ao contrário. O documento está associado a um assembly e contém um ponteiro para esse assembly. Quando o documento é aberto, o Word ou Excel localiza o assembly e executa o código em resposta a todos os eventos manipulados.		 Aqueles que usam a solução simplesmente abrem o documento ou pasta de trabalho (ou criam um novo documento a partir de um modelo) assim como abririam qualquer outro arquivo do Microsoft Office.

O assembly fornece personalizações no documento ou pasta de trabalho, como preenchê-lo automaticamente com dados atuais ou mostrar uma caixa de diálogo para solicitar informações.

Formatos de documento suportados para personalizações em nível de documento

Ao criar um projeto de personalização, você pode escolher o formato do documento que deseja usar no projeto. Para obter mais informações, consulte Como: Criar projetos do Office no Visual Studio.

A tabela a seguir lista os formatos de documento que você pode usar em personalizações em nível de documento para Excel e Word.

Excel Word
Pasta de trabalho do Excel (.xlsx)

Pasta de trabalho habilitada para macro do Excel (.xlsm)

Pasta de trabalho binária do Excel (.xlsb)

Pasta de trabalho do Excel 97-2003 (.xls)

Modelo do Excel (.xltx)

Modelo habilitado para macro do Excel (.xltm)

Modelo do Excel 97-2003 (.xlt)		 Documento do Word (.docx)

Documento habilitado para macro do Word (.docm)

Documento do Word 97-2003 (.doc)

Modelo do Word (.dotx)

Modelo habilitado para macro do Word (.dotm)

Modelo do Word 97-2003 (.dot)

Você deve criar extensões de código gerenciado somente para documentos nos formatos suportados. Caso contrário, determinados eventos podem não ser gerados quando o documento é aberto no aplicativo. Por exemplo, o Open evento não é gerado quando você usa extensões de código gerenciado com pastas de trabalho salvas no formato de planilha XML do Excel ou na página da Web (.htm; . html).

Suporte para documentos do Word que têm extensões de nome de arquivo .xml

Os modelos de projeto em nível de documento não permitem que você crie projetos com base nos seguintes formatos de arquivo:

  • Documento XML do Word (*xml).

  • Documento XML do Word 2003 (*xml).

    Se você quiser que os usuários finais usem personalizações nesses formatos de arquivo, crie e implante uma personalização que use um dos formatos de arquivo com suporte especificados na tabela acima. Depois de instalar a personalização, os usuários finais podem salvar o documento no formato Documento XML do Word (*xml) ou no formato Documento XML do Word 2003 (*xml), e a personalização continuará a funcionar conforme o esperado.

Componentes de personalizações

Os principais componentes de uma personalização são o documento e o assembly. Além desses componentes, há várias outras partes que desempenham um papel importante em como os aplicativos do Microsoft Office descobrem e carregam personalizações.

Manifesto de implantação e manifesto do aplicativo

As personalizações usam manifestos de implantação e manifestos de aplicativo para identificar e carregar a versão mais atual do assembly de personalização. O manifesto de implantação aponta para o manifesto do aplicativo atual. O manifesto do aplicativo aponta para o assembly de personalização e especifica a classe de ponto de entrada (ou classes) a ser executada no assembly. Para obter mais informações, consulte Manifestos de aplicativo e implantação em soluções do Office.

Runtime do Visual Studio Tools para Office

Para executar personalizações em nível de documento que são criadas usando as ferramentas de desenvolvedor do Office no Visual Studio, os computadores do usuário final devem ter o Visual Studio Tools for Office runtime instalado. O tempo de execução do Visual Studio Tools for Office inclui componentes não gerenciados que carregam o assembly de personalização e também um conjunto de assemblies gerenciados. Esses assemblies gerenciados fornecem o modelo de objeto que seu código de personalização usa para automatizar e estender o aplicativo host.

Para obter mais informações, consulte Visão geral do Visual Studio tools for Office runtime.

Como as personalizações funcionam com aplicativos do Microsoft Office

Quando um usuário abre um documento que faz parte de uma personalização do Microsoft Office, o aplicativo usa o manifesto de implantação vinculado ao documento para localizar e carregar a versão mais atual do assembly de personalização. O local do manifesto de implantação é armazenado em uma propriedade de documento personalizada chamada AssemblyLocation. A cadeia de caracteres que identifica esse local é inserida na propriedade quando você cria a solução.

O manifesto de implantação aponta para o manifesto do aplicativo, que aponta para o assembly mais atual. Para obter mais informações, consulte Manifestos de aplicativo e implantação em soluções do Office.

A ilustração a seguir mostra a arquitetura básica de uma personalização em nível de documento.

2007 Office customization architecture

Observação

Em soluções do Office destinadas ao .NET Framework 4, as soluções chamam o modelo de objeto do aplicativo host usando informações de tipo de assembly de interoperabilidade primária (PIA) que são incorporadas no assembly de solução, em vez de chamar o PIA diretamente. Para obter mais informações, consulte Projetar e criar soluções do Office.

Processo de carregamento

As etapas a seguir ocorrem quando um usuário abre um documento que faz parte de uma solução do Microsoft Office.

  1. O aplicativo Microsoft Office verifica as propriedades personalizadas do documento para ver se há extensões de código gerenciado associadas ao documento. Para obter mais informações, consulte Visão geral das propriedades personalizadas do documento.

  2. Se houver extensões de código gerenciado, o aplicativo carregará VSTOEE.dll, que carrega VSTOLoader.dll. Essas são DLLs não gerenciadas que são os componentes do carregador para o tempo de execução do Visual Studio 2010 Tools for Office. Para obter mais informações, consulte Visão geral do tempo de execução do Visual Studio Tools for Office.

  3. VSTOLoader.dll carrega o .NET Framework e inicia a parte gerenciada do tempo de execução do Visual Studio Tools for Office.

  4. Se o documento for aberto de um local diferente do computador local, o Visual Studio Tools for Office runtime verificará se o local do documento está na lista Locais Confiáveis nas Configurações da Central de Confiabilidade para esse aplicativo específico do Office. Se o local do documento não estiver em um local confiável, a personalização não será confiável e o processo de carregamento será interrompido aqui.

  5. O Visual Studio Tools for Office runtime instala a solução se ela ainda não tiver sido instalada, baixa o aplicativo mais recente e manifestos de implantação e executa uma série de verificações de segurança. Para obter mais informações, consulte Soluções do Office Seguro.

  6. Se a personalização for confiável para execução, o tempo de execução do Visual Studio Tools for Office usará o manifesto de implantação e o manifesto do aplicativo para verificar se há atualizações de assembly. Se uma nova versão do assembly estiver disponível, o tempo de execução baixará a nova versão do assembly para o cache do ClickOnce no computador cliente. Para obter mais informações, consulte Implantar uma solução do Office.

  7. O tempo de execução do Visual Studio Tools for Office cria um novo domínio de aplicativo no qual carregar o assembly de personalização.

  8. O tempo de execução do Visual Studio Tools for Office carrega o assembly de personalização no domínio do aplicativo.

  9. O tempo de execução do Visual Studio Tools for Office chama o manipulador de eventos de inicialização em seu assembly de personalização. Para obter mais informações, consulte Eventos em projetos do Office.

Conteúdo relacionado