Compartilhar via

Falhas

  • Artigo

Uma mensagem de falha é usada para comunicar informações de erro sobre uma falha em um ponto de extremidade remoto. Uma mensagem de falha é como qualquer outra mensagem, exceto que o formato do corpo da mensagem tem um formato padrão. As falhas podem ser usadas tanto por protocolos de infraestrutura, como WS-Addressing, quanto por protocolos de aplicativo de nível superior.

Visão geral

O conteúdo do corpo de uma mensagem de falha é representado nessa API usando a estrutura WS_FAULT . Embora uma falha tenha um conjunto fixo de campos usados para fornecer informações sobre a falha (como o WS_FAULT_CODE que identifica o tipo de falha e a WS_FAULT_REASON que contém texto que descreve a falha), ela também contém um campo de detalhes que pode ser usado para especificar conteúdo XML arbitrário relacionado à falha.

Gerando falhas em um serviço

Um serviço normalmente enviará uma falha devido a algum erro que foi encontrado durante o processamento da solicitação. O modelo usado por essa API é que o código no serviço que encontra o erro de processamento capturará as informações de falha necessárias no objeto WS_ERROR e, em seguida, o código em um nível mais alto na cadeia de chamadas realmente enviará a falha usando as informações capturadas na camada inferior. Esse esquema permite que o código que envia a falha seja isolado de como as situações de erros são mapeadas para falhas, permitindo que informações de falha avançadas sejam enviadas.

As propriedades a seguir podem ser usadas com WsSetFaultErrorProperty para capturar informações de falha de um objeto WS_ERROR :

  • WS_FAULT_ERROR_PROPERTY_ACTION. Isso especifica a ação a ser usada para a mensagem de falha. Se isso não for especificado, uma ação padrão será fornecida.
  • WS_FAULT_ERROR_PROPERTY_FAULT. Isso contém a estrutura WS_FAULT que é enviada no corpo da mensagem de falha.
  • WS_FAULT_ERROR_PROPERTY_HEADER. Algumas falhas incluem cabeçalhos de mensagem que são adicionados à mensagem de falha para transmitir falhas de processamento relacionadas a cabeçalhos da mensagem de solicitação. Essa propriedade pode ser usada para especificar um WS_XML_BUFFER que contém um cabeçalho a ser adicionado à mensagem de falha.

Todas as cadeias de caracteres de erro adicionadas ao objeto WS_ERROR são usadas como o texto na falha enviada. Cadeias de caracteres de erro podem ser adicionadas ao objeto de erro usando WsAddErrorString.

A função WsSetFaultErrorProperty pode ser usada para definir essas propriedades do objeto WS_ERROR .

Para definir os detalhes da falha armazenada no objeto WS_ERROR , use a função WsSetFaultErrorDetail . Essa função pode ser usada para associar conteúdo XML arbitrário à falha.

O Host de Serviço enviará automaticamente falhas usando as informações acima no objeto WS_ERROR . A propriedade WS_SERVICE_PROPERTY_FAULT_DISCLOSURE pode ser usada para controlar o quão detalhada de uma falha será enviada.

Se estiver trabalhando na camada de canal, as falhas poderão ser enviadas para um objeto WS_ERROR usando WsSendFaultMessageForError.

Tratamento de falhas em um cliente

Se um cliente receber uma falha ao usar um Proxy de Serviço ou por meio de WsRequestReply ou WsReceiveMessage, o erro WS_E_ENDPOINT_FAULT_RECEIVED será retornado. (Para obter mais informações, consulte Valores retornados dos Serviços Web do Windows.) Essas funções também preencherão o objeto WS_ERROR fornecido à chamada com informações sobre a falha recebida.

As seguintes propriedades de um objeto WS_ERROR podem ser consultadas usando WsGetFaultErrorProperty para obter informações sobre uma falha recebida:

Uma falha pode conter conteúdo XML adicional arbitrário nos detalhes da falha. Isso pode ser acessado usando a função WsGetFaultErrorDetail .

Usando falhas com mensagens

A seção a seguir se aplica ao lidar diretamente com o conteúdo do corpo de uma mensagem de falha.

O conteúdo do corpo de uma mensagem de falha é representado pela estrutura de WS_FAULT padrão, que tem suporte interno para serialização.

Por exemplo, o código a seguir pode ser usado para gravar uma falha em um corpo de mensagem:

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

O código a seguir pode ser usado para ler uma falha de um corpo de mensagem:

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 se uma mensagem recebida é uma falha ou não, o WS_MESSAGE_PROPERTY_IS_FAULT pode ser consultado. Essa propriedade é definida com base em se o primeiro elemento no corpo é um elemento de falha durante WsReadMessageStart ou WsReadEnvelopeStart.

Para criar um WS_FAULT dado um WS_ERROR, use a função WsCreateFaultFromError .

As seguintes enumerações fazem parte de falhas:

As seguintes funções fazem parte de falhas:

As seguintes estruturas fazem parte de falhas: