Share via

Definición y especificación de errores

  • Artículo

Los errores de SOAP transmiten información de condición de error desde un servicio a un cliente y, en caso de comunicación dúplex, desde un cliente a un servicio de una manera interoperable. Este tema describe cuándo y cómo definir contenido personalizado de error y especificar qué operaciones pueden devolverlos. Para obtener más información sobre cómo un servicio o un cliente dúplex pueden enviar esos errores, además de sobre cómo una aplicación cliente o de servicio administra estos errores, consulte Envío y recepción de errores. Para obtener información general sobre los procesos de control de errores en las aplicaciones de Windows Communication Foundation (WCF), consulte Especificación y control de errores en contratos y servicios.

Información general

Los errores de SOAP declarados son aquéllos en los que una operación tiene System.ServiceModel.FaultContractAttribute que especifica un tipo de error de SOAP personalizado. Los errores de SOAP no declarados son aquéllos que no se especifican en el contrato para una operación. Este tema le ayuda a identificar esas condiciones de error y crear un contrato de error para su servicio, que los clientes pueden utilizar para administrar correctamente esas condiciones de error cuando sean notificadas por errores de SOAP personalizados. Las tareas básicas son, en orden:

  1. Defina las condiciones que un cliente de su servicio debería saber.

  2. Defina el contenido personalizado de los errores de SOAP para esas condiciones de error.

  3. Marque sus operaciones para que los errores de SOAP específicos que inician se expongan a los clientes en WSDL.

Definir Condiciones de error que los clientes deberían saber

Los errores de SOAP son mensajes descritos públicamente que llevan información de error para una operación determinada. Dado que se describen junto con otros mensajes de la operación en WSDL, los clientes saben y, por consiguiente, esperan controlar dichos errores al invocar una operación. Sin embargo, dado que los servicios WCF se escriben en código administrado, decidir qué condiciones de error en código administrado deben convertirse en errores y devolverse al cliente le proporcionará la oportunidad de separar las condiciones de error y errores de su servicio de la conversación formal sobre el error que ocurre con un cliente.

Por ejemplo, el ejemplo de código siguiente muestra una operación que toma dos enteros y devuelve otro entero. Aquí, se pueden producir varias excepciones, por lo que al diseñar el contrato del error, debe determinar qué condiciones de error son importantes para su cliente. En este caso, el servicio debería detectar la excepción System.DivideByZeroException.

[ServiceContract]  
public class CalculatorService  
{  
    [OperationContract]
    int Divide(int a, int b)  
    {  
      if (b==0) throw new Exception("Division by zero!");  
      return a/b;  
    }  
}  

<ServiceContract> _
Public Class CalculatorService
    <OperationContract> _
    Public Function Divide(a As Integer, b As Integer) As Integer
        If b = 0 Then Throw New DivideByZeroException("Division by zero!")
        Return a / b
    End Function
End Class

En el ejemplo anterior, la operación puede devolver un error de SOAP personalizado, específico de dividir por cero, un error personalizado específico a las operaciones de matemática, pero con información específica a dividir por cero, varios errores para varias situaciones de error diferentes, o ningún error de SOAP en absoluto.

Definir el contenido de condiciones de error

Una vez identificada una condición de error como una que puede devolver un error de SOAP personalizado de forma útil, el paso siguiente es definir los contenidos de ese error y garantizar que se puede serializar la estructura de contenido. El ejemplo de código de la sección anterior muestra un error específico en una operación Divide, pero si hay otras operaciones en el servicio Calculator, a continuación, un error de SOAP personalizado único puede informar el cliente de todas las condiciones de error de la calculadora, Divide incluido. El ejemplo de código siguiente muestra la creación de un error de SOAP personalizado, MathFault, que puede notificar los errores realizados utilizando todas las operaciones de matemática, incluso Divide. Mientras que la clase puede especificar una operación (la propiedad Operation ) y un valor que describe el problema (la propiedad ProblemType ), la clase y estas propiedades deben ser serializables para ser transferidas al cliente en un error de SOAP personalizado. Por consiguiente, System.Runtime.Serialization.DataContractAttribute y los atributos System.Runtime.Serialization.DataMemberAttribute se utilizan para hacer el tipo y sus propiedades serializables y tan interoperable como sea posible.

// Define a math fault data contract
[DataContract(Namespace="http://Microsoft.ServiceModel.Samples")]
public class MathFault
{
    private string operation;
    private string problemType;

    [DataMember]
    public string Operation
    {
        get { return operation; }
        set { operation = value; }
    }

    [DataMember]
    public string ProblemType
    {
        get { return problemType; }
        set { problemType = value; }
    }
}

' Define a math fault data contract
<DataContract([Namespace]:="http://Microsoft.ServiceModel.Samples")> _
Public Class MathFault

    Private m_operation As String
    Private m_problemType As String

    <DataMember()> _
    Public Property Operation() As String

        Get

            Return m_operation

        End Get

        Set(ByVal value As String)

            m_operation = value

        End Set

    End Property

    <DataMember()> _
    Public Property ProblemType() As String

        Get

            Return m_problemType

        End Get

        Set(ByVal value As String)

            m_problemType = value

        End Set

    End Property

End Class

Para obtener más información sobre cómo asegurarse de que los datos son serializables, consulte Especificación de transferencia de datos en contratos de servicio. Para obtener una lista sobre los tipos que admite la clase System.Runtime.Serialization.DataContractSerializer en los procesos de serialización, consulte Tipos admitidos por el serializador de contrato de datos.

Marcar operaciones para establecer el contrato de error

Una vez definida una estructura de datos serializable que se devuelve como parte de un error de SOAP personalizado, el último paso es marcar su contrato de operación como iniciar un error de SOAP de ese tipo. Para ello, utilice el atributo System.ServiceModel.FaultContractAttribute y pase el tipo del tipo de datos personalizado que ha construido. El ejemplo de código siguiente muestra cómo usar el atributo FaultContractAttribute para especificar que la operación Divide puede devolver un error de SOAP del tipo MathFault. Otras operaciones basadas en matemáticas, ahora, también pueden especificar que pueden devolver un MathFault.

[OperationContract]
[FaultContract(typeof(MathFault))]
int Divide(int n1, int n2);

<OperationContract()> _
<FaultContract(GetType(MathFault))> _
Function Divide(ByVal n1 As Integer, ByVal n2 As Integer) As Integer

Una operación puede especificar que devuelve más de un error personalizado marcando esa operación con más de un atributo FaultContractAttribute.

El siguiente paso consiste en implementar el contrato de error en su implementación de la operación. Para hacerlo, consulte el tema Envío y recepción de errores.

SOAP, WSDL y consideraciones de la interoperabilidad

En algunas circunstancias, sobre todo al interoperar con otras plataformas, puede ser importante para controlar la manera en que aparece un error en un mensaje SOAP o la manera en el que se describe en los metadatos de WSDL.

El atributo FaultContractAttribute tiene una propiedad Name que permite controlar el nombre del elemento de error WSDL que se genera en los metadatos para ese error.

Según la norma de SOAP, un error puede tener Action, Codey Reason. Action es controlado por la propiedad Action. La propiedad Code y la propiedad Reason son ambas propiedades de la clase System.ServiceModel.FaultException, que es la clase primaria del System.ServiceModel.FaultException<TDetail> genérico. Una propiedad Code incluye un miembro SubCode.

Al tener acceso a servicios que generan errores, ciertas limitaciones existen. La infraestructura WCF solo admite errores con los tipos de detalle que describa el esquema y que sean compatibles con los contratos de datos. Por ejemplo, como ya se ha mencionado, WCF no admite errores cuyos tipos de detalle usen atributos XML o errores que incluyan más de un elemento de nivel superior en la sección de detalles.

Consulte también