Kit de ressources CASI - Partie 3
Kit de ressources CASI - Partie 3
Ceci est la troisième partie d’une série en cinq parties consacrée au Kit CASI (Claims, Azure and SharePoint Integration). La partie 1 était une vue d’ensemble qui présentait l’intégralité de l’infrastructure et de la solution, et qui décrivait les objectifs de la série. La partie 2 a expliqué comment créer vos applications WCF, comment en faire des applications prenant en charge les revendications, puis comment les intégrer à Windows Azure. Dans cet article, je vais décrire l’un des livrables les plus importants de l’infrastructure. Il s’agit d’une classe de base de contrôle personnalisé qui vous permet d’établir la connexion entre SharePoint et votre application WCF hébergée dans Windows Azure. Voici les points abordés :
· Classe de base – À quoi elle correspond et comment l’utiliser dans votre projet
· Page de disposition – Comment ajouter votre nouveau contrôle à une page du répertoire _layouts
· Propriétés importantes – Description des propriétés importantes à connaître dans la classe de base
Classe de base du Kit CASI
L’un des principaux livrables du Kit CASI est la classe de base d’un contrôle personnalisé qui se connecte à votre application WCF et envoie des requêtes à l’aide du jeton d’ouverture de session de l’utilisateur actuel. La classe de base proprement dite est un contrôle serveur ASP.NET standard. L’implémentation de ce modèle de développement vous oblige à créer un contrôle serveur ASP.NET qui hérite de cette classe de base. Pour des raisons qui dépassent le cadre de cet article, votre contrôle doit pouvoir faire deux choses :
1. Créer une référence de service pour votre application WCF hébergée dans Windows Azure.
2. Substituer la méthode ExecuteRequest de la classe de base. En fait, c’est plutôt simple, car il vous suffit d’écrire environ cinq lignes de code pour créer et configurer le proxy qui va se connecter à votre application WCF, puis appeler la méthode ExecuteRequest de la classe de base.
Pour commencer, créez un projet dans Visual Studio et choisissez le projet de type Bibliothèque de classes Windows. Après avoir remplacé l’espace de noms et le nom de classe par ce qui vous convient, vous devez ajouter une référence à la classe de base du Kit CASI, qui se trouve dans l’assembly AzureConnect.dll. Vous devez également ajouter des références aux assemblys suivants : Microsoft.SharePoint, System.ServiceModel, System.Runtime.Serialization et System.Web.
Dans votre classe de base, ajoutez une instruction using pour Microsoft.SharePoint, puis modifiez votre classe de sorte qu’elle hérite d’AzureConnect.WcfConfig. WcfConfig est la classe de base qui contient l’intégralité du code et de la logique permettant de se connecter à l’application WCF, d’inclure toutes les propriétés afin d’accroître la flexibilité de l’implémentation, et d’éliminer tout recours aux modifications web.config classiques qui sont normalement nécessaires pour se connecter à un point d’arrêt de service WCF. Il est important de bien comprendre ceci : en règle générale, vous devez ajouter près d’une centaine de lignes de modifications web.config pour chaque application WCF à laquelle vous vous connectez, pour chaque fichier web.config de chaque serveur, pour chaque application Web l’ayant utilisé. La classe de base WcfConfig inclut tout cela dans le contrôle proprement dit ; par conséquent, il vous suffit d’hériter du contrôle et le reste se fait automatiquement. Toutes les propriétés qui doivent être modifiées dans le fichier web.config peuvent l’être également dans le contrôle WcfConfig, car il expose les propriétés de l’ensemble d’entre elles. J’approfondirai ce point dans la section consacrée aux propriétés importantes.
Il est temps à présent d’ajouter une nouvelle référence de service à votre application WCF hébergée dans Windows Azure. Il n’y a rien de spécifique au Kit CASI que vous ayez à effectuer ici. Cliquez simplement avec le bouton droit sur Références dans votre projet, puis sélectionnez Ajouter une référence de service. Indiquez l’URL vers votre application WCF Azure en spécifiant « ?WSDL » à la fin, de sorte qu’elle récupère le WSDL correspondant à votre implémentation de service. Remplacez ensuite le nom par ce que vous voulez, ajoutez la référence et c’est tout pour cette partie.
À ce stade, vous disposez d’une classe vide et d’une référence de service pour votre application WCF. Passons à présent à la partie écriture du code, qui est heureusement plutôt courte. Vous devez substituer la méthode ExecuteRequest, créer et configurer le proxy de la classe de service, puis appeler la méthode ExecuteRequest de la classe de base. Pour simplifier, voici le code complet de l’exemple de contrôle joint à cet article ; j’ai surligné en jaune les parties que vous devez modifier pour qu’elles correspondent à votre référence de service :
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Diagnostics;
using Microsoft.SharePoint;
//requiert des références à :
//1. AzureConnect
//2. Microsoft.SharePoint
//3. System.ServiceModel
//4. System.Runtime.Serialization
//5. System.Web
namespace AzureWcfPage
{
public class WcfDataControl : AzureConnect.WcfConfig
{
//cette méthode doit être substituée pour que le proxy puisse
//être configuré et créé correctement
public override bool ExecuteRequest()
{
try
{
//crée l’instance de proxy avec les liaisons et le point de terminaison que
//le contrôle de configuration de la classe de base a créés à cet effet
CustomersWCF.CustomersClient cust =
new CustomersWCF.CustomersClient(this.FedBinding,
this.WcfEndpointAddress);
//configure le canal pour que nous puissions l’appeler avec
//FederatedClientCredentials.
SPChannelFactoryOperations.ConfigureCredentials<CustomersWCF.ICustomers>
(cust.ChannelFactory,
Microsoft.SharePoint.SPServiceAuthenticationMode.Claims);
//crée un canal vers le point de terminaison WCF via
//le jeton et les revendications de l’utilisateur actuel
CustomersWCF.ICustomers claimsWCF =
SPChannelFactoryOperations.CreateChannelActingAsLoggedOnUser
<CustomersWCF.ICustomers>(cust.ChannelFactory,
this.WcfEndpointAddress,
new Uri(this.WcfEndpointAddress.Uri.AbsoluteUri));
//définit la propriété cliente pour la classe de base
this.WcfClientProxy = claimsWCF;
}
catch (Exception ex)
{
Debug.WriteLine(ex.Message);
}
//une fois la configuration terminée, appelle la méthode
return base.ExecuteRequest();
}
}
}
Au final, vous avez principalement cinq lignes de code. Il vous suffit de copier et de coller directement le code de la substitution d’ExcecuteRequest indiquée ici dans votre propre substitution. Vous n’avez plus ensuite qu’à remplacer les parties surlignées en jaune par la classe et les interfaces appropriées exposées par votre application WCF. Dans le code surligné ci-dessus :
· CustomersWCF.CustomersClient : « CustomersWCF » est le nom que j’ai utilisé lorsque j’ai créé ma référence de service, et CustomersClient est le nom de la classe que j’ai exposée via mon application WCF. Le nom de la classe dans mon application WCF est en fait « Customers ». L’outil Ajouter une référence de service de VS.NET ajoute la partie « Client » à la fin.
· CustomersWCF.ICustomers : « CustomersWCF » est identique à ce qui est décrit ci-dessus. « ICustomers » est l’interface que j’ai créée dans mon application WCF et qui est en fait implémentée par ma classe « Customers » WCF.
C’est fini. Vous n’avez pas besoin d’écrire de lignes de code supplémentaires pour établir la connexion vers votre application WCF hébergée dans Windows Azure. Plutôt facile, vous ne trouvez pas ? Petit détail, le code que vous avez écrit est ce qui permet de passer l’appel de l’application WCF avec le jeton de l’utilisateur SharePoint. J’ai expliqué ce point avec davantage de détails dans cet autre article : https://blogs.technet.com/b/speschka/archive/2010/09/08/calling-a-claims-aware-wcf-service-from-a-sharepoint-2010-claims-site.aspx.
Maintenant que le code est terminé, vous devez veiller à inscrire la classe de base et votre nouveau contrôle personnalisé dans le Global Assembly Cache de chaque serveur où il sera utilisé. Pour ce faire, le plus simple est d’utiliser une solution SharePoint. Le contrôle étant terminé et inscrit, voyons comment l’utiliser pour récupérer des données et effectuer leur rendu. Dans le Kit CASI, j’ai essayé de traiter trois scénarios principaux relatifs à l’utilisation de données Azure :
1. Rendu de contenu dans une page SharePoint à l’aide d’un composant WebPart
2. Récupération des données de configuration à utiliser par un ou plusieurs contrôles et stockage de ces données dans le cache ASP.NET
3. Récupération de données et utilisation de ces dernières dans des exécutables de type tâche, par exemple un travail du minuteur SharePoint
Le premier scénario est probablement le plus répandu, c’est pourquoi nous allons l’aborder en premier. Le plus simple, une fois cette méthodologie mappée, serait de créer un composant WebPart personnalisé qui effectue tous ces appels durant un événement Load ou quelque chose d’approchant, puis de récupérer les données et d’effectuer leur rendu sur la page. Cependant, il s’agit pour moi d’une MONUMENTALE erreur. Si ce code est inclus dans le composant WebPart proprement dit, de sorte qu’il s’exécute côté serveur durant le traitement d’une demande de page, cela peut considérablement limiter l’ensemble du débit de la batterie de serveurs. Je ne suis pas du tout favorable à l’idée d’avoir un ou plusieurs composants WebPart sur une page, qui effectuent un ou plusieurs appels latents parmi les applications et les centres de données afin de récupérer des données ; en effet, il est facile d’imaginer que dans un tel scénario, une utilisation intensive peut littéralement mettre à genou l’ensemble d’une batterie de serveurs. Toutefois, il est nécessaire que du code s’exécute sur le serveur, car cela permet de configurer le canal vers l’application WCF afin d’envoyer le jeton d’utilisateur avec la requête. Ma solution au problème comprend deux parties :
1. Une page personnalisée hébergée dans le dossier _layouts. Elle contient le contrôle personnalisé que nous venons d’écrire ci-dessus et effectue le rendu des données renvoyées à partir de l’appel WCF.
2. Un composant WebPart personnalisé qui n’exécute AUCUN CODE côté serveur, mais qui utilise à la place les langages JavaScript et jQuery pour appeler la page dans le dossier _layouts. Il lit les données renvoyées à partir de la page, puis les transmet à une fonction JavaScript qui, par défaut, effectue simplement le rendu du contenu dans le composant WebPart. Naturellement, il est possible de faire bien plus de choses dans le composant WebPart, mais j’en parlerai plus en détails dans le prochain article. En tout cas, l’essentiel est que lorsqu’un utilisateur demande la page, son traitement est effectué sans appels latents supplémentaires à l’application WCF. À la place, la page suit le pipeline de traitement et parvient directement dans le navigateur de l’utilisateur. Une fois la page entièrement chargée, un appel est effectué pour récupérer uniquement le contenu WCF.
Page de disposition
La page de disposition qui doit héberger votre contrôle personnalisé est très simple à écrire. J’ai tout fait dans le Bloc-notes en l’espace de cinq minutes. Ce sera même encore plus rapide pour vous, car je vais simplement copier et coller ici ma page de disposition, puis je vous montrerai ce que vous devez remplacer dans votre page.
<%@ Page Language="C#" AutoEventWireup="true" Inherits="Microsoft.SharePoint.WebControls.LayoutsPageBase,Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" MasterPageFile="~/_layouts/simple.master" %>
<%@ Assembly Name="Microsoft.SharePoint.ApplicationPages, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c"%>
<%@ Import Namespace="Microsoft.SharePoint.ApplicationPages" %>
<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="Utilities" Namespace="Microsoft.SharePoint.Utilities" Assembly="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Assembly Name="Microsoft.Web.CommandUI, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Assembly Name="AzureConnect, Version=1.0.0.0, Culture=neutral, PublicKeyToken=c0b51bd3d3b33212"%>
<%@ Register Tagprefix="AzWcf" Namespace="AzureWcfPage" Assembly="AzureWcfPage, Version=1.0.0.0, Culture=neutral, PublicKeyToken=f0ed63b2f4046026" %>
<asp:Content ID="Content1" ContentPlaceHolderId="PlaceHolderPageTitle" runat="server">
<SharePoint:EncodedLiteral ID="wcfConnectPageTitle" runat="server" text="Azure Wcf Connect Page" EncodeMethod='HtmlEncode'/>
</asp:Content>
<asp:Content ID="Content2" ContentPlaceHolderId="PlaceHolderPageTitleInTitleArea" runat="server">
<SharePoint:EncodedLiteral ID="wcfConnectPage" runat="server" text="Azure Wcf Connect Page" EncodeMethod='HtmlEncode'/>
</asp:Content>
<asp:Content ID="Content3" ContentPlaceHolderId="PlaceHolderSiteName" runat="server"/>
<asp:Content ID="Content4" ContentPlaceHolderId="PlaceHolderMain" runat="server">
<AzWcf:WcfDataControl runat="server" id="wcf" WcfUrl="https://azurewcf.vbtoys.com/Customers.svc" OutputType="Page" MethodName="GetAllCustomersHtml" />
</asp:Content>
Une fois de plus, l’implémentation de la page proprement dite est d’une simplicité enfantine. Vous devez absolument changer le nom fort de l’assembly pour votre contrôle personnalisé. Pour illustrer ma description, j’ai également mis en surbrillance quelques propriétés de la balise de contrôle proprement dite. Ces propriétés sont spécifiques à mon service WCF. Vous pouvez les modifier et, dans certains cas, les supprimer entièrement de votre implémentation. Les propriétés seront décrites de manière plus détaillée ci-après. Une fois la page de disposition créée, elle doit être envoyée dans le répertoire _layouts de chaque serveur frontal Web de votre batterie de serveurs SharePoint. À ce stade, elle peut être appelée à partir de n’importe quel site, dans n’importe quelle application Web prenant en charge les revendications au sein de votre batterie de serveurs SharePoint. Naturellement, ne vous attendez pas à ce qu’elle fonctionne dans un site d’authentification classique, par exemple l’Administration centrale. Une fois la page déployée, elle peut être utilisée par le composant WebPart du Kit CASI, dont la description fait l’objet de la quatrième partie de cette série.
Propriétés importantes
WcfConfig contient deux grandes catégories de propriétés : celles qui permettent de configurer le canal et la connexion à l’application WCF, et celles qui permettent de configurer l’utilisation du contrôle proprement dit.
Propriétés WCF
Comme indiqué précédemment, toutes les informations de configuration de l’application WCF contenues normalement dans le fichier web.config ont été encapsulées dans le contrôle WcfConfig. Toutefois, quasiment toutes ces propriétés sont exposées de manière à pouvoir être modifiées en fonction des besoins de votre implémentation. Il existe deux exceptions importantes : la version de sécurité du message, qui est toujours MessageSecurityVersion.WSSecurity11WSTrust13WSSecureConversation13WSSecurityPolicy12BasicSecurityProfile10, et le transport, qui est toujours HTTPS, et non HTTP. Le contrôle comporte un certain nombre de propriétés qui peuvent être éventuellement intéressantes à connaître dans le cadre de votre implémentation (néanmoins, en règle générale, vous n’avez pas besoin de les modifier).
En premier lieu, il existe cinq propriétés en lecture seule qui exposent les objets de configuration de niveau supérieur utilisés dans la configuration. Lorsque je parle de lecture seule, il faut comprendre que ce sont les objets eux-mêmes qui sont en lecture seule ; vous pouvez définir les propriétés individuelles si vous utilisez le contrôle par programmation. Ces propriétés sont les suivantes :
SecurityBindingElement SecurityBinding
BinaryMessageEncodingBindingElement BinaryMessage
HttpsTransportBindingElement SecureTransport
WS2007FederationHttpBinding FedBinding
EndpointAddress WcfEndpointAddress
Les autres propriétés peuvent toutes être configurées dans la balise de contrôle ajoutée à la page de disposition aspx. Pour ces propriétés, j’ai utilisé une convention d’affectation des noms qui, je l’espère, est suffisamment explicite pour les valeurs de propriétés composées. Par exemple, la propriété SecurityBinding a une propriété appelée LocalClient, qui a une propriété booléenne appelée CacheCookies. Pour rendre tout cela plus facile à comprendre et à utiliser, j’ai juste créé une propriété appelée SecurityBindingLocalClientCacheCookies. Vous remarquerez plusieurs propriétés construites de manière similaire. Cela vous aidera également à trouver la propriété adéquate si vous examinez le Kit de développement .NET Framework SDK et si vous vous demandez comment modifier certaines de ces valeurs de propriétés dans l’implémentation de la classe de base. Voici la liste complète des propriétés :
SecurityAlgorithmSuite SecurityBindingDefaultAlgorithmSuite
SecurityHeaderLayout SecurityBindingSecurityHeaderLayout
SecurityKeyEntropyMode SecurityBindingKeyEntropyMode
bool SecurityBindingIncludeTimestamp
bool SecurityBindingLocalClientCacheCookies
bool SecurityBindingLocalClientDetectReplays
int SecurityBindingLocalClientReplayCacheSize
int SecurityBindingLocalClientMaxClockSkew
int SecurityBindingLocalClientMaxCookieCachingTime
int SecurityBindingLocalClientReplayWindow
int SecurityBindingLocalClientSessionKeyRenewalInterval
int SecurityBindingLocalClientSessionKeyRolloverInterval
bool SecurityBindingLocalClientReconnectTransportOnFailure
int SecurityBindingLocalClientTimestampValidityDuration
int SecurityBindingLocalClientCookieRenewalThresholdPercentage
bool SecurityBindingLocalServiceDetectReplays
int SecurityBindingLocalServiceIssuedCookieLifetime
int SecurityBindingLocalServiceMaxStatefulNegotiations
int SecurityBindingLocalServiceReplayCacheSize
int SecurityBindingLocalServiceMaxClockSkew
int SecurityBindingLocalServiceNegotiationTimeout
int SecurityBindingLocalServiceReplayWindow
int SecurityBindingLocalServiceInactivityTimeout
int SecurityBindingLocalServiceSessionKeyRenewalInterval
int SecurityBindingLocalServiceSessionKeyRolloverInterval
bool SecurityBindingLocalServiceReconnectTransportOnFailure
int SecurityBindingLocalServiceMaxPendingSessions
int SecurityBindingLocalServiceMaxCachedCookies
int SecurityBindingLocalServiceTimestampValidityDuration
int BinaryMessageMaxReadPoolSize
int BinaryMessageMaxWritePoolSize
int BinaryMessageMaxSessionSize
int BinaryMessageReaderQuotasMaxDepth
int BinaryMessageReaderQuotasMaxStringContentLength
int BinaryMessageReaderQuotasMaxArrayLength
int BinaryMessageReaderQuotasMaxBytesPerRead
int BinaryMessageReaderQuotasMaxNameTableCharCount
System.Net.AuthenticationSchemes SecureTransportAuthenticationScheme
System.ServiceModel.HostNameComparisonMode SecureTransportHostNameComparisonMode
System.Net.AuthenticationSchemes SecureTransportProxyAuthenticationScheme
System.ServiceModel.TransferMode SecureTransportTransferMode
bool SecureTransportManualAddressing
long SecureTransportMaxBufferPoolSize
long SecureTransportMaxReceivedMessageSize
bool SecureTransportAllowCookies
bool SecureTransportBypassProxyOnLocal
bool SecureTransportKeepAliveEnabled
int SecureTransportMaxBufferSize
string SecureTransportRealm
bool SecureTransportUnsafeConnectionNtlmAuthentication
bool SecureTransportUseDefaultWebProxy
bool SecureTransportRequireClientCertificate
HostNameComparisonMode FedBindingHostNameComparisonMode
WSMessageEncoding FedBindingMessageEncoding
Encoding FedBindingTextEncoding
SecurityAlgorithmSuite FedBindingSecurityMessageAlgorithmSuite
SecurityKeyType FedBindingSecurityMessageIssuedKeyType
bool FedBindingSecurityMessageNegotiateServiceCredential
int FedBindingCloseTimeout
int FedBindingOpenTimeout
int FedBindingReceiveTimeout
int FedBindingSendTimeout
bool FedBindingBypassProxyOnLocal
bool FedBindingTransactionFlow
long FedBindingMaxBufferPoolSize
long FedBindingMaxReceivedMessageSize
bool FedBindingUseDefaultWebProxy
int FedBindingReaderQuotasMaxDepth
int FedBindingReaderQuotasMaxStringContentLength
int FedBindingReaderQuotasMaxArrayLength
int FedBindingReaderQuotasMaxBytesPerRead
int FedBindingReaderQuotasMaxNameTableCharCount
bool FedBindingReliableSessionOrdered
int FedBindingReliableSessionInactivityTimeout
bool FedBindingReliableSessionEnabled
Là encore, ces propriétés ont toutes été créées de manière à pouvoir être modifiées directement dans la balise de contrôle de la page de disposition aspx. Par exemple, voici comment définir la propriété FedBindingUseDefaultWebProxy :
<AzWcf:WcfDataControl runat="server" id="wcf" WcfUrl="https://azurewcf.vbtoys.com/Customers.svc" OutputType="Page" MethodName="GetAllCustomersHtml" FedBindingUseDefaultWebProxy="true" />
Propriétés d’utilisation
Les autres propriétés du contrôle sont conçues pour encadrer son utilisation. Bien que la liste des propriétés soit plutôt longue, notez que cela accroît la souplesse de leur utilisation ; dans le cas de figure le plus simple, vous n’avez qu’une ou deux propriétés à définir. Autrement, vous pouvez définir ces dernières dans le composant WebPart décrit dans la quatrième partie de cette série. Voici une liste de chaque propriété avec une courte description.
string WcfUrl : URL du point de terminaison de service WCF, par exemple https://azurewcf.vbtoys.com/Customers.svc.
string MethodName : nom de la méthode qui doit être appelée lorsque la page est demandée. Vous pouvez affecter la méthode appelée par défaut à cette propriété. En outre, vous pouvez également affecter la valeur false à la propriété AllowQueryStringOverride, ce qui oblige la page à utiliser UNIQUEMENT la propriété MethodName définie dans la balise de contrôle. Cette propriété peut être définie via une chaîne de requête à l’aide du composant WebPart du Kit CASI.
string MethodParams : liste de valeurs de paramètre séparées par des points-virgules et qui doivent être passées à l’appel de méthode. Elles doivent être dans le même ordre que dans la signature de méthode. Comme indiqué dans la deuxième partie de la série de ce blog, les valeurs de paramètre ne prennent en charge que les types de données simples, par exemple string, bool, int et datetime. Si vous souhaitez passer davantage d’objets complexes en tant que paramètres de méthode, vous devez définir votre paramètre en tant que chaîne, puis désérialiser votre objet en XML avant d’appeler la méthode. Dans votre application WCF, vous pouvez ensuite resérialiser la chaîne en instance d’objet. Toutefois, si vous optez pour le passage en tant que paramètre de chaîne de requête, vous êtes limité par la longueur maximale de chaîne de requête prise en charge par votre navigateur et IIS. Cette propriété peut être définie via une chaîne de requête à l’aide du composant WebPart du Kit CASI.
object WcfClientProxy : sert en fait à effectuer l’appel à l’application WCF. Cette propriété doit être configurée pour prendre en charge le passage du jeton d’utilisateur avec l’appel, c’est la raison pour laquelle la dernière partie du code de configuration que vous écrivez dans votre contrôle personnalisé dans le cadre de la substitution d’ExecuteRequest doit affecter à cet objet proxy le proxy d’application de service créé et configuré pour utiliser les informations d’identification du client actuel.
string QueryResultsString : cette propriété contient une représentation sous forme de chaîne des résultats renvoyés à partir de l’appel de méthode. Si votre méthode WCF renvoie un type de données simple tel que bool, int, string ou datetime, la valeur de cette propriété correspond à la valeur renvoyée ToString(). Si votre méthode WCF renvoie une classe personnalisée correcte, lorsque la classe de base reçoit la valeur renvoyée, elle la désérialise en chaîne de sorte que vous disposiez d’une représentation XML des données.
object QueryResultsObject : cette propriété contient une représentation sous forme d’objet des résultats renvoyés à partir de l’appel de méthode. Elle est utile lorsque vous utilisez le contrôle par programmation. Par exemple, si vous utilisez le contrôle pour récupérer des données à stocker dans le cache ASP.NET, ou à utiliser dans un travail du minuteur SharePoint, la propriété QueryResultsObject possède exactement ce que l’appel de méthode WCF a renvoyé. S’il s’agit d’une classe personnalisée, il vous suffit d’effectuer une conversion de type (transtypage) des résultats de cette propriété vers le type de classe approprié pour pouvoir l’utiliser.
DataOutputType OutputType : la propriété OutputType est une énumération qui peut avoir l’une des quatre valeurs suivantes : Page, ServerCache, Both ou None. Si vous utilisez le contrôle dans la page de disposition et si vous effectuez le rendu des résultats avec le composant WebPart, OutputType doit avoir la valeur Page ou Both. Pour récupérer les données et les stocker dans le cache ASP.NET, utilisez ServerCache ou Both. REMARQUE : lors du stockage des résultats dans le cache, SEUL QueryResultsObject est stocké. Évidemment, Both effectue le rendu des données et stocke ces dernières dans le cache ASP.NET. Si vous utilisez simplement le contrôle par programmation dans un travail du minuteur SharePoint, par exemple, vous pouvez affecter la valeur None à cette propriété, car vous lisez uniquement QueryResultsString ou QueryResultsObject après l’appel de la méthode ExecuteRequest. Cette propriété peut être définie via une chaîne de requête à l’aide du composant WebPart du Kit CASI.
string ServerCacheName : si vous choisissez ServerCache ou Both pour OutputType, vous devez affecter une valeur de chaîne non vide à la propriété ServerCacheName, sinon une exception est levée. Ceci est la clé utilisée pour stocker les résultats dans le cache ASP.NET. Par exemple, si vous affectez « MyFooProperty » à la propriété ServerCacheName, après l’appel de la méthode ExecuteRequest, vous pouvez récupérer l’objet renvoyé à partir de l’application WCF en faisant référence à HttpContext.Current.Cache["MyFooProperty"]. Cette propriété peut être définie via une chaîne de requête à l’aide du composant WebPart du Kit CASI.
int ServerCacheTime : délai de conservation, en minutes, d’un élément ajouté au cache ASP.NET. Si vous affectez la valeur ServerCache ou Both à la propriété OutputType, vous devez également affecter une valeur différente de zéro à cette propriété, sinon une exception est levée. Cette propriété peut être définie via une chaîne de requête à l’aide du composant WebPart du Kit CASI.
bool DecodeResults : cette propriété est fournie au cas où votre application WCF renverrait des résultats HtmlEncoded. Si vous affectez la valeur true à cette propriété, HtmlDecoding est appliqué aux résultats. Dans la plupart des cas, cela n’est pas nécessaire. Cette propriété peut être définie via une chaîne de requête à l’aide du composant WebPart du Kit CASI.
string SharePointClaimsSiteUrl : cette propriété est fournie principalement pour les scénarios où vous devez créer le contrôle par programmation en dehors d’une requête HTTP, par exemple dans le cas d’un travail du minuteur SharePoint. Par défaut, lorsqu’une requête est effectuée via le composant WebPart, la classe de base utilise l’URL du site actuel pour se connecter au point de terminaison STS SharePoint afin de fournir le jeton d’utilisateur à l’appel WCF. Toutefois, si vous avez créé le contrôle par programmation et si vous n’avez aucun contexte HTTP, vous pouvez affecter à cette propriété l’URL d’un site SharePoint sécurisé prenant en charge les revendications, de sorte que le site soit utilisé pour l’accès au service STS SharePoint. Ainsi, par exemple, vous ne devez jamais avoir à définir cette propriété dans la balise de contrôle de la page de disposition, car vous disposez toujours d’un contexte HTTP lors de l’appel de cette page.
bool AllowQueryStringOverride : cette propriété permet aux administrateurs de verrouiller efficacement une balise de contrôle dans la page de disposition. Si AllowQueryStringOverride a la valeur false, les valeurs de substitution de chaîne de requête passées à partir du composant WebPart du Kit CASI sont ignorées.
string AccessDeniedMessage : il s’agit du message d’erreur relatif à un refus d’accès, qui doit s’afficher dans le composant WebPart du Kit CASI si l’accès est refusé à l’utilisateur pour une méthode particulière. Ainsi, comme indiqué dans la deuxième partie de cette série, si nous passons le jeton de l’utilisateur avec l’appel WCF, nous pouvons décorer les méthodes avec une demande PrincipalPermission, par exemple « Cet utilisateur doit faire partie du groupe des responsables des ventes ». Si un utilisateur ne répond pas aux exigences d’une demande PrincipalPermission, l’appel WCF échoue avec une erreur signalant un refus d’accès. Dans ce cas, le composant WebPart s’affiche, quel que soit AccessDeniedMessage. Notez que vous pouvez utiliser une mise en forme enrichie dans ce message, pour effectuer des actions telles que mettre des caractères en gras ou en rouge à l’aide de balises HTML (exemple : <font color='red'>Accès refusé : contactez votre administrateur</font>). Cette propriété peut être définie via une chaîne de requête à l’aide du composant WebPart du Kit CASI.
string TimeoutMessage : il s’agit du message qui s’affiche dans le composant WebPart du Kit CASI, si une erreur de délai d’attente se produit lors de la tentative d’exécution de l’appel de méthode WCF. Elle prend également en charge la mise en forme enrichie, par exemple la définition d’une police en caractères gras, en rouge, etc. Cette propriété peut être définie via une chaîne de requête à l’aide du composant WebPart du Kit CASI.
Il est vrai que cet article était LONG, mais il s’agit probablement de l’article le plus long de la série, car il contient la partie la plus significative de la description du Kit CASI. Dans le prochain article, je décrirai le composant WebPart inclus dans le Kit CASI pour effectuer le rendu des données de votre application WCF, à l’aide du contrôle personnalisé et de la page de disposition développés au cours de cette étape.
Vous trouverez en pièce jointe de cet article, un fichier zip qui contient l’exemple de projet Visual Studio 2010 que j’ai créé. Il inclut l’assembly de la classe de base du Kit CASI, mon contrôle personnalisé héritant de la classe de base du Kit CASI, ainsi que ma page de disposition personnalisée.
Ceci est une version localisée d’un article de blog. Vous trouverez la version originale sur The Claims, Azure and SharePoint Integration Toolkit Part 3