Cómo: Utilizar el atributo WebMethod

Artículo
10/07/2008

Actualización: noviembre 2007

El atributo WebMethod se asocia a un método Public para indicar que se desea exponer dicho método como parte del servicio Web XML. También se pueden utilizar las propiedades de este atributo para configurar aún más el comportamiento del método de servicio Web XML. Para obtener más información, vea Modelo de código para servicios Web XML en código administrado.

El atributo WebMethod proporciona las siguientes propiedades:

BufferResponse
CacheDuration
Descripción
EnableSession
MessageName
TransactionOption

BufferResponse

La propiedad BufferResponse del atributo WebMethod permite el almacenamiento en el búfer de respuestas para un método de servicio Web XML. Cuando se establece en true, el valor predeterminado, ASP.NET almacena en el búfer la respuesta completa antes de enviarla al cliente. El almacenamiento en el búfer es muy eficiente y ayuda a mejorar el rendimiento ya que minimiza la comunicación entre el proceso de trabajo y el proceso de IIS. Cuando se establece en false, ASP.NET almacena en el búfer la respuesta en fragmentos de 16KB. Normalmente, esta propiedad se establecería en false sólo cuando no se desee guardar en memoria todo el contenido de la respuesta a la vez. Por ejemplo, se vuelve a escribir una colección que extrae sus elementos de una base de datos. A menos que se especifique lo contrario, el valor predeterminado es true. Para obtener más información, vea WebMethodAttribute.BufferResponse (Propiedad).

Para almacenar en el búfer la respuesta de un método de servicio Web XML

Utilice la propiedad BufferResponse del atributo WebMethod como se muestra a continuación:

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

La propiedad CacheDuration del atributo WebMethod permite el almacenamiento en caché de los resultados de un método de servicio Web XML. ASP.NET guardará en caché los resultados de cada parámetro único establecido. El valor de esta propiedad indica cuántos segundos debe almacenar ASP.NET en caché los resultados. Un valor de cero deshabilita el almacenamiento en caché de los resultados. A menos que se especifique lo contrario, el valor predeterminado es cero. Para obtener más información, vea WebMethodAttribute.CacheDuration (Propiedad).

Para almacenar en caché los resultados de un método de servicio Web XML

Utilice la propiedad CacheDuration del atributo WebMethod como se muestra a continuación:

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;
    }
}

Descripción

La propiedad Description del atributo WebMethod proporciona una descripción de un método de servicio Web XML, que aparecerá en la página de ayuda del servicio. A menos que se especifique lo contrario, el valor predeterminado es una cadena vacía. Para obtener más información, vea WebMethodAttribute.Description (Propiedad).

Para proporcionar una descripción de un método de servicio Web XML

Utilice la propiedad Description del atributo WebMethod como se muestra a continuación:

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

La propiedad EnableSession del atributo WebMethod habilita el estado de sesión en un método de servicio Web XML. Una vez habilitada esta función, el servicio Web XML puede tener acceso a la colección de estado de sesión directamente desde HttpContext.Current.Session o con la propiedad WebService.Session si se hereda de la clase base WebService. A menos que se especifique lo contrario, el valor predeterminado es false. Para obtener más información, vea WebMethodAttribute.EnableSession (Propiedad).

Para habilitar el estado de sesión en un método de servicio Web XML

Utilice la propiedad EnableSession del atributo WebMethod como se muestra a continuación:

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

La propiedad MessageName del atributo WebMethod permite al servicio Web XML identificar de forma única a los métodos sobrecargados mediante un alias. A menos que se especifique lo contrario, el valor predeterminado es el nombre del método. Cuando se especificar la propiedad MessageName, los mensajes SOAP resultantes mostrarán este nombre en lugar del nombre real del método. Para obtener más información, vea WebMethodAttribute.MessageName (Propiedad).

Para proporcionar un nombre de mensaje para un método de servicio Web XML

Utilice la propiedad MessageName del atributo WebMethod como se muestra a continuación:

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;
    }
}

El mensaje de solicitud SOAP del método que agrega dobles, AddDoubles, se asemejará a lo siguiente:

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

El mensaje de respuesta SOAP del método que agrega dobles, AddDoubles, se asemejará a lo siguiente:

<?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

La propiedad TransactionOption del atributo WebMethod permite al método de servicio Web XML participar como objeto raíz de una transacción. Aunque la propiedad TransactionOption se puede establecer en cualquiera de los valores de la enumeración TransactionOption, un método de servicio Web XML sólo tiene dos comportamientos posibles: no participar en una transacción (Disabled, NotSupported, Supported), o crear una transacción nueva (Required, RequiresNew). A menos que se especifique lo contrario, el valor predeterminado es TransactionOption.Disabled. Para obtener más información, vea WebMethodAttribute.TransactionOption (Propiedad).

Además de los requisitos previos de cualquier método de servicio Web XML, tendrá que agregar una referencia a System.EnterpriseServices.dll. Este espacio de nombres contiene métodos y propiedades que exponen el modelo de transacción distribuida encontrado en Servicios COM+. La clase System.EnterpriseServices.ContextUtil le permite participar en la transacción utilizando el método SetAbort o SetComplete. Para obtener más información, vea Participar en transacciones de servicios Web XML creados con ASP.NET y Transacciones automáticas y servicios Web XML.

Para crear una transacción nueva con un método de servicio Web XML

Agregue una referencia a System.EnterpriseServices.dll. Para obtener más información, vea Agregar y quitar referencias.
Agregue el espacio de nombres System.EnterpriseServices al servicio Web XML, como se indica a continuación:
```
Imports System.EnterpriseServices
```
```
using System.EnterpriseServices;
```

Utilice la propiedad TransactionOption del atributo WebMethod como se muestra a continuación:

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