Procedura dettagliata: Associare controlli contenuto a parti XML personalizzate

  • Articolo

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:

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 PlainTextContentControl 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 DatePickerContentControl 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 DropDownListContentControl 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.

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

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

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

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.

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

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.

    string xmlData = GetXmlFromResource();

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

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:

Contenuto correlato