Accès aux données des documents sur le serveur
Mise à jour : novembre 2007
S'applique à |
|---|
Les informations de cette rubrique s'appliquent uniquement aux projets Visual Studio Tools pour Office et versions de Microsoft Office spécifiés. Type de projet
Version de Microsoft Office
Pour plus d'informations, consultez Fonctionnalités disponibles par type d'application et de projet. |
Visual Studio Tools pour Office vous permet de programmer les données dans une personnalisation au niveau du document sans avoir à 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 Modèle de données dans les personnalisations au niveau du document.
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, l'exécution de Visual Studio Tools pour Office 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 :
La propriété CachedData retourne un Microsoft.VisualStudio.Tools.Applications.CachedData, qui contient toute les données en mémoire cache dans une personnalisation au niveau du document.
Chaque Microsoft.VisualStudio.Tools.Applications.CachedData contient un ou plusieurs objets CachedDataHostItem. Un CachedDataHostItem contient tous les objets de données en mémoire cache définis dans une seule classe.
Chaque CachedDataHostItem contient un ou plusieurs objets CachedDataItem. CachedDataItem représente un objet de données en mémoire cache unique.
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"];
Pour obtenir un exemple de code qui montre comment accéder aux données dans un DataSet mis en cache, consultez Comment : récupérer des données mises en cache d'un classeur sur un serveur.
.gif "Remarque") Remarque : |
|---|
La classe ServerDocument et les classes de données en mémoire cache dans l'espace de noms Microsoft.VisualStudio.Tools.Applications ne peuvent être utilisées qu'avec les solutions destinées à la version 2007 de Microsoft Office System. Si vous utilisez des solutions pour Microsoft Office 2003, utilisez la classe ServerDocument et les classes de données en mémoire cache dans l'espace de noms Microsoft.VisualStudio.Tools.Applications.Runtime. Pour plus d'informations, consultez Gestion de documents sur un serveur à l'aide de la classe ServerDocument. |
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 :
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.
Apportez les modifications nécessaires à cette copie.
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. Pour plus d'informations, consultez DiffGrams (ADO.NET).
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.
Pour obtenir un exemple de code illustrant comment sérialiser des modifications apportées à un objet de données mis en cache en écrivant directement dans la propriété Xml, consultez Comment : modifier les données mises en cache dans un classeur sur un serveur.
Modification 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();
}
Pour obtenir un exemple de code qui montre comment initialiser un DataSet mis en cache sur un serveur, consultez Comment : insérer des données dans un classeur sur un serveur.
Modification 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 aux données d'un groupe de données typé à partir d'une solution Visual Studio Tools pour Office et d'une application différente d'Office, comme une application Windows Forms ou un projet ASP.NET, tenez compte des considérations suivantes :
Vous devez définir le groupe de données typé dans un assembly distinct 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é.
Vous devez accorder une confiance appropriée dans la stratégie de sécurité de chaque utilisateur final pour l'assembly contenant le groupe de données typé. Pour plus d'informations, consultez Spécifications de sécurité pour exécuter des solutions Office (Office System 2003).
Voir aussi
Tâches
Comment : récupérer des données mises en cache d'un classeur sur un serveur
Comment : modifier les données mises en cache dans un classeur sur un serveur
Comment : insérer des données dans un classeur sur un serveur
Concepts
Accès aux données des documents sur le serveur
Modèle de données dans les personnalisations au niveau du document