Gewusst wie: Verwenden des WebMethod-Attributs

Artikel
09/02/2008

Aktualisiert: November 2007

Wenn Sie das WebMethod-Attribut an eine Public-Methode anfügen, bedeutet dies, dass die Methode als Teil des XML-Webdiensts verfügbar gemacht werden soll. Sie können die Eigenschaften dieses Attributs auch verwenden, um das Verhalten der XML-Webdienstmethode weiter zu konfigurieren. Weitere Informationen finden Sie unter Codemodell für XML-Webdienste in verwaltetem Code.

Das WebMethod-Attribut bietet folgende Eigenschaften:

BufferResponse
CacheDuration
Beschreibung
EnableSession
MessageName
TransactionOption

BufferResponse

Die BufferResponse-Eigenschaft des WebMethod-Attributs aktiviert die Pufferung von Antworten für eine XML-Webdienstmethode. Wenn für diese die Standardeinstellung True festgelegt wurde, puffert ASP.NET die gesamte Antwort, bevor sie zum Client gesendet wird. Die Pufferung ist sehr effizient und hilft bei der Optimierung der Leistung, indem die Kommunikation zwischen dem Workerprozess und dem IIS-Prozess minimiert wird. Wenn für sie False festgelegt ist, puffert ASP.NET die Antwort in Blöcken mit 16 KB. In der Regel würden Sie für diese Eigenschaft nur dann False festlegen, wenn nicht der gesamte Inhalt der Antwort auf einmal in den Arbeitsspeicher geladen werden soll. Dies ist z. B. der Fall, wenn Sie eine Auflistung zurückschreiben, die ihre Elemente aus einer Datenbank abruft. Wenn nichts anderes angegeben wurde, ist der Standardwert True. Weitere Informationen finden Sie unter WebMethodAttribute.BufferResponse-Eigenschaft.

So puffern Sie die Antwort auf eine XML-Webdienstmethode

Verwenden Sie die BufferResponse-Eigenschaft des WebMethod-Attributs wie im Folgenden gezeigt:

Public Class Service1
    Inherits System.Web.Services.WebService
    <System.Web.Services.WebMethod(BufferResponse:=False)> _
    Public Function GetBigData() As DataSet
        'implementation code
    End Function
End Class

public class Service1 : System.Web.Services.WebService
{ 
    [System.Web.Services.WebMethod(BufferResponse=false)]
    public DataSet GetBigData()
    {
       //implementation code
    }
}

CacheDuration

Die CacheDuration-Eigenschaft des WebMethod-Attributs aktiviert das Zwischenspeichern der Ergebnisse für eine XML-Webdienstmethode. Die Ergebnisse für jede eindeutige Parametermenge werden von ASP.NET zwischengespeichert. Der Wert dieser Eigenschaft gibt die Anzahl der Sekunden an, für die die Ergebnisse von ASP.NET zwischengespeichert werden. Mit dem Wert 0 wird die Zwischenspeicherung von Ergebnissen deaktiviert. Wenn nichts anderes angegeben wurde, ist der Standardwert 0. Weitere Informationen finden Sie unter WebMethodAttribute.CacheDuration-Eigenschaft.

So aktivieren Sie das Zwischenspeichern der Ergebnisse einer XML-Webdienstmethode

Verwenden Sie die CacheDuration-Eigenschaft des WebMethod-Attributs wie im Folgenden gezeigt:

Public Class Service1
    Inherits System.Web.Services.WebService
    <System.Web.Services.WebMethod(CacheDuration:=60)> _
    Public Function ConvertTemperature(ByVal dFahrenheit As Double) _
                                       As Double
        ConvertTemperature = ((dFahrenheit - 32) * 5) / 9
    End Function
End Class

public class Service1 : System.Web.Services.WebService
{ 
    [System.Web.Services.WebMethod(CacheDuration=60)]
    public double ConvertTemperature(double dFahrenheit)
    {
       return ((dFahrenheit - 32) * 5) / 9;
    }
}

Beschreibung

Die Description-Eigenschaft des WebMethod-Attributs stellt eine Beschreibung für eine XML-Webdienstmethode bereit, die auf der Diensthilfeseite angezeigt wird. Wenn nichts anderes angegeben wurde, ist der Standardwert eine leere Zeichenfolge. Weitere Informationen finden Sie unter WebMethodAttribute.Description-Eigenschaft.

So stellen Sie eine Beschreibung für eine XML-Webdienstmethode bereit

Verwenden Sie die Description-Eigenschaft des WebMethod-Attributs wie im Folgenden gezeigt:

Public Class Service1
    Inherits System.Web.Services.WebService
    <System.Web.Services.WebMethod( _
       Description:="This method converts a temperature " & _
       "in degrees Fahrenheit to a temperature in degrees Celsius.")> _
    Public Function ConvertTemperature(ByVal dFahrenheit As Double) _
                                       As Double
        ConvertTemperature = ((dFahrenheit - 32) * 5) / 9
    End Function
End Class

public class Service1 : System.Web.Services.WebService
{ 
    [System.Web.Services.WebMethod(
       Description="Converts F to C a temperature in " +
       "degrees Fahrenheit to a temperature in degrees Celsius.")]
    public double ConvertTemperature(double dFahrenheit)
    {
       return ((dFahrenheit - 32) * 5) / 9;
    }
}

EnableSession

Die EnableSession-Eigenschaft des WebMethod-Attributs aktiviert den Sitzungszustand für eine XML-Webdienstmethode. Nach der Aktivierung kann der XML-Webdienst direkt aus HttpContext.Current.Session oder über die WebService.Session-Eigenschaft – sofern diese von der WebService-Basisklasse erbt – auf die Auflistung für den Sitzungszustand zugreifen. Wenn nichts anderes angegeben wurde, ist der Standardwert False. Weitere Informationen finden Sie unter WebMethodAttribute.EnableSession-Eigenschaft.

So aktivieren Sie den Sitzungszustand in einer XML-Webdienstmethode

Verwenden Sie die EnableSession-Eigenschaft des WebMethod-Attributs wie im Folgenden gezeigt:

Public Class Service1
    Inherits System.Web.Services.WebService
    <System.Web.Services.WebMethod(EnableSession:=True)> _
    Public Function ConvertTemperature(ByVal dFahrenheit As Double) _
                                       As Double
        Session("Conversions") = Session("Conversions") + 1
        ConvertTemperature = ((dFahrenheit - 32) * 5) / 9
    End Function
    <System.Web.Services.WebMethod(EnableSession:=True)> _
    Public Function GetNumberOfConversions() As Integer
        GetNumberOfConversions = Session("Conversions")
    End Function
End Class

public class Service1 : System.Web.Services.WebService
{ 
    [System.Web.Services.WebMethod(EnableSession=true)]
    public double ConvertTemperature(double dFahrenheit)
    {
       Session["Conversions"] = (int) Session["Conversions"] + 1;
       return ((dFahrenheit - 32) * 5) / 9;
    }
    [System.Web.Services.WebMethod(EnableSession=true)]
    public int GetNumberOfConversions()
    {
       return (int) Session["Conversions"];
    }
}

MessageName

Die MessageName-Eigenschaft des WebMethod-Attributs aktiviert den XML-Webdienst so, dass überladene Methoden mit einem Alias eindeutig gekennzeichnet werden. Wenn nichts anderes angegeben wurde, ist der Standardwert der Methodenname. Bei Angabe von MessageName geben die resultierenden SOAP-Nachrichten diesen Namen anstelle des tatsächlichen Methodennamens wider. Weitere Informationen finden Sie unter WebMethodAttribute.MessageName-Eigenschaft.

So stellen Sie einen Meldungsnamen für eine XML-Webdienstmethode bereit

Verwenden Sie die MessageName-Eigenschaft des WebMethod-Attributs wie im Folgenden gezeigt:

Public Class Service1
    Inherits System.Web.Services.WebService
    <System.Web.Services.WebMethod(MessageName:="AddDoubles")> _
    Public Function Add(ByVal dValueOne As Double, _
                        ByVal dValueTwo As Double) As Double
        Add = dValueOne + dValueTwo
    End Function
    <System.Web.Services.WebMethod(MessageName:="AddIntegers")> _
    Public Function Add(ByVal iValueOne As Integer, _
                        ByVal iValueTwo As Integer) As Integer
        Add = iValueOne + iValueTwo
    End Function
End Class

public class Service1 : System.Web.Services.WebService
{ 
    [System.Web.Services.WebMethod(MessageName="AddDoubles")]
    public double Add(double dValueOne, double dValueTwo)
    {
       return dValueOne + dValueTwo;
    }
    [System.Web.Services.WebMethod(MessageName="AddIntegers")]
    public int Add(int iValueOne, int iValueTwo)
    {
       return iValueOne + iValueTwo;
    }
}

Die SOAP-Anforderungsmeldung für die Methode AddDoubles, die Double-Werte hinzufügt, sieht ungefähr wie folgt aus:

POST /myWebService/Service1.asmx HTTP/1.1
Host: localhost
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://tempuri.org/AddDoubles"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <AddDoubles xmlns="http://tempuri.org/">
      <dValueOne>double</dValueOne>
      <dValueTwo>double</dValueTwo>
    </AddDoubles>
  </soap:Body>
</soap:Envelope>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

Die SOAP-Antwortmeldung für die Methode AddDoubles, die Double-Werte hinzufügt, sieht ungefähr wie folgt aus:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <AddDoublesResponse xmlns="http://tempuri.org/">
      <AddDoublesResult>double</AddDoublesResult>
    </AddDoublesResponse>
  </soap:Body>
</soap:Envelope>

TransactionOption

Die TransactionOption-Eigenschaft des WebMethod-Attributs aktiviert die XML-Webdienstmethode, die als Stammobjekt einer Transaktion teilnehmen soll. Obwohl Sie für die TransactionOption-Eigenschaft einen der Werte der TransactionOption-Enumeration festlegen können, gibt es für eine XML-Webdienstmethode nur zwei mögliche Verhaltensweisen: sie nimmt nicht an einer Transaktion teil (Disabled, NotSupported, Supported), oder sie erstellt eine neue Transaktion (Required, RequiresNew). Wenn nichts anderes angegeben wurde, lautet der Standardwert TransactionOption.Disabled. Weitere Informationen finden Sie unter WebMethodAttribute.TransactionOption-Eigenschaft.

Zusätzlich zu den Voraussetzungen für XML-Webdienstmethoden ist ein Verweis auf System.EnterpriseServices.dll erforderlich. Dieser Namespace enthält Methoden und Eigenschaften, die das verteilte Transaktionsmodell von COM+-Diensten offen legen. Mit der System.EnterpriseServices.ContextUtil-Klasse können Sie über die SetAbort-Methode oder die SetComplete-Methode eine Entscheidung hinsichtlich der Transaktion treffen. Weitere Informationen finden Sie unter Teilnehmen an Transaktionen in mit ASP.NET erstellten XML-Webdiensten und Automatische Transaktionen und XML-Webdienste.

So erstellen Sie eine neue Transaktion mit einer XML-Webdienstmethode

Fügen Sie einen Verweis auf System.EnterpriseServices.dll hinzu. Weitere Informationen finden Sie unter Hinzufügen und Entfernen von Verweisen.
Fügen Sie dem XML-Webdienst den System.EnterpriseServices-Namespace wie unten gezeigt hinzu:
```
Imports System.EnterpriseServices
```
```
using System.EnterpriseServices;
```

Verwenden Sie die TransactionOption-Eigenschaft des WebMethod-Attributs wie im Folgenden gezeigt:

Public Class Service1
    Inherits System.Web.Services.WebService
    <System.Web.Services.WebMethod( _
       TransactionOption:=TransactionOption.RequiresNew)> _
    Public Function DoSomethingTransactional() As String
       'The transaction was successful...
       ContextUtil.SetComplete
       DoSomethingTransactional = ContextUtil.TransactionId.ToString()
    End Function
End Class

public class Service1 : System.Web.Services.WebService
{ 
    [System.Web.Services.WebMethod(
       TransactionOption=TransactionOption.RequiresNew)]
    public string DoSomethingTransactional()
    {
       // The transaction was successful...
       ContextUtil.SetComplete();
       return ContextUtil.TransactionId.ToString();
    }
}