Kit de ressources CASI - Partie 4
Kit de ressources CASI - Partie 4
Ceci est la quatriè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. La partie 3 a décrit la classe de base qui permet de raccorder votre site SharePoint aux données Azure, via l’ajout d’un nouveau contrôle personnalisé à une page dans le répertoire _layouts. Dans cet article, je vais traiter du composant WebPart inclus dans le cadre de l’infrastructure. Il est conçu spécifiquement pour fonctionner avec le contrôle personnalisé que vous avez créé et ajouté dans la page de disposition au cours de la troisième partie.
Utilisation du composant WebPart
Avant de commencer à utiliser le composant WebPart, vous êtes censé a) disposer d’un service WCF fonctionnel hébergé dans Windows Azure, b) avoir créé un contrôle personnalisé et l’avoir ajouté à la page de disposition, comme indiqué dans la troisième partie de cette série d’articles. Vous êtes censé avoir déployé l’assembly de la classe de base du Kit CASI et votre assembly de contrôle personnalisé dans le GAC de chaque serveur de la batterie de serveurs SharePoint. Vous êtes également censé avoir déployé la page aspx personnalisée qui héberge votre contrôle personnalisé dans le répertoire _layouts de chaque serveur frontal Web de la batterie de serveurs. Pour décrire l’utilisation du composant WebPart, je vais recourir à l’exemple de projet AzureWcfPage que j’ai téléchargé et joint à l’article de la troisième partie de cette série. Voyons maintenant comment lier ces éléments afin de permettre le rendu de données à partir d’Azure dans un site SharePoint.
REMARQUE : bien que ce ne soit pas une obligation, il est généralement plus facile d’utiliser le composant WebPart si les méthodes WCF appelées renvoient un contenu HTML qui puisse être affiché directement dans la page sans traitement supplémentaire.
La première étape consiste à déployer la solution AzureRender.wsp dans la batterie de serveurs ; le fichier wsp est inclus dans le fichier zip joint à cet article. Il contient la fonctionnalité qui permet de déployer le composant WebPart DataView 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 composant WebPart à une page. À ce stade, vous êtes quasiment prêt à commencer le rendu de vos données à partir d’Azure ; toutefois, vous devez définir au minimum une propriété. Voyons à présent quelle est la propriété requise à définir, ainsi que les autres propriétés relatives au composant WebPart.
Propriétés du composant WebPart
Toutes les propriétés de composant WebPart se trouvent dans la section Propriétés de connexion. Au minimum, vous devez définir la propriété Data Page (Page d’accès aux données) en fonction de la page de disposition que vous avez créée et déployée. Par exemple, /_layouts/AzureData.aspx. Si la balise de serveur de votre contrôle personnalisé définit au minimum les propriétés WcfUrl et MethodName, vous n’avez rien de plus à faire. Si vous n’avez rien fait de plus, le composant WebPart appelle la page, puis utilise le point de terminaison et la méthode WCF configurés dans la page. Il récupère les données renvoyées par la méthode (au format HTML) et effectue leur rendu dans le composant WebPart. Cependant, dans la plupart des cas, vous pouvez utiliser d’autres propriétés de composant WebPart pour une flexibilité maximale. Voici un aperçu de chacune d’entre elles :
· Method Name (Nom de méthode)* – Nom de la méthode qui doit être appelée pour l’application WCF. Si vous devez appeler la page de disposition avec votre propre fonction JavaScript, le paramètre de chaîne de requête pour cette propriété est « methodname ».
· Parameter List (Liste de paramètres)* – 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 d’articles, 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 chaîne, appeler ensuite la méthode, puis le resérialiser en type complexe dans le point de terminaison WCF. Si vous devez appeler la page de disposition avec votre propre fonction JavaScript, le paramètre de chaîne de requête pour cette propriété est « methodparams ».
· Success Callback Address (Adresse de rappel en cas de succès) – Fonction JavaScript rappelée une fois que la requête jQuery pour la page de disposition s’est correctement effectuée. Par défaut, cette propriété utilise la fonction JavaScript incluse dans le composant WebPart. Si vous utilisez votre propre fonction, sa signature doit ressembler à ceci : function votreNomDeFonction(resultData, resultCode, queryObject). Pour plus d’informations, voir la documentation relative à jQuery AJAX sur https://api.jquery.com/jQuery.ajax/.
· Error Callback Address (Adresse de rappel en cas d’erreur) – Fonction JavaScript rappelée si la requête jQuery pour la page de disposition rencontre une erreur. Par défaut, cette propriété utilise la fonction JavaScript incluse dans le composant WebPart. Si vous utilisez votre propre fonction, sa signature doit ressembler à ceci : function votreNomDeFonction(XMLHttpRequest, textStatus, errorThrown). Pour plus d’informations, voir la documentation relative à jQuery AJAX sur https://api.jquery.com/jQuery.ajax/.
· Standard Error Message (Message d’erreur standard) – Message affiché dans le composant WebPart en cas d’erreur lors du traitement côté serveur du composant WebPart. Cela signifie que les scénarios où les données sont récupérées à partir d’Azure NE SONT PAS inclus.
· Access Denied Message (Message de refus d’accès)* – Message d’erreur relatif à un refus d’accès, qui doit s’afficher 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 le message de refus d’accès. 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>). Si vous devez appeler la page de disposition avec votre propre fonction JavaScript, le paramètre de chaîne de requête pour cette propriété est « accessdenied ».
· Timeout Message (Message d’expiration du délai d’attente)* – Message qui s’affiche 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. Si vous devez appeler la page de disposition avec votre propre fonction JavaScript, le paramètre de chaîne de requête pour cette propriété est « timeout ».
· Show Refresh Link (Afficher le lien d’actualisation) – Activez cette case à cocher pour effectuer le rendu d’une icône d’actualisation au-dessus des résultats de données Azure. Si un utilisateur clique sur l’icône, la méthode WCF est réexécutée afin d’obtenir la dernière version des données.
· Refresh Style (Style d’actualisation) – 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 pouvez ajouter « float:right; » à l’aide de cette propriété pour aligner à droite l’image d’actualisation.
· Cache Results (Mettre en cache les résultats) – Activez cette case à cocher pour que la bibliothèque jQuery mette en cache les résultats de la requête. Cela signifie que chaque fois que la page sera chargée, une version mise en cache des résultats de la requête sera utilisée. Cela évite des allers-retours vers Azure et se traduit par de meilleures performances pour l’utilisateur final. Si les données récupérées ne changent pas fréquemment, la mise en cache des résultats est un bon choix.
· Decode Results (Décoder les résultats)* – Activez cette case à cocher 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. Si vous devez appeler la page de disposition avec votre propre fonction JavaScript, le paramètre de chaîne de requête pour cette propriété est « encode ».
* – Ces propriétés sont ignorées si la propriété AllowQueryStringOverride du contrôle personnalisé a la valeur false.
Cas d’utilisation classiques
En supposant que votre méthode WCF renvoie du contenu HTML, dans la plupart des cas, vous voudrez ajouter le composant WebPart à une page et définir deux ou trois propriétés : Data Page (Page d’accès aux données), Method Name (Nom de méthode) et éventuellement Parameter List (Liste de paramètres).
Si vous avez des besoins plus complexes en matière d’affichage ou de traitement des données renvoyées par Azure, vous pouvez recourir à une fonction JavaScript personnalisée. Dans ce cas, ajoutez votre code JavaScript à la page et affectez le nom de votre fonction JavaScript à la propriété Success Callback Address (Adresse de rappel en cas de succès). Si votre composant requiert des publications supplémentaires dans l’application WCF, par exemple en matière d’ajouts, de mises à jour ou de suppressions, incluez-le dans vos propres fonctions JavaScript et appelez la page de disposition 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 en jQuery pour l’appel de la page de disposition, vous devez être en mesure d’adopter une approche similaire à celle du composant WebPart. La convention d’appel utilisée est basée sur la fonction de script ci-dessous ; notez que vous voudrez probablement continuer à utiliser la propriété dataFilter indiquée, car elle élimine tout ce qui dans la page ne provient PAS de la méthode WCF :
$.ajax({
type: "GET",
url: "/_layouts/SomePage.aspx",
dataType: "text",
data: "methodname=GetCustomerByEmail&methodparams=steve@contoso.local",
dataFilter: AZUREWCF_azureFilterResults,
success: yourSuccessCallback,
error: yourErrorCallback
});
Essayez !
À présent, vous disposez normalement de tous les éléments nécessaires pour tester la solution de bout en bout. Vous trouverez en pièce jointe de cet article un fichier zip qui comprend la solution du composant WebPart. Dans le prochain et dernier article de cette série, j’explique comment vous pouvez également vous servir du contrôle personnalisé développé lors de la deuxième partie pour récupérer des données en provenance d’Azure et les utiliser dans le cache ASP.NET avec d’autres contrôles. Par ailleurs, j’explique comment utiliser ce contrôle personnalisé dans des tâches SharePoint (par exemple dans un travail du minuteur SharePoint personnalisé).
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 4