Exemplarische Vorgehensweise: Erstellen eines benutzerdefinierten ASP.NET-Webdiensts

Artikel
09/24/2014

Letzte Änderung: Mittwoch, 7. Juli 2010

Gilt für: SharePoint Foundation 2010

Inhalt dieses Artikels
Grundlegende Schritte für das Erstellen eines ASP.NET-Webdienstes
Erstellen eines ASP.NET-Webdienstes in Visual Studio
Generieren und Ändern der statischen Discovery-Datei und der WSDL-Datei
Bereitstellen der Webdienstdateien im Verzeichnis "_vti_bin"
Auflisten des neuen Webdienstes in "spdisco.aspx"
Erstellen einer Windows-Anwendung zur Nutzung des Webdienstes
Implementieren des SharePoint Foundation-Objektmodells

Diese Programmieraufgabe bietet einen Überblick über das Erstellen eines benutzerdefinierten Webdienstes, der im Kontext von Microsoft SharePoint Foundation ausgeführt wird. Sie werden schrittweise beim Erstellen eines einfachen "Hello World"-Webdienstes in Microsoft Visual Studio 2010 begleitet, und es wird Ihnen gezeigt, wie Sie den Dienst so ändern, dass er das serverseitige Objektmodell von SharePoint Foundation implementiert, um Website- und Listendaten zurückzugeben.

Wichtig
Benutzerdefinierte ASP.NET-Webdienste können in SharePoint Foundation 2010 zwar ausgeführt werden, doch wird empfohlen, anstelle dessen benutzerdefinierte WCF-Dienste zu erstellen. Weitere Informationen zu WCF-Diensten finden Sie unter WCF-Dienste in SharePoint Foundation 2010. Eine exemplarische Vorgehensweise, in der gezeigt wird, wie Sie einen benutzerdefinierten WCF-Dienst erstellen, finden Sie unter Exemplarische Vorgehensweise: Erstellen und Implementieren eines benutzerdefinierten WCF-Diensts in SharePoint Foundation.

Benutzerdefinierte ASP.NET-Webdienste können in SharePoint Foundation 2010 zwar ausgeführt werden, doch wird empfohlen, anstelle dessen benutzerdefinierte WCF-Dienste zu erstellen. Weitere Informationen zu WCF-Diensten finden Sie unter WCF-Dienste in SharePoint Foundation 2010. Eine exemplarische Vorgehensweise, in der gezeigt wird, wie Sie einen benutzerdefinierten WCF-Dienst erstellen, finden Sie unter Exemplarische Vorgehensweise: Erstellen und Implementieren eines benutzerdefinierten WCF-Diensts in SharePoint Foundation.

Grundlegende Schritte für das Erstellen eines ASP.NET-Webdienstes

Erstellen Sie einen Microsoft ASP.NET-Webdienst in Microsoft Visual Studio.
Generieren und bearbeiten Sie eine statische Discovery-Datei und eine WSDL-Datei (Web Services Description Language).
Stellen Sie die Webdienstdateien im Verzeichnis _vti_bin bereit.
Sorgen Sie dafür, dass der Webdienst sichtbar ist, indem Sie ihn in Spdisco.aspx auflisten.
Erstellen Sie eine Clientanwendung, die den Webdienst nutzt.
Erstellen Sie eine Klassenbibliothek innerhalb des Webdienstes, in der die Programmierlogik für den Webdienst definiert wird.

Erstellen eines ASP.NET-Webdienstes in Visual Studio

Der erste Schritt besteht darin, eine Microsoft ASP.NET-basierte Webdienstwebsite in Visual Studio zu erstellen.

So erstellen Sie einen ASP.NET-Webdienst

Klicken Sie in Visual Studio auf Datei, zeigen Sie auf Neu, und wählen Sie dann Website aus.
Wählen Sie im Dialogfeld Neue Website die Option .NET Framework 3.5 als Zielframework aus, wählen Sie unter Installierte Vorlagen entweder Visual Basic oder Visual C# als Programmiersprache aus, und wählen Sie die Vorlage ASP.NET-Webdienst aus. Wählen Sie im Feld Webspeicherort die Option Dateisystem aus, und geben Sie einen Speicherort für das Projekt an. Klicken Sie auf OK.
Erstellen Sie in der neuen Webdienstlösung ein getrenntes Klassenbibliotheksprojekt für die Webdienstlogik. Klicken Sie zum Erstellen des Projekts auf Datei, zeigen Sie auf Neu, und wählen Sie dann Projekt aus.
Erweitern Sie im Dialogfeld Neues Projekt unter Installierte Vorlagen entweder Visual Basic oder Visual C# aus, wählen Sie als Vorlage die Option Klassenbibliothek aus. Geben Sie einen Namen und einen Speicherort für das Projekt an, wählen Sie im Feld Lösung die Option Hinzufügen aus, und klicken Sie dann auf OK.
Fügen Sie einen Verweis auf den System.Web.Services-Namespace im Klassenbibliotheksprojekt hinzu. Klicken Sie mit der rechten Maustaste auf das Projekt im Projektmappen-Explorer, klicken Sie auf Verweis hinzufügen, wählen Sie auf der Registerkarte .NET des Dialogfelds Verweis hinzufügen die Option System.Web.Services aus, und klicken Sie dann auf OK.
Ersetzen Sie die Standardklassendatei im Klassenbibliotheksprojekt durch die Standarddienstklassendatei, die von Visual Studio im Ordner App_Code des Webdienstes bereitgestellt wird.

So ersetzen Sie die Klassendatei durch die Dienstklassendatei
1. Ziehen Sie im Projektmappen-Explorer die Datei Service.cs oder Service.vb auf den obersten Knoten des Klassenbibliotheksprojekts.
2. Löschen Sie die Datei Class1.cs oder Class1.vb sowie die Datei Service.cs oder Service.vb im Ordner App_Code.
Erstellen Sie einen starken Namen für die Klassenbibliothek:
1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Klassenbibliotheksprojekt, und klicken Sie dann auf Eigenschaften.
2. Klicken Sie im Dialogfeld Eigenschaften auf Signieren, wählen Sie Assembly signieren und anschließend in der Liste Schlüsseldatei mit starkem Namen auswählen die Option <Neu> aus.
3. Geben Sie im Dialogfeld Schlüssel mit starkem Namen erstellen einen Dateinamen für den Schlüssel ein, deaktivieren Sie das Kontrollkästchen Schlüsseldatei mit Kennwort schützen, und klicken Sie dann auf OK.
Klicken Sie mit der rechten Maustaste im Projektmappen-Explorer auf das Projekt und dann auf Erstellen , um nur das Klassenbibliotheksprojekt zu erstellen.
Zum Hinzufügen der Assembly zum globalen Assemblycache (Global Assembly Cache, GAC) können Sie entweder die Assembly in das Verzeichnis %windows%\assembly mithilfe zweier Instanzen von Windows-Explorer ziehen, oder das Befehlszeilenprogramm gacutil.exe verwenden, das zum Lieferumfang des Microsoft .NET Framework 2.0 Software Development Kit gehört.

So kopieren Sie die Klassenbibliotheks-DLL mithilfe von "gacutil.exe" in den globalen Assemblycache
1. Klicken Sie zum Öffnen der Eingabeaufforderung von Visual Studio auf Start , klicken Sie auf Programme, auf Microsoft Visual Studio 2010, auf Visual Studio Tools, klicken Sie mit der rechten Maustaste auf Visual Studio-Eingabeaufforderung (2010), und klicken Sie auf Als Administrator ausführen.
2. Geben Sie an der Eingabeaufforderung einen Befehl in folgender Form ein, und drücken Sie die EINGABETASTE.
  
  gacutil.exe -if "<Full file system path to DLL>".
Nun können Sie die Assemblyinformationen in der Standarddatei Service.asmx des Webdienstes mithilfe von Informationen zur DLL im globalen Assemblycache ändern. Zum Abrufen von Informationen aus dem globalen Assemblycache öffnen Sie das Verzeichnis %windows%\assembly in Windows-Explorer, klicken Sie mit der rechten Maustaste auf die Assembly und klicken Sie dann auf Eigenschaften.
Wenn Sie Service.asmx im Projektmappen-Explorer öffnen möchten, klicken Sie mit der rechten Maustaste auf die Datei und klicken Sie dann auf Öffnen.
Entfernen Sie das CodeBehind-Attribut aus der Seitendirektive in Service.asmx, und ändern Sie den Inhalt des Class-Attributs so, dass die Direktive das folgende Format aufweist (der Assemblyname "MyServiceAssembly" und das Token des öffentlichen Schlüssels sind Werte im Dialogfeld Eigenschaften, das Sie in Schritt 10 geöffnet haben).
```
<%@ WebService Language="C#" Class="Service, MyServiceAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8f2dca3c0f2d0131" %>
```
Schließen Sie in Visual Basic den Namespace zur Identifizierung der Klasse ein, wie z. B. Class="MyServiceNamespace.Service, MyServiceAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8f2dca3c0f2d0131".
Benennen Sie die ASMX-Datei entsprechend um, und speichern Sie Ihre Änderungen.

Generieren und Ändern der statischen Discovery-Datei und der WSDL-Datei

Damit dem benutzerdefinierten Dienst Funktionen wie die Ermittlung und Beschreibung zur Verfügung stehen, müssen Sie eine DISCO-Datei und eine WSDL-Datei erstellen. Da SharePoint Foundation die URLs virtualisiert (so wird http://MyServer/MySite/MySubsite beispielsweise zu http://MyServer), können Sie die von ASP.NET automatisch generierten DISCO- und WSDL-Dateien nicht verwenden. Anstelle dessen müssen Sie eine DISCO-Seite und eine ASPX-basierte WSDL-Seite für die notwendige Umleitung und die Virtualisierung erstellen.

Sie können die DISCO- und WSDL-Dateien mithilfe von ASP.NET generieren, indem Sie den Webdienst zeitweise in einem virtuellen Verzeichnis wie /_layouts hosten und anschließend das Webdienstermittlungstool (Disco.exe) von Microsoft .NET Framework zum Abrufen der generierten Dateien verwenden.

So generieren und bearbeiten Sie die statische Discovery-Datei und die WSDL-Datei

Kopieren Sie in Windows-Explorer die ASMX-Datei des Webdienstes in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\LAYOUTS.
Führen Sie Disco.exe an der Eingabeaufforderung über das Verzeichnis LAYOUTS aus, um die DISCO- und WSDL-Dateien zu generieren. Führen Sie einen Befehl im folgenden Format aus, um die Dateien in \LAYOUTS zu generieren:

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

Zum Registrieren der Namespaces des SharePoint Foundation-Objektmodells öffnen Sie sowohl die DISCO- als auch die WSDL-Datei, und ersetzen Sie die XML-Verarbeitungsanweisung am Anfang (<?xml version="1.0" encoding="utf-8"?>) durch Anweisungen wie die folgenden.

<%@ 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"; %>

Ändern Sie den Vertragsverweis und die SOAP-Adresstags in der DISCO-Datei so, dass sie dem folgenden Beispiel entsprechen. Dabei werden literale Pfade durch von Code generierte Pfade mithilfe der Microsoft.SharePoint.Utilities.SPHttpUtility-Klasse und der Name der im binding-Attribut angegebenen Methode ersetzt.

<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/" />

Nehmen Sie in der WSDL-Datei die folgende vergleichbare Ersetzung für die jeweilige SOAP-Adresse vor.

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

Benennen Sie beide Dateien in den jeweiligen Formaten um zu MyCustomWebServicedisco.aspx und MyCustomWebServicewsdl.aspx, so dass Ihr Dienst über SharePoint Foundation sichtbar ist.

Bereitstellen der Webdienstdateien im Verzeichnis "_vti_bin"

Das virtuelle Verzeichnis _vti_bin wird physikalisch dem Verzeichnis %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\ISAPI zugeordnet, das die in SharePoint Foundation verwendeten Standard-Webdienstdateien enthält. Kopieren Sie die neuen Dateien MyCustomWebServicewsdl.aspx und MyCustomWebServicedisco.aspx sowie die Datei MyCustomWebService.asmx in den ISAPI-Ordner.

Aus dem Verzeichnis _vti_bin heraus stellt ein Webdienst der Website seine Funktion zur Verfügung, die beim Hinzufügen eines Webverweises auf den Dienst angegeben wird.

Um sicherzustellen, dass der benutzerdefinierte Webdienst sichtbar ist, navigieren Sie zu http://MyServer/_vti_bin/MyCustomWebService.asmx.

Auflisten des neuen Webdienstes in "spdisco.aspx"

Wenn Sie Ihren Webdienst in Visual Studio zusammen mit den Standardwebdiensten von SharePoint Foundation als Webdienst sichtbar machen möchten, öffnen Sie die Datei spdisco.aspx, die sich im Verzeichnis %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\ISAPI befindet, und fügen Sie den folgenden Code hinzu. Geben Sie dabei die ASMX-Datei für Ihren Webdienst an.

<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/" />

Erstellen einer Windows-Anwendung zur Nutzung des Webdienstes

Nach dem Kopieren der Webdienstdateien in das Verzeichnis _vti_bin besteht der nächste Schritt darin, eine Windows-Anwendung zur Nutzung des Webdienstes zu erstellen.

So erstellen Sie eine Windows-Anwendung, die den Webdienst nutzt

Öffnen Sie Visual Studio, zeigen Sie im Menü Datei auf Neu, und klicken Sie dann auf Projekt.
Wählen Sie im Dialogfeld Neues Projekt die Option Visual C# oder Visual Basic aus, und wählen Sie dann die Vorlage Windows-Forms-Anwendung aus.
Geben Sie einen Namen für die Anwendung in das Feld Name ein, geben Sie einen Speicherort für die Projektdateien im Feld Speicherort an, und klicken Sie dann auf OK.
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und klicken Sie dann auf Dienstverweis hinzufügen.
Klicken Sie im Dialogfeld Dienstverweis hinzufügen auf Erweitert, und klicken Sie im Feld Dienstverweiseinstellungen auf Webverweis hinzufügen.
Geben Sie in der Adressleiste des Browsers Webverweis hinzufügen die URL der Website, auf die der Dienst angewendet werden soll, wie folgt ein:

https://Servername/[Websites/][Websitename/]_vti_bin/MyCustomWebService.asmx

Drücken Sie dann die EINGABETASTE.
Klicken Sie auf Verweis hinzufügen, um den Vertrag für den Webdienst herunterzuladen.
Öffnen Sie Form1 in der Entwurfsansicht, zeigen Sie die Toolbox an, und ziehen Sie dann eine Schaltfläche auf das Formular.

Doppelklicken Sie auf das Steuerelement Button1 in Form1, um die CodeBehind-Datei im Code-Editor anzuzeigen, und fügen Sie den folgenden Code hinzu, durch den die benutzerdefinierte Methode aufgerufen wird.

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());

Drücken Sie F5, um das Projekt zu kompilieren und auszuführen und um ein Meldungsfeld zu öffnen, in dem "Hello World" angezeigt wird.

Implementieren des SharePoint Foundation-Objektmodells

Jetzt können Sie Typen und Mitglieder des SharePoint Foundation-Objektmodells in der Klassenbibliothek des Webdienstes testen.

So implementieren Sie das SharePoint Foundation-Objektmodell

Fügen Sie einen Verweis auf die Microsoft.SharePoint-Assembly hinzu. Klicken Sie mit der rechten Maustaste auf das Klassenbibliotheksprojekt im Projektmappen-Explorer, klicken Sie auf Verweis hinzufügen, wählen Sie SharePoint Foundation aus, und klicken Sie dann auf OK.
In der Datei Service.cs oder Service.vb des Projekts müssen Sie die entsprechenden Namespaces in das Objektmodell importieren. Für die Verwendung von Typen und Mitgliedern der Namespaces Microsoft.SharePoint und Microsoft.SharePoint.Utilities fügen Sie beispielsweise die folgenden Direktiven hinzu.
```
Imports Microsoft.SharePoint
Imports Microsoft.SharePoint.Utilities
```
```
using Microsoft.SharePoint;
using Microsoft.SharePoint.Utilities;
```
Benennen Sie die Methode in Service.cs oder Service.vb um. Ändern Sie beispielsweise den Namen von "HelloWorld" zu "GetSiteListCount".

Fügen Sie den folgenden Code hinzu, um den Namen der Website und die Anzahl der enthaltenen Listen anzuzeigen.

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.");

Hinweis
Wenn SharePoint Foundation-Daten in irgendeiner Weise während einer HttpGet-Anforderung durch Ihren Code geändert werden, ist es möglicherweise erforderlich, unsichere Updates in der Website zuzulassen; legen Sie hierzu die AllowUnsafeUpdates-Eigenschaft fest.

Wenn Sie die Klassenbibliotheks-DLL neu erstellen und in den globalen Assemblycache kopieren möchten, wiederholen Sie die Schritte 8 und 9 unter "So erstellen Sie einen ASP.NET-Webdienst".
Setzen Sie die Internetinformationsdienste (Internet Information Services, IIS) zurück, damit die Änderungen in der DLL wirksam werden.
Wenn Sie neue Versionen der DISCO- und der WSDL-Datei erstellen möchten, wiederholen Sie die Schritte unter "So generieren und bearbeiten Sie die statische Discovery-Datei und die WSDL-Datei". Ändern Sie dabei jedoch den Namen der Methodenbindung in der DISCO-Datei entsprechend, wie z. B. GetSiteListCount.
Kopieren Sie die neuen Versionen der Dateien MyCustomWebServicedisco.aspx und MyCustomWebServicewsdl.aspx in den ISAPI-Ordner.
Öffnen Sie die zuvor erstellte Windows-Anwendung, löschen Sie den bestehenden Webdienstverweis auf das Beispiel "Hello World", ändern Sie den Methodennamen entsprechend, und fügen Sie einen neuen Webverweis auf den überarbeiteten Webdienst hinzu.
Drücken Sie F5, um das Projekt zu kompilieren und auszuführen und um ein Meldungsfeld aufzurufen, in dem der Name der Website und die Anzahl der enthaltenen Listen angezeigt werden.

Freigeben über