Partilhar 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 aplicativos de nível superior.

Visão geral

O conteúdo do corpo de uma mensagem de falha é representado nesta 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 o WS_FAULT_REASON que contém texto descrevendo a falha), ele 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 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 erro são mapeadas para falhas, enquanto ainda permite que informações ricas de falhas sejam enviadas.

As seguintes propriedades podem ser usadas com WsSetFaultErrorProperty para capturar informações de falha para 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 aos cabeçalhos da mensagem de solicitação. Essa propriedade pode ser usada para especificar um WS_XML_BUFFER contendo 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.

O 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çãoWsSetFaultErrorDetail. Esta função pode ser usada para associar conteúdo XML arbitrário com a falha.

O Service Host 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 detalhado de uma falha será enviado.

Se estiver trabalhando na camada de canal, falhas podem ser enviadas para um objeto WS_ERROR usando WsSendFaultMessageForError.

Tratamento de falhas em um cliente

Se um cliente receber uma falha ao usar um de proxy de serviço ou por meio WsRequestReply ou WsReceiveMessage, o erro de WS_E_ENDPOINT_FAULT_RECEIVED será retornado. (Para obter mais informações, consulte Windows Web Services Return Values.) 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 no detalhe da falha. Isso pode ser acessado usando o uso da funçãoWsGetFaultErrorDetail.

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 no corpo de uma 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 no fato de o primeiro elemento no corpo ser um elemento de falha durante WsReadMessageStart ou WsReadEnvelopeStart.

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

As enumerações a seguir fazem parte de falhas:

As seguintes funções fazem parte das falhas:

As seguintes estruturas fazem parte das falhas: