Procedura dettagliata: associazione dei controlli del contenuto a parti XML personalizzate

In questa procedura dettagliata viene illustrato come associare i controlli del contenuto in una personalizzazione a livello di documento per Word ai dati XML archiviati nel documento.

Si applica a: le informazioni fornite in questo argomento sono valide per i progetti a livello di documento per Word 2007 e Word 2010. Per ulteriori informazioni, vedere Funzionalità disponibili in base ai tipi di progetto e applicazioni di Office.

Word consente di archiviare i dati XML, denominati parti XML personalizzate, in un documento. È possibile controllare la visualizzazione di questi dati associando i controlli del contenuto agli elementi in una parte XML personalizzata. Il documento di esempio in questa procedura dettagliata visualizza informazioni sul personale archiviate in una parte XML personalizzata. Quando si apre il documento, i controlli del contenuto visualizzano i valori degli elementi XML. Qualsiasi modifica apportata al testo nei controlli del contenuto viene salvata nella parte XML personalizzata.

In questa procedura dettagliata vengono illustrate le attività seguenti:

• Aggiunta di controlli del 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 del contenuto.

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

• Associazione dei controlli del contenuto agli elementi nella parte XML personalizzata.

• Associazione di un oggetto DropDownListContentControl a un insieme di valori definito nello schema XML.

Nota

Nel computer in uso è possibile che vengano visualizzati nomi o percorsi diversi per alcuni elementi dell'interfaccia utente di Visual Studio nelle istruzioni seguenti. La versione di Visual Studio in uso e le impostazioni configurate determinano questi elementi. Per ulteriori informazioni vedere Impostazioni di Visual Studio.

Prerequisiti

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

-

Una versione di Visual Studio 2010 che include gli strumenti per sviluppatori di Microsoft Office. Per ulteriori informazioni, vedere [Configurazione di un computer per sviluppare soluzioni Office](bb398242\(v=vs.100\).md).

• Microsoft Office Word 2007 o Word 2010.

Per una versione video di questo argomento, vedere la procedura relativa all'associazione di controlli di contenuto alle web part XML personalizzate (la pagina potrebbe essere in inglese).

Creazione di un nuovo progetto Documento di Word

Creare un documento di Word che si utilizzerà nella procedura dettagliata.

Per creare un nuovo progetto Documento di Word

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

  Il nuovo documento di Word verrà aperto nella finestra di progettazione di Visual Studio e il progetto EmployeeControls verrà aggiunto a Esplora soluzioni.

Aggiunta di controlli del contenuto al documento

Creare una tabella contenente tre tipi diversi di controlli del contenuto in cui l'utente può vedere o modificare le informazioni su un dipendente.

Per aggiungere i controlli del contenuto al documento

1. Nel documento di Word contenuto nella finestra di progettazione Visual Studio, fare clic sulla scheda Inserisci sulla barra multifunzione.

2. Nel gruppo Tabelle, fare clic su Tabella e inserire una tabella con 2 colonne e 3 righe.

3. Digitare nella prima colonna un testo simile alla colonna seguente:

   Nome dipendente

   Data assunzione

   Titolo

4. Nella seconda colonna della tabella, fare clic nella prima riga accanto a Nome dipendente.

5. Nella barra multifunzione, fare clic sulla scheda Sviluppatore.

   Nota

   Se la scheda Sviluppatore non è visibile, è necessario prima visualizzarla. Per ulteriori informazioni, vedere Procedura: visualizzare la scheda Sviluppo nella barra multifunzione.

6. Nel gruppo Controlli, fare clic sul pulsante Testo per aggiungere PlainTextContentControl alla prima cella.

7. Nella seconda colonna della tabella, fare clic nella seconda riga accanto a Data assunzione.

8. Nel gruppo Controlli, fare clic sul pulsante Selezione data per aggiungere DatePickerContentControl alla seconda cella.

9. Nella seconda colonna della tabella, fare clic nella terza riga accanto a Titolo.

10. Nel gruppo Controlli, fare clic sul pulsante Casella di riepilogo a discesa per aggiungere DropDownListContentControl all'ultima cella.

L'interfaccia utente per questo progetto è completata. Se si esegue subito il progetto, è possibile digitare il testo nella prima riga e selezionare una data nella seconda riga. Il prossimo passaggio consiste nel connettere i dati da visualizzare al documento in un file XML.

Creazione del file di dati XML

In genere, si otterrà l'archiviazione dei dati XML in una parte XML personalizzata tramite un'origine esterna, ad esempio un file o un database. In questa procedura dettagliata, viene creato un file XML contenente i dati del dipendente, contrassegnati da elementi che verranno associati ai controlli del contenuto nel documento. Per rendere disponibili i dati 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.

   Viene visualizzata la finestra di dialogo Aggiungi nuovo elemento.

2. Nel riquadro Modelli selezionare File XML.

3. Assegnare un nome al file employees.xml e scegliere Aggiungi.

   Il file employees.xml verrà aperto nell'editor di codice.

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

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

5. In Esplora soluzioni, fare clic su employees.xml.

6. Nella finestra Proprietà selezionare la proprietà Operazione di compilazione e cambiare il valore in Risorsa incorporata.

   In questo passaggio, il file XML viene incorporato come risorsa nell'assembly quando il progetto viene compilato. In tal modo sarà possibile accedere al contenuto del file XML in fase di esecuzione.

Creazione di uno schema XML

Per associare un controllo del contenuto a un solo elemento in una parte XML personalizzata, non è necessario utilizzare uno schema XML. Tuttavia, per associare DropDownListContentControl a un insieme di valori, è necessario creare un schema XML che convalidi il file di dati XML creato precedentemente. Lo schema XML definisce i possibili valori per l'elemento title. Più avanti in questa procedura dettagliata, DropDownListContentControl verrà associato a questo elemento.

Per creare uno schema XML

1. Scegliere Aggiungi nuovo elemento dal menu Progetto.

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

   Verrà visualizzata la finestra Progettazione schema.

4. In Esplora soluzioni fare clic con il pulsante destro del mouse su employees.xsd, quindi scegliere Visualizza codice.

5. Sostituire il contenuto del file employees.xml con il seguente schema.

   <?xml version="1.0" encoding="utf-8" ?>
   <xs:schema xmlns="https://schemas.microsoft.com/vsto/samples" 
       targetNamespace="https://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. Nel menu File, fare clic su Salva tutto per salvare le modifiche nei file employees.xml e employees.xsd.

Connessione dello schema XML al documento

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

Per connettere lo schema XML al documento

1. Attivare EmployeeControls.docx nella finestra di progettazione.

2. Nella barra multifunzione, fare clic sulla scheda Sviluppatore.

3. Nel gruppo XML, fare clic su Schema.

4. Selezionare la scheda XML Schema nella finestra di dialogo Modelli e aggiunte, quindi scegliere Aggiungi schema.

5. Selezionare lo schema employees.xsd creato in precedenza, contenuto nella directory del progetto e scegliere Apri.

6. Scegliere OK nella finestra di dialogo Impostazioni schema.

7. Scegliere OK per chiudere la finestra di dialogo Modelli e aggiunte.

   Verrà aperto il riquadro attività Struttura XML.

8. Chiudere il riquadro attività Struttura XML.

Aggiunta di una parte XML personalizzata al documento

Prima di poter associare i controlli del contenuto agli 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, fare clic con il pulsante destro del mouse su ThisDocument.cs o ThisDocument.vb e scegliere Visualizza codice.

2. Aggiungere le seguenti dichiarazioni alla classe ThisDocument. In questo codice vengono dichiarati molti oggetti che si utilizzeranno per aggiungere una parte XML personalizzata al documento.

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

   [CachedAttribute()]
   public string employeeXMLPartID = string.Empty;
   private Office.CustomXMLPart employeeXMLPart;
   private const string prefix = "xmlns:ns='https://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.

   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
   

   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;
   }
   

4. Aggiungere il seguente metodo alla classe ThisDocument. Il metodo AddCustomXmlPart crea una nuova parte XML personalizzata contenente 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 solo se nel documento non esiste già una parte XML personalizzata con lo stesso GUID. Alla prima chiamata, il metodo salva il valore della proprietà Id nella stringa employeeXMLPartID. Il valore della stringa employeeXMLPartID è salvato in modo permanente nel documento perché è stato dichiarato mediante l'attributo CachedAttribute.

   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", _
                   "https://schemas.microsoft.com/vsto/samples")
               employeeXMLPartID = employeeXMLPart.Id
           End If
       End If
   End Sub
   

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

Associazione dei controlli del contenuto agli elementi nella parte XML personalizzata

Per associare un controllo del contenuto a un elemento nella parte XML personalizzata, utilizzare la proprietà XMLMapping di ogni controllo del contenuto.

Per associare i controlli del contenuto agli elementi nella parte XML personalizzata

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

  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
  

  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);
  }
  

Esecuzione di codice quando il documento è aperto

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

Per eseguire il codice quando il documento è aperto

• 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 del contenuto agli elementi nella parte XML personalizzata.

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

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

Verifica del progetto

Quando si apre il documento, i controlli del contenuto visualizzano i dati dagli elementi nella parte XML personalizzata. È possibile selezionare DropDownListContentControl per scegliere uno dei tre valori validi per l'elemento title definiti nel file employees.xsd. Se i dati nei controlli del contenuto vengono modificati, i nuovi valori vengono salvati nella parte XML personalizzata nel documento.

Per verificare i controlli del contenuto

1. Premere F5 per eseguire il progetto.

2. Verificare che la tabella nel documento sia simile alla tabella seguente. Ogni stringa della seconda colonna viene ottenuta da un elemento nella parte XML personalizzata nel documento.

   Nome dipendente	Karina Leal
   Data assunzione	1 aprile 1999
   Titolo	Manager

3. Fare clic nella cella a destra della cella Nome dipendente e digitare un nome diverso.

4. Fare clic nella cella a destra della cella Data assunzione e selezionare una data diversa nella selezione data.

5. Fare clic nella cella a destra della cella Titolo e selezionare un nuovo elemento nella casella di riepilogo a discesa.

6. Salvare e chiudere il documento.

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

8. Fare clic con il pulsante destro del mouse su EmployeeControls.docx e scegliere Rinomina.

9. Assegnare al file il nome EmployeeControls.docx.zip.

   Il documento EmployeeControls.docx viene salvato nel formato Open XML. Il documento è stato rinominato con l'estensione del nome file zip e quindi è possibile esaminare il contenuto del documento. Per ulteriori informazioni sul formato Open XML, vedere l'articolo tecnico Introduzione ai formati di file Office Open XML (2007).

10. Fare doppio clic sul file EmployeeControls.docx.zip.

11. Fare doppio clic sulla cartella customXml.

12. Fare clic con il pulsante destro del mouse su item2.xml, 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 del contenuto nel documento.

14. Chiudere il file item2.xml.

Passaggi successivi

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

• Utilizzare tutti i controlli del contenuto disponibili per creare un modello. Per ulteriori informazioni, vedere Procedura dettagliata: creazione di un modello utilizzando i controlli del contenuto.

• Modificare i dati nelle parti XML personalizzate con il documento chiuso. La volta successiva che l'utente apre il documento, i controlli del contenuto associati agli elementi XML visualizzeranno i nuovi dati. Per ulteriori informazioni, vedere Procedura: aggiungere web part XML personalizzate a documenti senza avviare Microsoft Office.

• Utilizzare i controlli del contenuto per proteggere parti di un documento. Per ulteriori informazioni, vedere Procedura: proteggere parti di documenti mediante i controlli del contenuto.

Vedere anche

Attività

Procedura: aggiungere controlli del contenuto ai documenti di Word

Procedura: proteggere parti di documenti mediante i controlli del contenuto

Concetti

Automazione di Word utilizzando oggetti estesi

Controlli del contenuto

Cenni preliminari sugli elementi e sui controlli host

Limitazioni a livello di codice degli elementi e dei controlli host

Aggiunta di controlli ai documenti di Office in fase di esecuzione

Metodi di supporto per i controlli host