Compartir a través de

Errores

  • Artículo

Se usa un mensaje de error para comunicar información de error sobre un error en un punto de conexión remoto. Un mensaje de error es similar a cualquier otro mensaje, excepto que el formato del cuerpo del mensaje tiene un formato estándar. Los errores se pueden usar tanto por protocolos de infraestructura, como WS-Addressing, como por protocolos de aplicación de nivel superior.

Información general

El contenido del cuerpo de un mensaje de error se representa en esta API mediante la estructura WS_FAULT . Aunque un error tiene un conjunto fijo de campos usados para proporcionar información sobre el error (como el WS_FAULT_CODE que identifica el tipo de error y el WS_FAULT_REASON que contiene texto que describe el error), también contiene un campo de detalle que se puede usar para especificar contenido XML arbitrario relacionado con el error.

Generación de errores en un servicio

Normalmente, un servicio enviará un error debido a algún error que se encontró al procesar la solicitud. El modelo usado por esta API es que el código del servicio que encuentra el error de procesamiento capturará la información de error necesaria en el objeto WS_ERROR y, a continuación, el código en un nivel superior de la cadena de llamadas enviará realmente el error mediante la información capturada en la capa inferior. Este esquema permite que el código que envía el error se aísla de cómo se asignan las situaciones de error a los errores, a la vez que permite enviar información enriquecida sobre errores.

Las siguientes propiedades se pueden usar con WsSetFaultErrorProperty para capturar información de error para un objeto de WS_ERROR :

  • WS_FAULT_ERROR_PROPERTY_ACTION. Esto especifica la acción que se va a usar para el mensaje de error. Si no se especifica, se proporciona una acción predeterminada.
  • WS_FAULT_ERROR_PROPERTY_FAULT. Contiene la estructura WS_FAULT que se envía en el cuerpo del mensaje de error.
  • WS_FAULT_ERROR_PROPERTY_HEADER. Algunos errores incluyen encabezados de mensaje que se agregan al mensaje de error para transmitir errores de procesamiento relacionados con los encabezados del mensaje de solicitud. Esta propiedad se puede usar para especificar un WS_XML_BUFFER que contiene un encabezado que se va a agregar al mensaje de error.

Las cadenas de error que se agregan al objeto WS_ERROR se usan como texto del error que se envía. Las cadenas de error se pueden agregar al objeto de error mediante WsAddErrorString.

La función WsSetFaultErrorProperty se puede usar para establecer estas propiedades del objeto WS_ERROR .

Para establecer el detalle del error almacenado en el objeto WS_ERROR , use la función WsSetFaultErrorDetail . Esta función se puede usar para asociar contenido XML arbitrario con el error.

El host de servicio enviará automáticamente errores mediante la información anterior en el objeto WS_ERROR . La propiedad WS_SERVICE_PROPERTY_FAULT_DISCLOSURE se puede usar para controlar cómo se enviarán los detalles de un error.

Si trabaja en la capa de canal, se pueden enviar errores para un objeto WS_ERROR mediante WsSendFaultMessageForError.

Control de errores en un cliente

Si un cliente recibe un error al usar un proxy de servicio o a través de WsRequestReply o WsReceiveMessage, se devolverá el error WS_E_ENDPOINT_FAULT_RECEIVED . (Para obtener más información, vea Valores devueltos de servicios web de Windows). Estas funciones también rellenarán el objeto WS_ERROR proporcionado a la llamada con información sobre el error recibido.

Se pueden consultar las siguientes propiedades de un objeto WS_ERROR mediante WsGetFaultErrorProperty para obtener información sobre un error recibido:

Un error puede contener contenido XML adicional arbitrario en el detalle del error. Se puede acceder a esto mediante el uso de la función WsGetFaultErrorDetail .

Uso de errores con mensajes

La sección siguiente se aplica al tratar directamente con el contenido del cuerpo de un mensaje de error.

El contenido del cuerpo de un mensaje de error se representa mediante la estructura estándar WS_FAULT , que tiene compatibilidad integrada para la serialización.

Por ejemplo, el código siguiente se puede usar para escribir un error en un cuerpo del mensaje:

HRESULT hr;
WS_ELEMENT_DESCRIPTION faultDescription = { NULL, WS_FAULT_TYPE, NULL, NULL };
WS_FAULT fault = { ... };
hr = WsWriteBody(message, &faultDescription, WS_WRITE_REQUIRED_VALUE, &fault, sizeof(fault), error);

El código siguiente se puede usar para leer un error de un cuerpo del mensaje:

HRESULT hr;
WS_ELEMENT_DESCRIPTION faultDescription = { NULL, WS_FAULT_TYPE, NULL, NULL };
WS_FAULT fault;
hr = WsReadBody(message, &faultDescription, WS_READ_REQUIRED_VALUE, &fault, sizeof(fault), error);

Para saber si un mensaje recibido es un error o no, se puede consultar el WS_MESSAGE_PROPERTY_IS_FAULT . Esta propiedad se establece en función de si el primer elemento del cuerpo es un elemento de error durante WsReadMessageStart o WsReadEnvelopeStart.

Para crear una WS_FAULT dada una WS_ERROR, use la función WsCreateFaultFromError .

Las enumeraciones siguientes forman parte de errores:

Las siguientes funciones forman parte de errores:

Las siguientes estructuras forman parte de errores: