Procédure pas à pas : création d’un service Web ASP.NET personnalisé

Article
09/24/2014

Dernière modification : mercredi 7 juillet 2010

S’applique à : SharePoint Foundation 2010

Dans cet article
Étapes de base pour la création d’un service Web ASP.NET
Création d’un service Web ASP.NET dans Visual Studio
Génération et modification des fichiers de découverte statique et WSDL
Déploiement des fichiers des services Web dans le répertoire _vti_bin
Listage du nouveau service Web dans spdisco.aspx
Création d’une application Windows pour utiliser le service Web
Implémentation du modèle objet SharePoint Foundation

Cette tâche de programmation fournit une vue d’ensemble de la création d’un service Web personnalisé qui fonctionne dans le contexte de Microsoft SharePoint Foundation. Elle décrit le processus de création d’un service Web « Hello World » simple dans Microsoft Visual Studio 2010, puis montre comment modifier le service de sorte qu’il implémente le modèle objet côté serveur SharePoint Foundation pour renvoyer les données de site et de liste.

Important

Les services Web ASP.NET personnalisés fonctionneront avec SharePoint Foundation 2010, mais il est plutôt recommandé de créer des services WCF personnalisés. Pour plus d’informations sur les services WCF, voir Services WCF dans SharePoint Foundation 2010. Pour obtenir une procédure pas à pas qui montre comment créer un service WCF personnalisé, voir Procédure pas à pas : création et implémentation d’un Service WCF personnalisé dans SharePoint Foundation.

Étapes de base pour la création d’un service Web ASP.NET

Créer un service Web Microsoft ASP.NET dans Microsoft Visual Studio.
Générer et modifier un fichier de découverte statique et un fichier WSDL (Web Services Description Language).
Déployer les fichiers du service Web dans le répertoire _vti_bin.
Rendre votre service Web détectable en le répertoriant dans Spdisco.aspx.
Créer une application cliente pour utiliser le service Web.
Créer une bibliothèque de classes dans le service Web, qui définit la logique de programmation du service Web.

Création d’un service Web ASP.NET dans Visual Studio

La première étape consiste à créer un site Web de service Web Microsoft ASP.NET dans Visual Studio.

Pour créer un service Web ASP.NET

Dans Visual Studio, cliquez sur Fichier, pointez sur Nouveau, puis sélectionnez Site Web.
Dans la boîte de dialogue Nouveau site Web, sélectionnez .NET Framework 3.5 comme framework cible, sélectionnez Visual Basic ou Visual C# comme langage de programmation, sous Modèles installés, sélectionnez le modèle Service Web ASP.NET, sélectionnez Système de fichiers dans la zone Emplacement Web, spécifiez un emplacement pour le projet, puis cliquez sur OK.
Dans la nouvelle solution de service Web, créez un projet de bibliothèque de classes distinct qui contiendra la logique du service Web. Pour créer le projet, cliquez sur Fichier, pointez sur Nouveau, puis sélectionnez Projet.
Dans la boîte de dialogue Nouveau projet, développez Visual Basic ou Visual C# sous Modèles installés, sélectionnezBibliothèque de classes comme modèle, indiquez un nom et un emplacement pour le projet, sélectionnez Ajouter à la solution dans la zone Solution, puis cliquez sur OK.
Ajoutez une référence à l’espace de noms System.Web.Services dans le projet Bibliothèque de classes. Cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions, cliquez sur Ajouter une référence, sélectionnez System.Web.Services sous l’onglet .NET de la boîte de dialogue Ajouter une référence, puis cliquez sur OK.
Remplacez le fichier de classe par défaut du projet de bibliothèque de classes par le fichier de classe de service par défaut que fournit Visual Studio dans le dossier App_Code du service Web.

Pour remplacer le fichier de classe par le fichier de classe de service
1. Dans l’Explorateur de solutions, faites glisser le fichier Service.cs ou Service.vb vers le nœud supérieur dans le projet de bibliothèque de classes.
2. Supprimez le fichier Class1.cs ou Class1.vb, ainsi que le fichier Service.cs ou Service.vb qui reste dans le dossier App_Code.
Créez un nom fort pour la bibliothèque de classes :
1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet Bibliothèque de classes, puis cliquez sur Propriétés.
2. Dans la boîte de dialogue Propriétés, cliquez sur Signature, sélectionnez Signer l’assembly, puis sélectionnez <Nouveau> dans la liste Choisir un fichier de clé de nom fort.
3. Dans la boîte de dialogue Créer une clé de nom fort, spécifiez un nom de fichier pour la clé, désactivez la case à cocher Protéger mon fichier de clé par un mot de passe, puis cliquez sur OK.
Pour générer uniquement le projet Bibliothèque de classes, cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions, puis cliquez sur Générer.
Pour ajouter votre assembly au Global Assembly Cache, vous pouvez soit faire glisser l’assembly dans le répertoire %windows%\assembly en utilisant deux instances de l’Explorateur Windows, soit recourir à gacutil.exe, l’utilitaire en ligne de commande installé avec le Kit de développement logiciel (SDK) Microsoft .NET Framework 2.0.

Pour utiliser gacutil.exe afin de copier la DLL de bibliothèque de classes dans le Global Assembly Cache
1. Pour ouvrir l’invite de commandes de Visual Studio, cliquez sur Démarrer, sur Tous les programmes, sur Microsoft Visual Studio 2010, sur Visual Studio Tools, cliquez avec le bouton droit sur Invite de commandes de Visual Studio (2010), puis cliquez sur Exécuter en tant qu’administrateur.
2. À l’invite de commandes, tapez une commande sous la forme suivante, puis appuyez sur Entrée :
  
  gacutil.exe -if "<Full file system path to DLL>".
À présent, vous êtes prêt à modifier les informations d’assembly dans le fichier Service.asmx par défaut du service Web à l’aide des informations relatives à la DLL que vous pouvez obtenir dans le Global Assembly Cache. Pour obtenir des informations du Global Assembly Cache, ouvrez le répertoire %windows%\assembly dans l’Explorateur Windows, cliquez avec le bouton droit sur votre assembly, puis cliquez sur Propriétés.
Pour ouvrir Service.asmx dans l’Explorateur de solutions, cliquez avec le bouton droit sur le fichier, puis cliquez sur Ouvrir.
Supprimez l’attribut CodeBehind de la directive de page dans Service.asmx, puis modifiez le contenu de l’attribut Class de sorte que la directive corresponde au format suivant, où le nom d’assembly « MyServiceAssembly » et le jeton de clé publique représentent les valeurs spécifiées dans la boîte de dialogue Propriétés que vous avez ouverte à l’étape 10.
```
<%@ WebService Language="C#" Class="Service, MyServiceAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8f2dca3c0f2d0131" %>
```
Dans Visual Basic, incluez l’espace de noms pour identifier la classe, par exemple, Class="MyServiceNamespace.Service, MyServiceAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8f2dca3c0f2d0131".
Renommez votre fichier .asmx de manière appropriée, puis enregistrez vos modifications.

Génération et modification des fichiers de découverte statique et WSDL

Pour rendre votre service Web personnalisé détectable et lui donner une description, vous devez créer un fichier .disco et un fichier .wsdl. Dans la mesure où SharePoint Foundation virtualise ses URL (par exemple http://MyServer/MySite/MySubsite devient http://MyServer), vous ne pouvez pas utiliser les fichiers .disco et .wsdl générés automatiquement par ASP.NET. À la place, vous devez créer une page .disco et une page ASPX .wsdl qui vont fournir la redirection nécessaire et gérer la virtualisation.

Vous pouvez utiliser ASP.NET pour générer les fichiers .disco et .wsdl en hébergeant temporairement votre service Web dans un répertoire virtuel, par exemple /_layouts, puis en utilisant l’outil Web Services Discovery Microsoft .NET Framework (Disco.exe) pour obtenir les fichiers générés.

Pour générer et modifier le fichier WSDL et le fichier de découverte statique

Dans l’Explorateur Windows, copiez le fichier .asmx de votre service Web dans %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\LAYOUTS.
Exécutez Disco.exe à l’invite de commandes à partir du répertoire LAYOUTS afin de générer les fichiers .disco et .wsdl. Exécutez une commande en respectant le format suivant afin de générer les fichiers dans \LAYOUTS :

disco http://MyServer/_layouts/MyCustomWebService.asmx

Pour inscrire les espaces de noms du modèle objet SharePoint Foundation, ouvrez les fichiers .disco et .wsdl, puis remplacez l’instruction de traitement XML ouvrante -- <?xml version="1.0" encoding="utf-8"?> -- par des instructions similaires à ce qui suit.

<%@ Page Language="C#" Inherits="System.Web.UI.Page" %> 
<%@ Assembly Name="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %> 
<%@ Import Namespace="Microsoft.SharePoint.Utilities" %> 
<%@ Import Namespace="Microsoft.SharePoint" %>
<% Response.ContentType = "text/xml"; %>

Dans le fichier .disco, modifiez la référence de contrat et les balises d’adresse SOAP en vous inspirant de l’exemple suivant, lequel remplace les chemins d’accès littéraux par les chemins d’accès générés par du code via l’utilisation de la classe Microsoft.SharePoint.Utilities.SPHttpUtility, et remplace le nom de méthode spécifié dans l’attribut binding.

<contractRef ref=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(SPWeb.OriginalBaseUrl(Request) + "?wsdl"),Response.Output); %> 
docRef=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(SPWeb.OriginalBaseUrl(Request)),Response.Output); %> 
xmlns="https://schemas.xmlsoap.org/disco/scl/" />
<soap address=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(SPWeb.OriginalBaseUrl(Request)),Response.Output); %> 
xmlns:q1="http://tempuri.org/" binding="q1:HelloWorld" xmlns="https://schemas.xmlsoap.org/disco/soap/" />
<soap address=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(SPWeb.OriginalBaseUrl(Request)),Response.Output); %> 
xmlns:q2="http://tempuri.org/" binding="q2:ServiceSoap12" xmlns="https://schemas.xmlsoap.org/disco/soap/" />

Dans le fichier .wsdl, effectuez la substitution similaire suivante pour l’adresse SOAP spécifiée.

<soap:address location=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(SPWeb.OriginalBaseUrl(Request)),Response.Output); %> />

Renommez les deux fichiers dans les formats respectifs MyCustomWebServicedisco.aspx et MyCustomWebServicewsdl.aspx de sorte que votre service soit détectable via SharePoint Foundation.

Déploiement des fichiers des services Web dans le répertoire _vti_bin

Le répertoire virtuel _vti_bin est mappé de manière physique au répertoire %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\ISAPI, qui contient les fichiers des services Web par défaut utilisés dans SharePoint Foundation. Copiez les nouveaux fichiers MyCustomWebServicewsdl.aspx et MyCustomWebServicedisco.aspx, ainsi que le fichier MyCustomWebService.asmx, dans le dossier ISAPI.

À partir du répertoire _vti_bin, un service Web offre ses fonctionnalités au site spécifié lors de l’ajout d’une référence Web pour le service.

Pour vous assurer que votre service Web personnalisé est détectable, accédez à http://MyServer/_vti_bin/MyCustomWebService.asmx.

Listage du nouveau service Web dans spdisco.aspx

Pour rendre votre service Web détectable en tant que tel dans Visual Studio au même titre que les services Web SharePoint Foundation par défaut, ouvrez le fichier spdisco.aspx situé dans %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\ISAPI, puis ajoutez le code suivant, en indiquant le fichier .asmx pour votre service Web.

<contractRef ref=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(spWeb.Url + "/_vti_bin/MyCustomWebService.asmx?wsdl"), Response.Output); %> 
docRef=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(spWeb.Url + "/_vti_bin/MyCustomWebService.asmx"), Response.Output); %> 
xmlns=" https://schemas.xmlsoap.org/disco/scl/ " />
<discoveryRef ref=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(spWeb.Url + "/_vti_bin/MyCustomWebService.asmx?disco"),Response.Output); %> 
xmlns="https://schemas.xmlsoap.org/disco/" />

Création d’une application Windows pour utiliser le service Web

Une fois que vous avez copié les fichiers des services Web dans le répertoire _vti_bin, l’étape suivante consiste à créer une application Windows pour utiliser le service Web.

Pour créer une application Windows qui utilise le service Web

Ouvrez Visual Studio, puis dans le menu Fichier, pointez sur Nouveau, puis cliquez sur Projet.
Dans la boîte de dialogue Nouveau projet, sélectionnez Visual C# ou Visual Basic, puis sélectionnez le modèle Application Windows Forms.
Tapez le nom de l’application dans la zone Nom, spécifiez l’emplacement des fichiers projet dans la zone Emplacement, puis cliquez sur OK.
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet, puis cliquez sur Ajouter une référence de service.
Dans la boîte de dialogue Ajouter une référence de service, cliquez sur Avancé, puis dans la zone Paramètres de référence de service, cliquez sur Ajouter une référence Web.
Dans la barre d’adresses du navigateur Ajouter une référence Web, tapez l’URL du site à appliquer au service, comme indiqué ci-dessous.

http://Nom_Serveur/[sites/][Nom_Site/]_vti_bin/MyCustomWebService.asmx

et appuyez ensuite sur Entrée.
Cliquez sur Ajouter une référence afin de télécharger le contrat de service pour le service Web.
Ouvrez Form1 en mode Création, affichez la Boîte à outils, puis faites glisser un bouton vers le formulaire.

Double-cliquez sur le contrôle Button1 dans Form1 pour afficher le fichier code-behind dans l’éditeur de code, puis ajoutez le code suivant pour appeler votre méthode personnalisée.

Dim MyCustomService As New Web_Reference_Folder.MyServiceClass()
MyCustomService.UseDefaultCredentials = True
MessageBox.Show(MyCustomService.HelloWorld())

Web_Reference_Folder.MyServiceClass MyCustomService = new Web_Reference_Folder.MyServiceClass();
MyCustomService.UseDefaultCredentials = true;
MessageBox.Show(MyCustomService.HelloWorld());

Appuyez sur F5 pour compiler et exécuter le projet, ce qui vous permet de voir une boîte de dialogue afficher « Hello World ».

Implémentation du modèle objet SharePoint Foundation

Vous êtes désormais prêt à essayer des types et des membres du modèle objet SharePoint Foundation dans la bibliothèque de classes de votre service Web.

Pour implémenter le modèle objet SharePoint Foundation

Ajoutez une référence à l’assembly Microsoft.SharePoint. Cliquez avec le bouton droit sur le projet de bibliothèque de classes dans l’Explorateur de solutions, cliquez sur Ajouter une référence, sélectionnez SharePoint Foundation, puis cliquez sur OK.
Dans votre fichier projet Service.cs ou Service.vb, vous devez importer les espaces de noms appropriés dans le modèle objet. Par exemple, pour utiliser les types et les membres des espaces de noms Microsoft.SharePoint et Microsoft.SharePoint.Utilities, ajoutez les directives suivantes.
```
Imports Microsoft.SharePoint
Imports Microsoft.SharePoint.Utilities
```
```
using Microsoft.SharePoint;
using Microsoft.SharePoint.Utilities;
```
Renommez la méthode dans Service.cs or Service.vb. Par exemple, remplacez le nom HelloWorld par GetSiteListCount.
Ajoutez le code suivant pour afficher le nom du site Web et le nombre de listes qu’il contient.
```
Dim myWebSite As SPWeb = SPContext.Current.Web
Dim lists As SPListCollection = myWebSite.Lists

Return myWebSite.Title + " contains " + lists.Count.ToString() + 
" lists."
```
```
SPWeb myWebSite = SPContext.Current.Web;
SPListCollection lists = myWebSite.Lists;

return (myWebSite.Title + " contains " + lists.Count.ToString() + 
" lists.");
```
Notes

Si votre code modifie des données SharePoint Foundation au cours d’une demande HttpGet, vous devrez peut-être autoriser les mises à jour non sécurisées sur le site Web. Pour ce faire, définissez la propriété AllowUnsafeUpdates.
Pour regénérer la DLL de bibliothèque de classes et la copier dans le Global Assembly Cache, répétez les étapes 8 et 9 décrites dans la section « Pour créer un service Web ASP.NET ».
Réinitialisez les services IIS (Internet Information Services) pour que les modifications de la DLL prennent effet.
Pour générer de nouvelles versions des fichiers .disco et .wsdl, répétez les étapes décrites dans la section « Pour générer le fichier WSDL et le fichier de découverte statique » tout en modifiant le nom de liaison de la méthode dans le fichier .disco de manière appropriée, par exemple en utilisant GetSiteListCount.
Copiez les nouvelles versions des fichiers MyCustomWebServicedisco.aspx et MyCustomWebServicewsdl.aspx dans le dossier ISAPI.
Ouvrez l’application Windows que vous avez créée précédemment, supprimez la référence au service Web précédente pour l’exemple Hello World, changez le nom de la méthode selon les besoins, puis ajoutez une nouvelle référence Web au service Web modifié.
Appuyez sur F5 pour compiler et exécuter le projet, ce qui entraîne l’affichage d’un message indiquant le nom du site Web et le nombre de listes qu’il contient.

Partager via