Procedura dettagliata: Associare controlli contenuto a parti XML personalizzate

Questa procedura dettagliata illustra come associare i controlli contenuto in una personalizzazione a livello di documento per Word a dati XML archiviati nel documento.

Si applica a: le informazioni contenute in questo argomento si applicano ai progetti a livello di documento per Word. Per altre informazioni, vedere Funzionalità disponibili per app Office lication e tipo di progetto.

Word consente di archiviare dati XML, denominati parti XML personalizzate, in un documento. È possibile controllare la visualizzazione di questi dati associando i controlli contenuto a elementi in una parte XML personalizzata. Il documento di esempio in questa procedura dettagliata visualizza informazioni sui dipendenti che vengono archiviate in una parte XML personalizzata. Quando si apre il documento, i controlli contenuto visualizzano i valori degli elementi XML. Nella parte XML personalizzata vengono salvate le eventuali modifiche apportate al testo nei controlli contenuto.

In questa procedura dettagliata sono illustrati i task seguenti:

• Aggiunta di controlli contenuto al documento di Word presente in un progetto a livello di documento in fase di progettazione.

• Creazione di un file di dati XML e di uno schema XML che definisce gli elementi da associare ai controlli contenuto.

• Associazione dello schema XML al documento in fase di progettazione.

• Aggiunta del contenuto del file XML a una parte XML personalizzata nel documento in fase di esecuzione.

• Binding dei controlli contenuto a elementi nella parte XML personalizzata.

• Associazione di DropDownListContentControl a un set di valori definiti nello schema XML.

  Nota

  I nomi o i percorsi visualizzati per alcuni elementi dell'interfaccia utente di Visual Studio nelle istruzioni seguenti potrebbero essere diversi nel computer in uso. La versione di Visual Studio in uso e le impostazioni configurate determinano questi elementi. Per altre informazioni, vedere Personalizzare l'IDE.

Prerequisiti

Per completare questa procedura dettagliata, è necessario disporre dei componenti seguenti:

• Una versione di Visual Studio che include Microsoft Office Developer Tools. Per altre informazioni, vedere Configurare un computer per sviluppare soluzioni Office.

• Microsoft Word.

Creare un nuovo progetto di documento di Word

Creare un documento di Word che verrà usato nella procedura dettagliata.

Per creare un progetto di documento di Word

1. Creare un progetto di documento di Word con il nome EmployeeControls. Creare un nuovo documento per la soluzione. Per altre informazioni, vedere Procedura: Creare progetti di Office in Visual Studio.

   Visual Studio apre il nuovo documento di Word nella finestra di progettazione e aggiunge il progetto EmployeeControls a Esplora soluzioni.

Aggiungere controlli contenuto al documento

Creare una tabella che contiene tre tipi diversi di controlli contenuto in cui un utente può visualizzare o modificare informazioni su un dipendente.

Per aggiungere controlli contenuto al documento

1. Nel documento di Word ospitato nella finestra di progettazione di Visual Studio scegliere la scheda Inserisci sulla barra multifunzione.

2. Nel gruppo Tabelle scegliere Tabella e inserire una tabella con 2 colonne e 3 righe.

3. Digitare il testo nella prima colonna in modo che sia simile alla colonna seguente:

   Nome dipendente
   Data di assunzione
   Title

4. Nella seconda colonna della tabella scegliere la prima riga accanto a Nome dipendente.

5. Sulla barra multifunzione scegliere la scheda Sviluppo .

   Nota

   Se la scheda Sviluppatore non viene mostrata, è necessario abilitarne la visualizzazione. Per altre informazioni, vedere Procedura: Visualizzare la scheda sviluppatore sulla barra multifunzione.

6. Nel gruppo Controlli scegliere il pulsante Testo per aggiungere un oggetto PlainTextContentControl alla prima cella.

7. Nella seconda colonna della tabella scegliere la seconda riga (accanto a Hire Date).

8. Nel gruppo Controlli scegliere il pulsante Selezione data per aggiungere un oggetto DatePickerContentControl alla seconda cella.

9. Nella seconda colonna della tabella scegliere la terza riga accanto a Titolo.

10. Nel gruppo Controlli scegliere il pulsante Elenco a discesa per aggiungere un DropDownListContentControl oggetto all'ultima cella.

    È l'intera interfaccia utente per questo progetto. Se si esegue il progetto a questo punto, è possibile digitare un testo nella prima riga e selezionare una data nella seconda riga. Il passaggio successivo consiste nell'allegare i dati che si vogliano visualizzare al documento in un file XML.

Creare il file di dati XML

In genere, si ottengono dati XML da archiviare in una parte XML personalizzata da un'origine esterna, ad esempio un file o un database. In questa procedura dettagliata è possibile creare un file XML che contiene i dati del dipendente, contrassegnati da elementi che verranno associati ai controlli contenuto del documento. Per rendere i dati disponibili in fase di esecuzione, incorporare il file XML come risorsa nell'assembly di personalizzazione.

Per creare il file di dati

1. Scegliere Aggiungi nuovo elemento dal menu Progetto.

   Verrà visualizzata la finestra di dialogo Aggiungi nuovo elemento .

2. Nel riquadro Modelli selezionare File XML.

3. Assegnare al file il nome employees.xml e quindi scegliere il pulsante Aggiungi .

   Il file employees.xml viene aperto nell'editor di codice.

4. Sostituire il contenuto del file employees.xml con il testo seguente.

   <?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. In Esplora soluzioni scegliere il file employees.xml.

6. Nella finestra Proprietà selezionare la proprietà Azione di compilazione e quindi modificare il valore in Risorsa incorporata.

   Questo passaggio incorpora il file XML come risorsa nell'assembly quando si compila il progetto. In questo modo è possibile accedere al contenuto del file XML in fase di esecuzione.

Creare un XML Schema

Se si intende associare un controllo contenuto a un singolo elemento in una parte XML personalizzata, non è necessario usare uno schema XML. Tuttavia, per associare DropDownListContentControl a un set di valori, è necessario creare uno schema XML che convalida il file di dati XML creato in precedenza. Lo schema XML definisce i valori possibili per l'elemento title. L'associazione di DropDownListContentControl a questo elemento viene eseguita più avanti in questa procedura dettagliata.

Per creare uno schema XML

1. Scegliere Aggiungi nuovo elemento dal menu Progetto.

   Verrà visualizzata la finestra di dialogo Aggiungi nuovo elemento .

2. Nel riquadro Modelli selezionare XML Schema.

3. Assegnare allo schema il nome employees.xsd e scegliere il pulsante Aggiungi .

   Viene aperta la progettazione schema.

4. In Esplora soluzioni aprire il menu di scelta rapida per employees.xsd e quindi scegliere Visualizza codice.

5. Sostituire il contenuto del file employees.xsd con lo schema seguente.

   <?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. Scegliere Salva tutto dal menu File per salvare le modifiche apportate ai file employees.xml e employees.xsd.

Allegare lo schema XML al documento

È necessario allegare lo schema XML al documento per associare DropDownListContentControl ai valori validi dell'elemento title.

Per collegare lo schema XML al documento ( Word 2013 )

1. Attivare EmployeeControls.docx nella finestra di progettazione.

2. Sulla barra multifunzione scegliere la scheda Sviluppo e quindi scegliere il pulsante Componenti aggiuntivi .

3. Nella finestra di dialogo Modelli e componenti aggiuntivi scegliere la scheda XML Schema e quindi scegliere il pulsante Aggiungi schema.

4. Passare allo schema employees.xsd creato in precedenza, che si trova nella directory del progetto e quindi scegliere il pulsante Apri .

5. Scegliere il pulsante OK nella finestra di dialogo Schema Impostazioni.

6. Scegliere il pulsante OK per chiudere la finestra di dialogo Modelli e componenti aggiuntivi .

Per allegare lo schema XML al documento (Word 2010)

1. Attivare EmployeeControls.docx nella finestra di progettazione.

2. Sulla barra multifunzione scegliere la scheda Sviluppo .

3. Nel gruppo XML scegliere il pulsante Schema.

4. Nella finestra di dialogo Modelli e componenti aggiuntivi scegliere la scheda XML Schema e quindi scegliere il pulsante Aggiungi schema.

5. Passare allo schema employees.xsd creato in precedenza, che si trova nella directory del progetto e scegliere il pulsante Apri .

6. Scegliere il pulsante OK nella finestra di dialogo Schema Impostazioni.

7. Scegliere il pulsante OK per chiudere la finestra di dialogo Modelli e componenti aggiuntivi .

   Verrà visualizzato il riquadro attività Struttura XML.

8. Chiudere il riquadro attività Struttura XML.

Aggiungere una parte XML personalizzata al documento

Prima di poter associare i controlli contenuto a elementi nel file XML, è necessario aggiungere il contenuto del file XML a una nuova parte XML personalizzata nel documento.

Per aggiungere una parte XML personalizzata al documento

1. In Esplora soluzioni aprire il menu di scelta rapida per ThisDocument.cs o ThisDocument.vb e quindi scegliere Visualizza codice.

2. Aggiungere le seguenti dichiarazioni alla classe ThisDocument. Questo codice dichiara diversi oggetti che verranno usati per aggiungere una parte XML personalizzata al 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. Aggiungere il seguente metodo alla classe ThisDocument. Questo metodo ottiene il contenuto del file di dati XML incorporato come risorsa nell'assembly e restituisce il contenuto come stringa 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. Aggiungere il seguente metodo alla classe ThisDocument. Il metodo crea AddCustomXmlPart una nuova parte XML personalizzata che contiene una stringa XML che viene passata al metodo.

   Per garantire che la parte XML personalizzata venga creata solo una volta, il metodo crea la parte XML personalizzata solo se non esiste già nel documento una parte XML personalizzata con GUID corrispondente. La prima volta che viene chiamato questo metodo, viene salvato il valore della proprietà Id per la stringa employeeXMLPartID. Il valore della stringa employeeXMLPartID viene mantenuto nel documento perché è stato dichiarato mediante l'attributo CachedAttribute.

   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
   

Associare i controlli contenuto agli elementi nella parte XML personalizzata

Associare ogni controllo contenuto a un elemento nella parte XML personalizzata utilizzando la proprietà XMLMapping di ogni controllo contenuto.

Per associare i controlli contenuto a elementi nella parte XML personalizzata

1. Aggiungere il seguente metodo alla classe ThisDocument. Questo metodo associa ogni controllo del contenuto a un elemento nella parte XML personalizzata e imposta il formato di visualizzazione della data di 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
   

Eseguire il codice all'apertura del documento

Creare la parte XML personalizzata e associare i controlli personalizzati ai dati quando il documento viene aperto.

Per eseguire il codice quando il documento è aperto

1. Aggiungere il seguente codice al metodo ThisDocument_Startup della classe ThisDocument. Questo codice ottiene la stringa XML dal file employees.xml , aggiunge la stringa XML a una nuova parte XML personalizzata nel documento e associa i controlli contenuto agli elementi nella parte XML personalizzata.

   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
   

Testare il progetto

Quando si apre il documento, i controlli contenuto consentono di visualizzare dati dagli elementi nella parte XML personalizzata. È possibile fare clic su DropDownListContentControl per selezionare uno dei tre valori validi per l'elemento title , definito nel file employees.xsd . Se si modificano i dati in uno dei controlli contenuto, i nuovi valori vengono salvati nella parte XML personalizzata del documento.

Per testare i controlli contenuto

1. Premere F5 per eseguire il progetto.

2. Verificare che la tabella nel documento sia simile alla tabella seguente. Tutte le stringhe della seconda colonna sono ottenute da un elemento nella parte XML personalizzata del documento.

   Column	Valore
   Nome dipendente	Karina Leal
   Data di assunzione	1 aprile 1999
   Title	Responsabile

3. Scegliere la cella a destra della cella Nome dipendente e digitare un nome diverso.

4. Scegliere la cella a destra della cella Hire Date e selezionare una data diversa nella selezione data.

5. Scegliere la cella a destra della cella Titolo e selezionare un nuovo elemento dall'elenco a discesa.

6. Salvare e chiudere il documento.

7. In Esplora file aprire la cartella \bin\Debug nel percorso del progetto.

8. Aprire il menu di scelta rapida per EmployeeControls.docx e quindi scegliere Rinomina.

9. Denominare il file EmployeeControls.docx.zip.

   Il documento EmployeeControls.docx viene salvato nel formato Open XML. Rinominando questo documento con l'estensione con estensione zip , è possibile esaminare il contenuto del documento. Per altre informazioni su Open XML, vedere l'articolo tecnico Introduzione ai formati di file Open XML di Office (2007).

10. Aprire il file EmployeeControls.docx.zip .

11. Aprire la cartella customXml .

12. Aprire il menu di scelta rapida per item2.xml e quindi scegliere Apri.

    Il file contiene la parte XML personalizzata che è stata aggiunta al documento.

13. Verificare che gli elementi name, hireDate e title contengano i nuovi valori immessi nei controlli contenuto nel documento.

14. Chiudere il file item2.xml .

Passaggi successivi

Per altre informazioni sull'utilizzo dei controlli contenuto, vedere gli argomenti seguenti:

• Usare tutti i controlli contenuto disponibili per creare un modello. Per altre informazioni, vedere Procedura dettagliata: Creare un modello usando i controlli contenuto.

• Modificare i dati nella parte XML personalizzata mentre il documento è chiuso. Alla successiva apertura del documento, i controlli contenuto associati agli elementi XML visualizzeranno i nuovi dati.

• Usare i controlli contenuto per proteggere parti di un documento. Per altre informazioni, vedere Procedura: Proteggere parti di documenti usando i controlli contenuto.

Contenuto correlato

• Automatizzare Word usando oggetti estesi
• Controlli contenuto
• Procedura: Aggiungere controlli contenuto ai documenti di Word
• Procedura: Proteggere parti di documenti usando i controlli contenuto
• Panoramica degli elementi host e dei controlli host
• Limitazioni a livello di codice degli elementi host e dei controlli host
• Aggiungere controlli ai documenti di Office in fase di esecuzione