Compartir a través de

Definición y especificación de errores

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. En este tema se describe cuándo y cómo definir contenido de error personalizado y especificar qué operaciones pueden devolverlas. Para obtener más información sobre cómo un servicio o un cliente dúplex pueden enviar esos errores y cómo una aplicación de cliente o servicio controla estos errores, consulte Envío y recepción de errores. Para obtener información general sobre el control de errores en las aplicaciones de Windows Communication Foundation (WCF), consulta Especificar y controlar errores en contratos y servicios.

Información general

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

  1. Defina las condiciones de error que debe conocer un cliente del servicio.

  2. Defina el contenido personalizado de las fallas SOAP para esas condiciones de error.

  3. Marque las operaciones para que los errores SOAP específicos que produzcan se expongan a los clientes en WSDL.

Definición de condiciones de error que los clientes deben conocer

Los errores 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 operación en WSDL, los clientes saben y, por lo tanto, 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 el código administrado se van a convertir en fallas y devolver al cliente le proporciona la oportunidad de separar las condiciones de error y los errores en su servicio de la conversación formal de errores que tiene con un cliente.

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

[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 ya sea una falla SOAP personalizada específica para dividir por cero, una falla personalizada específica de las operaciones matemáticas pero que contiene información específica para dividir por cero, múltiples fallas para varias situaciones de error diferentes o ninguna falla SOAP en absoluto.

Definir el contenido de las condiciones de error

Una vez que se ha identificado una condición de error como una que puede devolver útilmente un error SOAP personalizado, el siguiente paso es definir el contenido de ese error y asegurarse de que la estructura de contenido se puede serializar. En el ejemplo de código de la sección anterior se muestra un error específico de una Divide operación, pero si hay otras operaciones en el Calculator servicio, un único error SOAP personalizado puede informar al cliente de todas las condiciones de error de la calculadora, Divide incluidas. En el ejemplo de código siguiente se muestra la creación de un error SOAP personalizado, , MathFaultque puede notificar errores realizados mediante todas las operaciones matemáticas, incluido Divide. Aunque la clase puede especificar una operación (la Operation propiedad) y un valor que describe el problema (la ProblemType propiedad), la clase y estas propiedades deben ser serializables para ser transferidas al cliente en una falta SOAP personalizada. Por lo tanto, los System.Runtime.Serialization.DataContractAttribute atributos y System.Runtime.Serialization.DataMemberAttribute se usan para hacer que el tipo y sus propiedades sean serializables y lo más interoperables 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 la transferencia de datos en contratos de servicio. Para obtener una lista de la compatibilidad con la serialización que System.Runtime.Serialization.DataContractSerializer proporciona, vea 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, use el System.ServiceModel.FaultContractAttribute atributo y pase el tipo del tipo de datos personalizado que ha construido. En el ejemplo de código siguiente se muestra cómo usar el FaultContractAttribute atributo para especificar que la Divide operación puede devolver un error SOAP de 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 FaultContractAttribute atributo.

El siguiente paso, para implementar el contrato de error en la implementación de la operación, se describe en el tema Envío y recepción de errores.

Consideraciones de interoperabilidad, WSDL y SOAP

En algunas circunstancias, especialmente cuando se interopera con otras plataformas, puede ser importante controlar la forma en que aparece un error en un mensaje SOAP o en la forma en que se describe en los metadatos de WSDL.

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

Según el estándar SOAP, un error puede tener un Action, un Codey un Reason. El Action está controlado por la propiedad Action. Las propiedades Code y Reason son ambas propiedades de la clase System.ServiceModel.FaultException, que es la clase padre del genérico System.ServiceModel.FaultException<TDetail>. La Code propiedad incluye un SubCode elemento.

Al acceder a servicios que no son servicios que generan errores, existen ciertas limitaciones. WCF solo admite errores con tipos de detalle que describe el esquema y que son compatibles con contratos de datos. Por ejemplo, como se mencionó anteriormente, WCF no admite errores que usan atributos XML en sus tipos de detalles o errores con más de un elemento de nivel superior en la sección de detalles.

Consulte también