Traduction

Cet article est la traduction la plus fidèle possible de l'article original de Steve Peschka, The Claims, Azure and SharePoint Integration Toolkit Part 4.

Introduction

Ceci est la quatrième partie d'une série en six parties sur le CASI (Claims, Azure and SharePoint Integration) Kit.

  • Partie 1 : une introduction présentant une vue d'ensemble de l'intégralité du « framework » et de la solution, et qui décrit ce que la série va tâcher de couvrir.
  • Partie 2 : la partie « instructions et lignes directrices » du CASI Kit. Cela commence par faire de WCF le « frontend » pour toutes vos données - cela pourrait être des jeux de données, du XML, des classes personnalisées ou tout simplement de l'HTML. Dans la première phase, nous prenons votre service WCF standard et en faisons un service prenant en charge les revendications - c'est ce qui nous permet de prendre le jeton d'utilisateur de SharePoint et de le transmettre, indépendamment des limites des applications ou des centres de données, vers nos applications WCF personnalisées. Dans la deuxième phase, j'éplucherai la liste de toutes les choses à effectuer pour faire passer cette application WCF classique de « hébergée en local » à « hébergée dans Windows Azure ». Une fois cela terminé, vous aurez le « backend » en place pour assurer une prise en charge multi-applications, multi-centres de données avec l'authentification intégrée.
  • Partie 3 : décrit l'assembly de la trousse d'outils personnalisé qui fournit « le ciment » pour connecter votre application WCF prenant en charge les revendications dans le cloud et votre ferme SharePoint. J'expliquerai comment utiliser cet assembly, je parlerai du contrôle personnalisé plutôt simple que vous devez créer (environ 5 lignes de code) et comment vous pouvez l'héberger dans une page du répertoire « _layouts » comme moyen de récupérer et d'effectuer le rendu des données dans un web part. L'intégralité du code source de l'exemple de contrôle personnalisé et de la page « _layouts » sera également publiée.
  • Partie 4 : le web part que j'inclus dans le CASI Kit. Il fournit une solution sans code, prête à l'emploi, qui vous permet de vous raccorder et de vous connecter à une requête asynchrone côté client pour récupérer des données à partir de votre service hébergé dans le cloud, et de les afficher ensuite dans le web part. Il dispose également « d'accroches » intégrées afin que vous puissiez le personnaliser un peu et utiliser vos propres fonctions JavaScript pour effectuer le rendu des données.
  • Partie 5 : un bref examen de quelques exemples d'applications qui illustrent quelques autres scénarios pour utiliser le contrôle personnalisé que vous avez construit dans la troisième partie dans d'autres cas de figures communs. L'un de ces scénarios utilisera le contrôle pour récupérer une sorte de données utilisateur ou de données de configuration et les stocker dans le cache ASP.NET, puis les utiliser dans un web part personnalisé. L'autre scénario utilisera le contrôle personnalisé pour récupérer des données d'Azure et de les utiliser dans une tâche personnalisée ; dans le cas présent, un travail du minuteur SharePoint personnalisé. L'intégralité du code source de ces exemples d'applications sera également publiée.
  • Partie 6 : article complémentaire contenant quelques conseils sur l'utilisation de SQL Azure afin que vous puissiez l'intégrer facilement et rapidement dans vos projets de développement SharePoint 2010 avec Windows Azure.

Le CASI Kit : Partie 4 - Le web part

La première partie de cette série présentait une vue d'ensemble de l'intégralité du « framework » et de la solution, et décrivait les objectifs de chacun des articles de la série. Dans la deuxième partie de la série nous avons vu comment créer et utiliser une application WCF personnalisée comme « frontend » pour vos données et du contenu, comment faire pour rendre cette application WCF capable de prendre en charge les revendications, et finalement comment la modifier pour la transférer vers et l'intégrer à Windows Azure. Dans la troisième partie de la série, nous avons abordé l'un des livrables les plus importants du « framework », la classe de base de contrôle personnalisé que vous avez utilisée pour connecter votre site SharePoint à votre application WCF hébergée dans Windows Azure. Nous avons vu les éléments suivants : ce qu'est la classe de base et comment l'utiliser dans votre projet, comment ajouter un nouveau contrôle personnalisé à une page dans le répertoire « _layouts », et quelques-unes des propriétés importantes à connaître dans la classe de base.

Dans cet article, j'aborderai le web part inclus dans le cadre de ce « framework ». Il est conçu spécifiquement pour fonctionner avec le contrôle personnalisé que vous avez créé et ajouté dans la page de dispositions dans la troisième partie.

Utilisation du web part

Avant de commencer à utiliser le web part, il est évidemment présumé que vous a) disposez d'un service WCF fonctionnel hébergé dans Windows Azure, b) avez créé un contrôle personnalisé et l'avez ajouté à la page de dispositions, comme indiqué dans la troisième partie de cette série d'articles. Je vais, par ailleurs, présumé que vous avez déployé l'assembly de la classe de base du CASI Kit et votre assembly du contrôle personnalisé dans le GAC de chaque serveur de la ferme SharePoint. Je vais également présumé que la page aspx personnalisée qui héberge votre contrôle personnalisé a été déployée dans le répertoire « _layouts » de chaque serveur « frontend » Web de la ferme. Pour décrire comment utiliser le web part, je vais utiliser l'exemple de projet AzureWcfPage que j'ai téléchargé et joint à l'article de la troisième partie. Voyons maintenant comment vous lieriez ces deux éléments ensemble afin de pouvoir effectuer le rendu de données à partir d'Azure dans un site SharePoint.

Bien qu'il ne s'agisse pas d'une exigence, il sera typiquement plus facile d'utiliser le web part si les méthodes WCF étant appelées renvoient du HTML de sorte qu'il puisse être affiché directement dans la page sans traitement supplémentaire.

La première étape consiste à déployer la solution AzureRender.wsp dans la ferme ; le fichier wsp est inclus dans le fichier compressé joint à cet article. Il contient la fonctionnalité qui permet de déployer le DataView WebPart d'Azure, ainsi que jQuery 1.4.2, dans le répertoire « _layouts ». Une fois la solution déployée et la fonctionnalité activée pour une collection de sites, vous pouvez ajouter le web part à une page. À ce stade, vous êtes quasiment prêt à commencer le rendu de vos données à partir d'Azure, mais il y au minimum une propriété que vous devez définir. Voyons à présent quelle est cette propriété qui doit être définie, ainsi que les autres propriétés relatives au web part.

Propriétés du web part

Toutes les propriétés du web part se trouvent dans la section « Propriétés de connexion ». Au minimum, vous devez définir la propriété Data Page à la page de dispositions que vous avez créée et déployée, par exemple, /_layouts/AzureData.aspx. Si la balise de serveur de votre contrôle personnalisé a défini au minimum les propriétés WcfUrl et MethodName, alors c'est tout ce que vous avez à faire. Si vous n'avez rien fait de plus, le web part appellerait la page et utiliserait le point de terminaison WCF et la méthode configurés dans la page, et il récupérerait toutes les données renvoyées par la méthode (apparemment il les renvoie au format HTML) et effectuerait leur rendu dans le web part. Cependant, dans la plupart des cas, vous allez vouloir utiliser quelques-unes des autres propriétés du web part pour une flexibilité maximale, voici donc un aperçu de chacune d'entre elles :

  • Method Name* - le nom de la méthode qui doit être appelée pour l'application WCF. Si vous devez appeler la page de dispositions avec votre propre fonction JavaScript, le paramètre de chaîne de requête pour cette propriété est « methodname ».
  • Parameter List* - la liste de paramètres séparés par des points-virgules pour la méthode WCF. Comme indiqué dans la deuxième et la troisième partie de cette série, seuls les types de données de base sont pris en charge : string, int, bool, long et datetime. Si vous avez besoin d'un type de données plus complexe, vous devez d'abord le dé-sérialiser en une chaîne, appeler ensuite la méthode, puis le ré-sérialiser en type complexe dans le point de terminaison WCF. Si vous devez appeler la page de dispositions avec votre propre fonction JavaScript, le paramètre de chaîne de requête pour cette propriété est « methodparams ».
  • Success Callback Address - la fonction JavaScript qui est rappelée une fois que la requête jQuery pour la page de dispositions se termine avec succès. Par défaut, cette propriété utilise la fonction JavaScript qui est incluse dans le web part. Si vous utilisez votre propre fonction, sa signature devrait ressembler à ceci : function yourFunctionName(resultData, resultCode, queryObject). Pour plus de détails, voir la documentation sur jQuery AJAX à l'adresse http://api.jquery.com/jQuery.ajax/.
  • Error Callback Address - la fonction JavaScript qui est rappelée si la requête jQuery pour la page de dispositions rencontre une erreur. Par défaut, cette propriété utilise la fonction JavaScript qui est incluse dans le web part. Si vous utilisez votre propre fonction, sa signature devrait ressembler à ceci : function yourFunctionName(XMLHttpRequest, textStatus, errorThrown). Pour plus de détails, voir la documentation sur jQuery AJAX à l'adresse http://api.jquery.com/jQuery.ajax/.
  • Standard Error Message - le message qui sera affiché dans le web part en cas d'erreur lors du traitement côté serveur du web part. Cela signifie qu'il n'inclut pas les scénarios où les données sont récupérées à partir d'Azure.
  • Access Denied Message* - le message d'erreur de type « Access Denied », qui devrait s'afficher si l'accès est refusé à l'utilisateur pour une méthode particulière. Par exemple, comme expliqué dans la deuxième partie de cette série, puisque nous passons le jeton de l'utilisateur avec l'appel WCF, nous pouvons « décorer » toutes les méthodes avec une demande PrincipalPermission, telle que « cet utilisateur doit faire partie du groupe des responsables des ventes ». Si un utilisateur ne correspond pas à une demande PrincipalPermission, alors l'appel WCF échouera avec une erreur de refus d'accès. Dans ce cas, le web part affichera, quel que soit sera le message de refus d'accès. Notez que vous pouvez utiliser la mise en forme enrichie dans ce message, pour effectuer des choses telles que définir la police en gras ou en rouge en utilisant des balises HTML (c'est-à-dire : <font color='red'>Accès refusé : veuillez contacter votre administrateur</font>). Si vous devez appeler la page de dispositions avec votre propre fonction JavaScript, le paramètre de chaîne de requête pour cette propriété est « accessdenied ».
  • Timeout Message* - c'est le message qui sera affiché s'il y a une erreur de délai d'attente lors de la tentative d'exécution de l'appel de méthode WCF. Elle prend également en charge la mise en forme enrichie, comme la définition d'une police en gras, en rouge, etc. Si vous devez appeler la page de dispositions avec votre propre fonction JavaScript, le paramètre de chaîne de requête pour cette propriété est « timeout ».
  • Show Refresh Link - cochez cette case pour effectuer le rendu d'une icône d'actualisation au-dessus des résultats de données Azure. Si l'icône est cliquée, la méthode WCF sera ré-exécutée afin d'obtenir la dernière version des données.
  • Refresh Style - vous permet d'ajouter des attributs de style supplémentaires à l'attribut principal Style de la balise IMG utilisée pour afficher le lien d'actualisation. Par exemple, vous pourriez ajouter « float:right; » à l'aide de cette propriété pour avoir l'image d'actualisation alignée sur la droite.
  • Cache Results - cochez cette case pour que la bibliothèque jQuery mette en cache les résultats de la requête. Cela signifie que chaque fois que la page se chargera, elle utilisera une version mise en cache des résultats de la requête. Cela évitera des allers-retours vers Azure et se traduit par de meilleures performances pour les utilisateurs finals. Si les données qu'il est en train de récupérer ne changent pas fréquemment, alors la mise en cache des résultats est une bonne option.
  • Decode Results* - cochez cette case au cas où votre application WCF renverrait des résultats HtmlEncoded. Si vous affectez la valeur true à cette propriété, alors HtmlDecoding sera appliqué aux résultats. Dans la plupart des cas, cela n'est pas nécessaire. Si vous devez appeler la page de dispositions avec votre propre fonction JavaScript, le paramètre de chaîne de requête pour cette propriété est « encode ».
  • Show Debug Information - cochez cette case pour que le web part sorte des informations de débogage avec les données afin d'aider à résoudre les problèmes. Notez que cela ne fera rien si la valeur false est affectée a la propriété ReturnDiagnosticsInformation du contrôle utilisateur.

* - ces propriétés seront ignorées si la propriété AllowQueryStringOverride du contrôle personnalisé a la valeur false.

Cas d'utilisation typique

En supposant que votre méthode WCF renvoie du HTML, dans la plupart des cas vous allez vouloir ajouter le web part à une page et définir deux ou trois propriétés : Data Page, Method Name et éventuellement Parameter List.

Si vous avez des exigences plus avancées en matière d'affichage ou de traitement pour les données qui sont renvoyées par Azure, vous pouvez alors recourir à une fonction JavaScript personnalisée afin de réaliser cela. Dans ce cas, vous devriez ajouter votre code JavaScript à la page et affecter le nom de votre fonction JavaScript à la propriété Success Callback Address. Si votre web part requiert des publications supplémentaires dans l'application WCF, pour des choses telles que des ajouts, des mises à jour ou des suppressions, vous devriez alors inclure cela dans vos propres fonctions JavaScript et appeler la page de dispositions personnalisée avec les valeurs appropriées pour Method Name et Parameter List ; les noms des variables de chaîne de requête à utiliser sont documentés ci-dessus. Lors de l'appel de la méthode ajax dans jQuery pour appeler la page de dispositions, vous devriez être en mesure d'utiliser une approche similaire à celle qu'utilise le web part. La convention d'appel qu'il utilise est basée sur la fonction de script ci-dessous ; notez que vous allez probablement vouloir continuer à utiliser la propriété dataFilter indiquée, car elle supprime toute sortie de page qui ne provient pas de la méthode WCF :

 
Sélectionnez
$.ajax({

type: "GET", 

       url: "/_layouts/SomePage.aspx",

dataType: "text",

data: "methodname=GetCustomerByEmail&methodparams=steve@contoso.local",

dataFilter: AZUREWCF_azureFilterResults,

success: yourSuccessCallback,

error: yourErrorCallback

});

Essayez-la !

À présent, vous devriez disposer normalement de tous les éléments pour tester la solution intégrale. Vous trouverez en pièce jointe de cet article un fichier compressé qui comprend la solution du web part.

Mise à jour du 03/06/2011 : La prise en charge pour héberger plusieurs web parts du CASI Kit dans une seule page a été ajoutée. Support was added for hosting multiple CASI Kit web parts on a single page. Cela exigeait une mise à niveau vers jQuery 1.5.1. Si vous souhaitez tirer profit de cette nouvelle fonctionnalité, il va falloir rétracter et redéployer le web part ; lorsque vous déployez cela va automatiquement copier jQuery 1.5.1 dans le répertoire « _ayouts ».

Conclusion

Dans cet article, nous avons abordé le web part inclus dans le cadre de ce « framework » et qui a été conçu spécifiquement pour fonctionner avec le contrôle personnalisé que vous avez précédemment créé et ajouté dans la page de dispositions.

Dans le prochain article de cette série, je vais décrire comment vous pouvez également utiliser le contrôle personnalisé développé dans la deuxième partie pour récupérer des données à partir d'Azure et les utiliser dans le cache ASP.NET avec d'autres contrôles, et aussi comment utiliser ce contrôle personnalisé dans des tâches SharePoint - dans le cas présent, un travail du minuteur SharePoint personnalisé.

Liens

Vous trouverez en pièce jointe de cet article, un fichier compressé qui contient la version Word de l'article en anglais et la solution du web part.

Le projet CASI Kit sur CodePlex : ici

Remerciements

Je tiens ici à remercier Steve Peschka de m'avoir autorisé à traduire son article.
Je remercie xyz pour sa relecture technique et ses propositions.
Je remercie également abc pour sa relecture orthographique et ses propositions.