Partager via

Accès aux données des documents sur le serveur

  • Article

Vous pouvez programmer par rapport aux données d'une personnalisation au niveau du document sans devoir utiliser le modèle objet de Microsoft Office Word ou Microsoft Office Excel.Cela signifie que vous pouvez accéder aux données contenues dans un document sur un serveur sur lequel Word ou Excel n'est pas installé.Par exemple, un code sur un serveur (dans une page ASP.NET, par exemple) peut personnaliser les données d'un document et envoyer le document ainsi personnalisé à un utilisateur final.Lorsque l'utilisateur final ouvre le document, le code de liaison de données dans l'assembly de solution lie les données personnalisées dans le document.Cette opération est possible car les données du document sont séparées de l'interface utilisateur.Pour plus d’informations, consultez Données mises en cache dans des personnalisations au niveau du document.

S'applique à : Les informations contenues dans cette rubrique s'appliquent aux projets de niveau document pour les applications suivantes : Excel 2013, Excel 2010, Word 2013 et Word 2010. Pour en savoir plus, consultez Fonctionnalités disponibles par type d'application et de projet Office.

Mise en cache de données pour une utilisation sur un serveur

Pour mettre un objet de données en cache dans un document, marquez-le avec l'attribut CachedAttribute au moment du design ou utilisez la méthode StartCaching d'un élément hôte au moment de l'exécution.Lorsque vous mettez en cache un objet de données dans un document, Visual Studio Tools pour Office Runtime sérialise l'objet dans une chaîne XML stockée dans le document.Pour pouvoir être mis en cache, les objets doivent répondre à certains critères.Pour plus d’informations, consultez Mise en cache des données.

Le code côté serveur peut manipuler n'importe quel objet de données dans le cache de données.Les contrôles liés aux instances de données en mémoire cache sont synchronisés avec l'interface utilisateur, afin que toutes les modifications côté serveur apportées aux données s'affichent automatiquement lorsque le document est ouvert sur le client.

Accès aux données du cache

Vous pouvez accéder aux données contenues dans le cache à partir d'applications en dehors de Microsoft Office, par exemple à partir d'une application console, d'une application Windows Forms ou d'une page Web.L'application qui accède aux données en mémoire cache doit avoir le niveau de confiance totale ; une application Web qui dispose de la confiance partielle ne peut pas insérer, récupérer ou modifier des données mises en cache dans un document Office.

Le cache de données est accessible via une hiérarchie de collections exposées par la propriété CachedData de la classe ServerDocument :

L'exemple de code suivant montre comment accéder à une chaîne mise en cache dans la classe Sheet1 d'un projet de classeur Excel.Cet exemple de code fait partie d'un exemple plus complet fourni pour la méthode 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"];

Modification des données du cache

Pour modifier un objet des données en mémoire cache, vous suivez généralement la procédure suivante :

  1. Désérialisez la représentation XML de l'objet en mémoire cache dans une nouvelle instance de l'objet.Vous pouvez accéder au XML à l'aide de la propriété Xml du CachedDataItem qui représente l'objet de données en mémoire cache.

  2. Apportez les modifications nécessaires à cette copie.

  3. Resérialisez l'objet modifié dans le cache de données à l'aide d'une des options suivantes :

    • Pour sérialiser automatiquement les modifications, utilisez la méthode SerializeDataInstance.Cette méthode utilise le format DiffGram pour sérialiser le DataSet, le DataTable et les objets d'un groupe de données typé dans le cache de données.Le format DiffGram garantit que les modifications apportées au cache de données dans un document hors connexion sont envoyées correctement au serveur.

    • Si vous souhaitez exécuter votre propre sérialisation des modifications apportées aux données mises en cache, vous pouvez écrire directement dans la propriété Xml.Spécifiez le format DiffGram si vous utilisez DataAdapter pour mettre à jour une base de données avec les modifications apportées aux données dans un groupe de données DataSet, DataTable ou typé.Sinon, le DataAdapter mettra à jour la base de données en ajoutant de nouvelles lignes au lieu de modifier des lignes existantes.

427e3fw2.collapse_all(fr-fr,VS.110).gifModification de données sans désérialiser la valeur actuelle

Dans certains cas, vous pouvez souhaiter modifier la valeur de l'objet mis en cache sans désérialiser préalablement la valeur actuelle.Vous pouvez par exemple procéder de la sorte si vous modifiez la valeur d'un objet de type simple, tel qu'une chaîne ou un nombre entier, ou si vous initialisez un DataSet mis en cache dans un document sur un serveur.Dans ces cas-là, vous pouvez utiliser la méthode SerializeDataInstance sans désérialiser en préalablement la valeur actuelle de l'objet mis en cache.

L'exemple de code suivant montre comment modifier la valeur d'une chaîne mise en cache dans la classe Sheet1 d'un projet de classeur Excel.Cet exemple de code fait partie d'un exemple plus complet fourni pour la méthode 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();
}

427e3fw2.collapse_all(fr-fr,VS.110).gifModification de valeurs null dans le cache de données

Le cache de données ne stocke aucun objet ayant la valeur null lorsque le document est enregistré et fermé.Cette limitation a plusieurs conséquences lorsque vous modifiez les données mises en cache :

  • Si vous affectez la valeur null à un objet quelconque du cache de données, tous les objets du cache prendront automatiquement la valeur null à l'ouverture du document et l'ensemble du cache de données sera effacé lors de l'enregistrement et de la fermeture du document.Autrement dit, tous les objets mis en cache seront supprimés du cache de données et la collection CachedData sera vide.

  • Si vous construisez une solution avec des objets null dans le cache de données et vous souhaitez initialiser ces objets à l'aide de la classe ServerDocument avant la première ouverture du document, vous devez veiller à initialiser tous les objets du cache de données.Si vous initialisez uniquement certains objets, tous les objets prendront la valeur null à l'ouverture du document et l'ensemble du cache de données entier sera effacé lors de l'enregistrement et de la fermeture du document.

Accès aux groupes de données typées du cache

Si vous souhaitez accéder à la fois aux données d'un dataset typé d'une solution Office et d'une application non Office, telle qu'une application Windows Forms ou un projet ASP.NET, vous devez définir le groupe de données typé dans un assembly séparé, référencé dans les deux projets.Si vous ajoutez le groupe de données typé à chaque projet à l'aide de l'Assistant Configuration de source de données ou du Concepteur de DataSet, le .NET Framework traitera les groupes de données typées dans les deux projets comme des types différents.Pour plus d'informations sur la création de groupes de données typés, consultez Comment : créer un groupe de données typé.

Voir aussi

Concepts

Accès aux données des documents sur le serveur

Données mises en cache dans des personnalisations au niveau du document