Accesso ai dati dei documenti sul server

Articolo
08/11/2011

È possibile programmare i dati in una personalizzazione a livello di documento senza dovere utilizzare il modello a oggetti di Microsoft Office Word o Microsoft Office Excel. Ciò significa che è possibile accedere ai dati di un documento contenuto in un server in cui non è stato installato Word o Excel. Ad esempio, un server può contenere codice, quale il codice di una pagina ASP.NET, in grado di personalizzare i dati di un documento e quindi inviare il documento personalizzato a un utente finale. Quando l'utente finale apre il documento, il codice per l'associazione dati nell'assembly della soluzione consente di associare i dati personalizzati nel documento. Ciò è possibile perché i dati del documento sono separatati dall'interfaccia utente. Per ulteriori informazioni, vedere Dati memorizzati nella cache nelle personalizzazioni a livello di documento.

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

Memorizzazione dei dati nella cache per l'utilizzo su un server

Per memorizzare nella cache un oggetto dati di un documento, contrassegnarlo in fase di progettazione con l'attributo CachedAttribute o utilizzare in fase di esecuzione il metodo StartCaching di un elemento host. Quando si memorizza nella cache un oggetto dati in un documento, Runtime di Visual Studio Tools per Office serializza l'oggetto in una stringa XML memorizzata nel documento. Gli oggetti devono soddisfare determinati requisiti per essere idonei alla memorizzazione nella cache. Per ulteriori informazioni, vedere Memorizzazione di dati nella cache.

Il codice lato server può modificare qualsiasi oggetto dati contenuto nella cache di dati. I controlli associati alle istanze di dati memorizzate nella cache sono sincronizzati con l'interfaccia utente, per cui le modifiche del lato server eseguite sui dati vengono mostrate automaticamente quando il documento viene aperto sul client.

Accesso ai dati contenuti nella cache

È possibile accedere ai dati presenti nella cache da applicazioni esterne a Office, ad esempio da un'applicazione console, un'applicazione Windows Form o una pagina Web. L'applicazione che accede ai dati memorizzati nella cache deve essere completamente attendibile; un'applicazione Web parzialmente attendibile non potrà inserire, recuperare o modificare i dati memorizzati nella cache in un documento di Office.

La cache di dati è accessibile attraverso una gerarchia di insiemi esposti dalla proprietà CachedData della classe ServerDocument:

La proprietà CachedData restituisce un oggetto Microsoft.VisualStudio.Tools.Applications.CachedData che contiene tutti i dati memorizzati nella cache di una personalizzazione a livello di documento.
Ogni oggetto Microsoft.VisualStudio.Tools.Applications.CachedData contiene uno o più oggetti CachedDataHostItem. L'oggetto CachedDataHostItem contiene tutti gli oggetti dati memorizzati nella cache definiti all'interno di una singola classe.
Ogni oggetto CachedDataHostItem contiene uno o più oggetti CachedDataItem. Un oggetto CachedDataItem rappresenta un solo oggetto dati memorizzato nella cache.

Nell'esempio di codice seguente viene illustrato come accedere a una stringa memorizzata nella cache contenuta nella classe Sheet1 di un progetto Cartella di lavoro di Excel. Questo esempio fa parte di un esempio più esaustivo fornito per il metodo ServerDocument.Save.

serverDocument1 = New ServerDocument(documentPath)
Dim hostItem1 As CachedDataHostItem = _
    serverDocument1.CachedData.HostItems("ExcelWorkbook1.Sheet1")
Dim dataItem1 As CachedDataItem = hostItem1.CachedData("CachedString")

serverDocument1 = new ServerDocument(documentPath);
CachedDataHostItem hostItem1 = 
    serverDocument1.CachedData.HostItems["ExcelWorkbook1.Sheet1"];
CachedDataItem dataItem1 = hostItem1.CachedData["CachedString"];

Per un esempio di codice che illustra come accedere ai dati contenuti in un oggetto DataSet memorizzato nella cache, vedere Procedura: recuperare i dati memorizzati nella cache di una cartella di lavoro di un server.

Modifica dei dati nella cache

Per modificare un oggetto dati memorizzato nella cache in genere si eseguono i passaggi seguenti:

Deserializzare la rappresentazione XML dell'oggetto memorizzato nella cache in una nuova istanza dell'oggetto. Per accedere al codice XML è possibile utilizzare la proprietà Xml dell'oggetto CachedDataItem che rappresenta l'oggetto dati memorizzato nella cache.
Apportare le modifiche a questa copia.
Serializzare l'oggetto modificato nella cache di dati tramite una delle opzioni seguenti:
- Se si desidera serializzare automaticamente le modifiche, utilizzare il metodo SerializeDataInstance. Questo metodo utilizza il formato DiffGram per serializzare gli oggetti DataSet, DataTable e gli oggetti DataSet tipizzati nella cache di dati. Il formato DiffGram garantisce che le modifiche apportate alla cache di dati in un documento offline vengano inviate al server correttamente. Per ulteriori informazioni, vedere DiffGram (ADO.NET).
- Se si desidera eseguire la serializzazione personalizzata per le modifiche ai dati memorizzati, è possibile scrivere direttamente nella proprietà Xml. Specificare il formato DiffGram se si utilizza un oggetto DataAdapter per aggiornare un database con modifiche apportate ai dati in un oggetto DataSet, DataTable o in un dataset tipizzato. In caso contrario, il database verrà aggiornato dall'oggetto DataAdapter tramite l'aggiunta di nuove righe anziché la modifica delle righe esistenti.

Per un esempio di codice che illustri come serializzare le modifiche apportate a un oggetto dati memorizzati tramite la scrittura diretta nella proprietà Xml, vedere Procedura: modificare i dati memorizzati nella cache di una cartella di lavoro di un server.

Modifica dei dati senza deserializzare il valore corrente

In alcuni casi è necessario modificare il valore dell'oggetto memorizzato nella cache senza prima deserializzare il valore corrente. Ad esempio, questo approccio è utile quando si modifica il valore di un oggetto che presenta un tipo semplice, quale una stringa o un numero intero, o quando si inizializza un oggetto DataSet memorizzato nella cache e appartenente a un documento contenuto in un server. In questi casi è possibile utilizzare il metodo SerializeDataInstance senza prima deserializzare il valore corrente dell'oggetto memorizzato nella cache.

Nell'esempio di codice seguente viene illustrato come modificare il valore di una stringa memorizzata nella cache contenuta nella classe Sheet1 di un progetto Cartella di lavoro di Excel. Questo esempio fa parte di un esempio più esteso fornito per il metodo ServerDocument.Save.

serverDocument1 = New ServerDocument(documentPath)
Dim hostItem1 As CachedDataHostItem = _
    serverDocument1.CachedData.HostItems("ExcelWorkbook1.Sheet1")
Dim dataItem1 As CachedDataItem = hostItem1.CachedData("CachedString")

If dataItem1 IsNot Nothing AndAlso _
    Type.GetType(dataItem1.DataType).Equals(GetType(String)) Then

    dataItem1.SerializeDataInstance("This is the new cached string value.")
    serverDocument1.Save()
End If

serverDocument1 = new ServerDocument(documentPath);
CachedDataHostItem hostItem1 = 
    serverDocument1.CachedData.HostItems["ExcelWorkbook1.Sheet1"];
CachedDataItem dataItem1 = hostItem1.CachedData["CachedString"];

if (dataItem1 != null &&
    Type.GetType(dataItem1.DataType) == typeof(string))
{
    dataItem1.SerializeDataInstance("This is the new cached string value.");
    serverDocument1.Save();
}

Per un esempio di codice che illustra come inizializzare un oggetto DataSet memorizzato nella cache contenuto in un server, vedere Procedura: inserire dati in una cartella di lavoro sul server.

Modifica di valori null contenuti nella cache di dati

La cache di dati non memorizza oggetti che presentano il valore null quando il documento viene salvato e chiuso. Questa limitazione comporta diverse conseguenze quando si modificano i dati memorizzati nella cache:

Se uno degli oggetti contenuti nella cache di dati viene impostato sul valore null, all'apertura del documento tutti gli oggetti nella cache di dati vengono impostati automaticamente su null. Inoltre, l'intera cache di dati viene cancellata quando il documento viene salvato e chiuso. In altre parole, tutti gli oggetti memorizzati nella cache vengono rimossi dalla cache di dati e l'insieme CachedData è vuoto.
Se si compila una soluzione che presenta oggetti null nella cache di dati e si desidera inizializzare questi oggetti tramite la classe ServerDocument prima che il documento venga aperto per la prima volta, è necessario assicurarsi di inizializzare tutti gli oggetti contenuti nella cache di dati. Se invece si inizializzano soltanto alcuni di essi, all'apertura del documento tutti gli oggetti vengono impostati su null e l'intera cache di dati viene cancellata quando il documento viene salvato e chiuso.

Accesso ai DataSet tipizzati nella cache

Se si desidera accedere ai dati in un dataset tipizzato sia da una soluzione Office sia da un'applicazione esterna ad Office, , ad esempio un'applicazione Windows Form o un progetto ASP.NET, il dataset tipizzato deve essere definito in un assembly distinto a cui si fa riferimento in entrambi i progetti. Se il DataSet tipizzato viene aggiunto a ogni progetto utilizzando la Configurazione guidata origine dati o Progettazione DataSet, i DataSet tipizzati dei due progetti verranno considerati da .NET Framework come due tipi diversi. Per ulteriori informazioni sulla creazione di dataset tipizzati, vedere Procedura: creare un dataset tipizzato.