Demonstra Passo a passo: Vincular controles de conteúdo a partes XML personalizadas

Esta explicação passo a passo demonstra como vincular controles de conteúdo em uma personalização em nível de documento para o Word para dados XML armazenados no documento.

Aplica-se a: As informações neste tópico se aplicam a projetos de nível de documento para o Word. Para obter mais informações, consulte Recursos disponíveis por aplicativo e tipo de projeto do Office.

O Word permite que você armazene dados XML, denominados partes XML personalizadas, em um documento. Você pode controlar a exibição desses dados vinculando controles de conteúdo a elementos em uma parte XML personalizada. O documento de exemplo neste passo a passo exibe informações do funcionário que são armazenadas em uma parte XML personalizada. Quando você abre o documento, os controles de conteúdo exibem os valores dos elementos XML. Todas as alterações feitas no texto nos controles de conteúdo são salvas na parte XML personalizada.

Este passo a passo ilustra as seguintes tarefas:

• Adicionando controles de conteúdo ao documento do Word em um projeto de nível de documento em tempo de design.

• Criando um arquivo de dados XML e um esquema XML que define os elementos a serem vinculados aos controles de conteúdo.

• Anexar o esquema XML ao documento em tempo de design.

• Adicionando o conteúdo do arquivo XML a uma parte XML personalizada no documento em tempo de execução.

• Vinculação dos controles de conteúdo a elementos na parte XML personalizada.

• Vinculação a DropDownListContentControl a um conjunto de valores definidos no esquema XML.

  Observação

  Seu computador pode mostrar diferentes nomes ou locais para alguns dos elementos de interface do usuário do Visual Studio nas instruções a seguir. A edição do Visual Studio que você possui e as configurações que você usa determinam esses elementos. Para obter mais informações, confira Personalizar o IDE.

Pré-requisitos

Você precisará dos seguintes componentes para concluir este passo a passo:

• Uma edição do Visual Studio que inclui o Microsoft Office Developer Tools. Para obter mais informações, consulte Configurar um computador para desenvolver soluções do Office.

• Microsoft Word.

Criar um novo projeto de documento do Word

Crie um documento do Word que você usará na explicação passo a passo.

Para criar um novo projeto de documento do Word

1. Crie um projeto de documento do Word com o nome EmployeeControls. Crie um novo documento para a solução. Para obter mais informações, consulte Como: Criar projetos do Office no Visual Studio.

   O Visual Studio abre o novo documento do Word no designer e adiciona o projeto EmployeeControls ao Gerenciador de Soluções.

Adicionar controles de conteúdo ao documento

Crie uma tabela que contenha três tipos diferentes de controles de conteúdo onde o usuário pode exibir ou editar informações sobre um funcionário.

Para adicionar controles de conteúdo ao documento

1. No documento do Word hospedado no designer do Visual Studio, na Faixa de Opções, escolha a guia Inserir .

2. No grupo Tabelas, escolha Tabela e insira uma tabela com 2 colunas e 3 linhas.

3. Digite o texto na primeira coluna para que ele se assemelhe à seguinte coluna:

   Nome do Funcionário
   Data de Contratação
   Título

4. Na segunda coluna da tabela, escolha a primeira linha (ao lado de Nome do funcionário).

5. Na Faixa de Opções, escolha a guia Desenvolvedor .

   Observação

   Se a guia Desenvolvedor não estiver visível, você deverá mostrá-la primeiro. Para obter mais informações, consulte Como mostrar a guia do desenvolvedor na faixa de opções.

6. No grupo Controles, escolha o botãoTexto para adicionar um PlainTextContentControl à primeira célula.

7. Na segunda coluna da tabela, escolha a segunda linha (ao lado de Data de contratação).

8. No grupo Controles, escolha o botão Seletor de Data para adicionar um DatePickerContentControl à segunda célula.

9. Na segunda coluna da tabela, escolha a terceira linha (ao lado de Título).

10. No grupo Controles, escolha o botão Lista suspensa para adicionar um DropDownListContentControl à última célula.

    Essa é toda a interface do usuário para este projeto. Se você executar o projeto agora, poderá digitar texto na primeira linha e selecionar uma data na segunda linha. A próxima etapa é anexar os dados que você deseja exibir ao documento em um arquivo XML.

Criar o arquivo de dados XML

Normalmente, você obterá dados XML para armazenar em uma parte XML personalizada de uma fonte externa, como um arquivo ou um banco de dados. Nesta explicação passo a passo, você cria um arquivo XML que contém os dados do funcionário, marcados por elementos que serão vinculados aos controles de conteúdo no documento. Para disponibilizar os dados em tempo de execução, incorpore o arquivo XML como um recurso no assembly de personalização.

Para criar o arquivo de dados

1. No menu Projeto, escolha Adicionar Novo Item.

   A caixa de diálogo Adicionar Novo Item aparecerá.

2. No painel Modelos, selecione Arquivo XML.

3. Nomeie os funcionários do arquivo .xml e escolha o botão Adicionar .

   O arquivo .xml funcionários é aberto no Editor de Códigos.

4. Substitua o conteúdo do arquivo .xml funcionários pelo texto a seguir.

   <?xml version="1.0" encoding="utf-8" ?>
   <employees xmlns="http://schemas.microsoft.com/vsto/samples">
     <employee>
       <name>Karina Leal</name>
       <hireDate>1999-04-01</hireDate>
       <title>Manager</title>
     </employee>
   </employees>
   

5. No Gerenciador de Soluções, escolha o arquivo .xml funcionários.

6. Na janela Propriedades, selecione a propriedade Ação de Criação e altere o valor para Recurso Incorporado.

   Esta etapa incorpora o arquivo XML como um recurso no assembly quando você cria o projeto. Isso permite que você acesse o conteúdo do arquivo XML em tempo de execução.

Criar um Esquema XML

Se você deseja vincular um controle de conteúdo a um único elemento em uma parte XML personalizada, não é necessário usar um esquema XML. No entanto, para vincular o a um conjunto de valores, você deve criar um esquema XML que valida o DropDownListContentControl arquivo de dados XML que você criou anteriormente. O esquema XML define os valores possíveis para o title elemento. Você vinculará o a esse elemento mais adiante nesta explicação passo a DropDownListContentControl passo.

Para criar um esquema XML

1. No menu Projeto, escolha Adicionar Novo Item.

   A caixa de diálogo Adicionar Novo Item aparecerá.

2. No painel Modelos, selecione Esquema XML.

3. Nomeie o esquema employees.xsd e escolha o botão Adicionar .

   O designer de esquema é aberto.

4. No Gerenciador de Soluções, abra o menu de atalho para employees.xsd e escolha Exibir Código.

5. Substitua o conteúdo do arquivo employees.xsd pelo esquema a seguir.

   <?xml version="1.0" encoding="utf-8" ?>
   <xs:schema xmlns="http://schemas.microsoft.com/vsto/samples"
       targetNamespace="http://schemas.microsoft.com/vsto/samples"
       xmlns:xs="http://www.w3.org/2001/XMLSchema"
       elementFormDefault="qualified">
     <xs:element name="employees" type="EmployeesType"></xs:element>
     <xs:complexType name="EmployeesType">
       <xs:all>
         <xs:element name="employee" type="EmployeeType"/>
       </xs:all>
     </xs:complexType>
     <xs:complexType name="EmployeeType">
       <xs:sequence>
         <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1"/>
         <xs:element name="hireDate" type="xs:date" minOccurs="1" maxOccurs="1"/>
         <xs:element name="title" type="TitleType" minOccurs="1" maxOccurs="1"/>
       </xs:sequence>
     </xs:complexType>
     <xs:simpleType name="TitleType">
       <xs:restriction base="xs:string">
         <xs:enumeration value ="Engineer"/>
         <xs:enumeration value ="Designer"/>
         <xs:enumeration value ="Manager"/>
       </xs:restriction>
     </xs:simpleType>
   </xs:schema>
   

6. No menu Arquivo, clique em Salvar Tudo para salvar suas alterações nos arquivos employees.xml e employees.xsd.

Anexar o esquema XML ao documento

Você deve anexar o esquema XML ao documento para vincular o DropDownListContentControl aos valores válidos do title elemento.

Para anexar o esquema XML ao documento ( Word 2013 )

1. Ative EmployeeControls.docx no designer.

2. Na Faixa de Opções, escolha a guia Desenvolvedor e escolha o botão Suplementos .

3. Na caixa de diálogo Modelos e Suplementos, escolha a guia Esquema XML e escolha o botão Adicionar Esquema.

4. Navegue até o esquema employees.xsd criado anteriormente, localizado no diretório do projeto, e escolha o botão Abrir.

5. Escolha o botão OK na caixa de diálogo Configurações do esquema.

6. Escolha o botão OK para fechar a caixa de diálogo Modelos e Suplementos .

Para anexar o esquema XML ao documento (Word 2010)

1. Ative EmployeeControls.docx no designer.

2. Na Faixa de Opções, escolha a guia Desenvolvedor .

3. No grupo XML, escolha o botão Esquema.

4. Na caixa de diálogo Modelos e Suplementos, escolha a guia Esquema XML e escolha o botão Adicionar Esquema.

5. Navegue até o esquema employees.xsd que você criou anteriormente, que está localizado no diretório do projeto, e escolha o botão Abrir.

6. Escolha o botão OK na caixa de diálogo Configurações do esquema.

7. Escolha o botão OK para fechar a caixa de diálogo Modelos e Suplementos .

   O painel de tarefas Estrutura XML é aberto.

8. Feche o painel de tarefas Estrutura XML .

Adicionar uma parte XML personalizada ao documento

Antes de vincular os controles de conteúdo aos elementos no arquivo XML, você deve adicionar o conteúdo do arquivo XML a uma nova parte XML personalizada no documento.

Para adicionar uma parte XML personalizada ao documento

1. No Gerenciador de Soluções, abra o menu de atalho para ThisDocument.cs ou ThisDocument.vb e escolha Exibir código.

2. Adicione as seguintes declarações à ThisDocument classe. Esse código declara vários objetos que você usará para adicionar uma parte XML personalizada ao documento.

   C#

   [CachedAttribute()]
   public string employeeXMLPartID = string.Empty;
   private Office.CustomXMLPart employeeXMLPart;
   private const string prefix = "xmlns:ns='http://schemas.microsoft.com/vsto/samples'";
   

   VB

   <Cached()> _
   Public employeeXMLPartID As String = String.Empty
   Private employeeXMLPart As Office.CustomXMLPart
   Private Const prefix As String = "xmlns:ns='http://schemas.microsoft.com/vsto/samples'"
   

3. Adicione o método a seguir à classe ThisDocument. Esse método obtém o conteúdo do arquivo de dados XML que é incorporado como um recurso no assembly e retorna o conteúdo como uma cadeia de caracteres XML.

   C#

   private string GetXmlFromResource()
   {
       System.Reflection.Assembly asm =
           System.Reflection.Assembly.GetExecutingAssembly();
       System.IO.Stream stream1 = asm.GetManifestResourceStream(
           "EmployeeControls.employees.xml");
   
       using (System.IO.StreamReader resourceReader =
               new System.IO.StreamReader(stream1))
       {
           if (resourceReader != null)
           {
               return resourceReader.ReadToEnd();
           }
       }
   
       return null;
   }
   

   VB

   Private Function GetXmlFromResource() As String
       Dim asm As System.Reflection.Assembly = _
           System.Reflection.Assembly.GetExecutingAssembly()
       Dim stream1 As System.IO.Stream = asm.GetManifestResourceStream( _
               "EmployeeControls.employees.xml")
   
       Using resourceReader As System.IO.StreamReader = _
           New System.IO.StreamReader(stream1)
           If resourceReader IsNot Nothing Then
               Return resourceReader.ReadToEnd()
           End If
       End Using
   
       Return Nothing
   End Function
   

4. Adicione o método a seguir à classe ThisDocument. O AddCustomXmlPart método cria uma nova parte XML personalizada que contém uma cadeia de caracteres XML que é passada para o método.

   Para garantir que a parte XML personalizada seja criada apenas uma vez, o método cria a parte XML personalizada somente se uma parte XML personalizada com um GUID correspondente ainda não existir no documento. Na primeira vez que esse método é chamado, ele salva o valor da propriedade na employeeXMLPartID cadeia de Id caracteres. O valor da cadeia de employeeXMLPartID caracteres é persistido no documento porque foi declarado usando o CachedAttribute atributo.

   C#

   private void AddCustomXmlPart(string xmlData)
   {
       if (xmlData != null)
       {
           employeeXMLPart = this.CustomXMLParts.SelectByID(employeeXMLPartID);
           if (employeeXMLPart == null)
           {
               employeeXMLPart = this.CustomXMLParts.Add(xmlData);
               employeeXMLPart.NamespaceManager.AddNamespace("ns", 
                   @"http://schemas.microsoft.com/vsto/samples");
               employeeXMLPartID = employeeXMLPart.Id;
           }
       }
   }
   

   VB

   Private Sub AddCustomXmlPart(ByVal xmlData As String)
       If xmlData IsNot Nothing Then
   
           employeeXMLPart = Me.CustomXMLParts.SelectByID(employeeXMLPartID)
           If (employeeXMLPart Is Nothing) Then
               employeeXMLPart = Me.CustomXMLParts.Add(xmlData)
               employeeXMLPart.NamespaceManager.AddNamespace("ns", _
                   "http://schemas.microsoft.com/vsto/samples")
               employeeXMLPartID = employeeXMLPart.Id
           End If
       End If
   End Sub
   

Vincular os controles de conteúdo a elementos na parte XML personalizada

Vincule cada controle de conteúdo a um elemento na parte XML personalizada usando a propriedade XMLMapping de cada controle de conteúdo.

Para vincular os controles de conteúdo a elementos na parte XML personalizada

1. Adicione o método a seguir à classe ThisDocument. Esse método vincula cada controle de conteúdo a um elemento na parte XML personalizada e define o formato de exibição de data do DatePickerContentControl.

   C#

   private void BindControlsToCustomXmlPart()
   {
       string xPathName = "ns:employees/ns:employee/ns:name";
       this.plainTextContentControl1.XMLMapping.SetMapping(xPathName,
           prefix, employeeXMLPart);
   
       string xPathDate = "ns:employees/ns:employee/ns:hireDate";
       this.datePickerContentControl1.DateDisplayFormat = "MMMM d, yyyy";
       this.datePickerContentControl1.XMLMapping.SetMapping(xPathDate,
           prefix, employeeXMLPart);
   
       string xPathTitle = "ns:employees/ns:employee/ns:title";
       this.dropDownListContentControl1.XMLMapping.SetMapping(xPathTitle,
           prefix, employeeXMLPart);
   }
   

   VB

   Private Sub BindControlsToCustomXmlPart()
       Dim xPathName As String = "ns:employees/ns:employee/ns:name"
       Me.PlainTextContentControl1.XMLMapping.SetMapping(xPathName, _
           prefix, employeeXMLPart)
   
       Dim xPathDate As String = "ns:employees/ns:employee/ns:hireDate"
       Me.DatePickerContentControl1.DateDisplayFormat = "MMMM d, yyyy"
       Me.DatePickerContentControl1.XMLMapping.SetMapping(xPathDate, _
           prefix, employeeXMLPart)
   
       Dim xPathTitle As String = "ns:employees/ns:employee/ns:title"
       Me.DropDownListContentControl1.XMLMapping.SetMapping(xPathTitle, _
           prefix, employeeXMLPart)
   End Sub
   

Execute o código quando o documento for aberto

Crie a parte XML personalizada e vincule os controles personalizados aos dados quando o documento for aberto.

Para executar o código quando o documento é aberto

1. Adicione o seguinte código ao ThisDocument_Startup método da ThisDocument classe. Esse código obtém a cadeia de caracteres XML do arquivo .xml funcionários, adiciona a cadeia de caracteres XML a uma nova parte XML personalizada no documento e vincula os controles de conteúdo a elementos na parte XML personalizada.

   C#

   string xmlData = GetXmlFromResource();
   
   if (xmlData != null)
   {
       AddCustomXmlPart(xmlData);
       BindControlsToCustomXmlPart();
   }
   

   VB

   Dim xmlData As String = GetXmlFromResource()
   If xmlData IsNot Nothing Then
       AddCustomXmlPart(xmlData)
       BindControlsToCustomXmlPart()
   End If
   

Testar o projeto

Quando você abre o documento, os controles de conteúdo exibem dados dos elementos na parte XML personalizada. Você pode clicar no DropDownListContentControl para selecionar um dos três valores válidos para o title elemento, que são definidos no arquivo employees.xsd . Se você editar os dados em qualquer um dos controles de conteúdo, os novos valores serão salvos na parte XML personalizada no documento.

Para testar os controles de conteúdo

1. Pressione F5 para executar o projeto.

2. Verifique se a tabela no documento é semelhante à tabela a seguir. Cada uma das cadeias de caracteres na segunda coluna é obtida de um elemento na parte XML personalizada no documento.

   Coluna	Valor
   Nome do Funcionário	Karina Leal
   Data de Contratação	1 de abril de 1999
   Título	Gerente

3. Escolha a célula à direita da célula Nome do Funcionário e digite um nome diferente.

4. Escolha a célula à direita da célula Data de contratação e selecione uma data diferente no seletor de datas.

5. Escolha a célula à direita da célula Título e selecione um novo item na lista suspensa.

6. Salve e feche o documento.

7. No Explorador de Arquivos, abra a pasta \bin\Debug no local do projeto.

8. Abra o menu de atalho para EmployeeControls.docx e escolha Renomear.

9. Nomeie o arquivo EmployeeControls.docx.zip.

   O documento EmployeeControls.docx é salvo no formato Open XML. Ao renomear este documento com a extensão de nome de arquivo .zip , você pode examinar o conteúdo do documento. Para obter mais informações sobre o Open XML, consulte o artigo técnico Apresentando os formatos de arquivo Open XML do Office (2007).

10. Abra o arquivo EmployeeControls.docx.zip .

11. Abra a pasta customXml .

12. Abra o menu de atalho do item2.xml e escolha Abrir.

    Esse arquivo contém a parte XML personalizada que você adicionou ao documento.

13. Verifique se os elementos , hireDatee title contêm os namenovos valores inseridos nos controles de conteúdo no documento.

14. Feche o arquivo item2.xml .

Próximas etapas

Você pode saber mais sobre como usar controles de conteúdo nestes tópicos:

• Use todos os controles de conteúdo disponíveis para criar um modelo. Para obter mais informações, consulte Demonstra Passo a passo: Criar um modelo usando controles de conteúdo.

• Modifique os dados nas partes XML personalizadas enquanto o documento está fechado. Na próxima vez que o usuário abrir o documento, os controles de conteúdo vinculados aos elementos XML exibirão os novos dados.

• Use controles de conteúdo para proteger partes de um documento. Para obter mais informações, consulte Como: Proteger partes de documentos usando controles de conteúdo.

Conteúdo relacionado

• Automatizar o Word usando objetos estendidos
• Controles de conteúdo
• Como: Adicionar controles de conteúdo a documentos do Word
• Como: Proteger partes de documentos usando controles de conteúdo
• Visão geral de itens de host e controles de host
• Limitações programáticas de itens de host e controles de host
• Adicionar controles a documentos do Office em tempo de execução