Verificação dos resultados de uma chamada do EWS ou de API Gerenciada do EWS

  • Artigo

Saiba como verificar os resultados de suas chamadas de API gerenciada por EWS ou EWS.

Quando as coisas não estão funcionando corretamente, é útil ver o que está acontecendo examinando as solicitações SOAP que seu aplicativo está enviando pela rede e as respostas que o servidor está enviando de volta. O artigo ferramentas e recursos para solução de problemas de aplicativos EWS inclui links para ferramentas para ajudar a capturar e visualizar essas solicitações SOAP. Depois de receber as solicitações e as respostas, como você verifica se a solicitação enviada ao servidor foi processada corretamente? Leia mais para descobrir.

Se você estiver enviando solicitações EWS, iniciará sua verificação verificando o atributo ResponseClass para cada mensagem de resposta na resposta. Isso informará se a operação foi concluída com êxito em cada item.

Dependendo do objeto que seu método está chamando, se você estiver usando a API Gerenciada do EWS para enviar solicitações, poderá fazer algumas verificações usando os objetos de resposta. Mas, como a resposta SOAP contém um superconjunto do que está incluído nos objetos de resposta da API gerenciada do EWS, convém examinar a resposta SOAP também. Como a resposta SOAP geralmente pode conter mais informações do que os objetos de resposta da API gerenciada do EWS, inicie sua verificação com a resposta SOAP.

Verificando os resultados de uma resposta SOAP

Quando você recebe uma resposta SOAP, a primeira coisa a ser observada é o atributo ResponseClass. Esse atributo está incluído em cada instância ResponseMessageType no elemento ResponseMessages, conforme mostrado no exemplo a seguir.

<s:Body>
      <m:GetItemResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
        <m:ResponseMessages>
          <m:GetItemResponseMessage ResponseClass="Success">
          …

Como uma resposta SOAP pode conter várias mensagens de resposta em uma única resposta SOAP, é importante verificar cada mensagem de resposta individualmente.

Se você estiver trabalhando com uma operação que inclui um ResponseClass como parte da resposta da operação, como a seguir, você pode ficar tentado a verificar apenas o ResponseClass da operação.

<soap:Body>
  <m:AddDelegateResponse xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
                         ResponseClass="Success"
                         xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages">
  …

No entanto, o status da operação reflete apenas a forma da resposta de nível superior e não reflete o status de todas as respostas de mensagens individuais. No exemplo a seguir, a operação AddDelegateResponse tem um ResponseClass de Success, mas o elemento DelegateUserResponseMessageType subjacente tem um valor ResponseClass de Error.

<soap:Body>
  <m:AddDelegateResponse xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
                         ResponseClass="Success"
                         xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages">
    <m:ResponseCode>NoError</m:ResponseCode>
    <m:ResponseMessages>
      <m:DelegateUserResponseMessageType ResponseClass="Error">
        <m:MessageText>The user is already a delegate for the mailbox.</m:MessageText>
        <m:ResponseCode>ErrorDelegateAlreadyExists</m:ResponseCode>
        <m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
      </m:DelegateUserResponseMessageType>
    </m:ResponseMessages>
  </m:AddDelegateResponse>
</soap:Body>

Portanto, para respostas SOAP EWS, você não pode confiar no ResponseClass da operação - você precisa examinar o ResponseClass de cada mensagem de resposta para determinar se a operação encontrou algum erro ao processar os itens.

Verificando o êxito

Se cada atributo ResponseClass para cada atributo ResponseMessage estiver definido como Success, a operação será concluída com êxito em todos os itens e você poderá passar para a próxima tarefa.

O exemplo a seguir mostra uma resposta bem-sucedida a uma solicitação de operação GetItem para recuperar um único item. Observe que quando ResponseClass é definido como Success, o ResponseCode associado é sempre definido como NoError.

<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
             xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <m:GetItemResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
        <m:ResponseMessages>
          <m:GetItemResponseMessage ResponseClass="Success">
            <m:ResponseCode>NoError</m:ResponseCode>
            <m:Items>
              <t:Message>
                <t:ItemId Id="Er5bAAA=" 
                          ChangeKey="CQAAABYAAAD32nSTjepyT63rYH17n9THAAAhE0/M" />
                <t:Subject>Dinner Party</t:Subject>
              </t:Message>
            </m:Items>
          </m:GetItemResponseMessage>
        </m:ResponseMessages>
      </m:GetItemResponse>
    </s:Body>

Veja a seguir uma resposta bem-sucedida a uma solicitação de operação GetItem para recuperar vários itens. Cada um dos elementos GetItemResponseMessage tem um ResponseClass de Success.

<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <m:GetItemResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
                     xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
    <m:ResponseMessages>
      <m:GetItemResponseMessage ResponseClass="Success">
        <m:ResponseCode>NoError</m:ResponseCode>
        <m:Items>
          <t:Message>
            <t:ItemId Id="Er5bAAA=" 
                      ChangeKey="CQAAABYAAAD32nSTjepyT63rYH17n9THAAAhE0/M" /
            <t:Subject>Dinner Party</t:Subject>
          </t:Message>
        </m:Items>
      </m:GetItemResponseMessage>
      <m:GetItemResponseMessage ResponseClass="Success">
        <m:ResponseCode>NoError</m:ResponseCode>
        <m:Items>
          <t:Message>
            <t:ItemId Id="3c66AAA="
                      ChangeKey="CQAAABYAAAD32nSTjepyT63rYH17n9THAAAc3kqm" />
            <t:Subject>Company Soccer Team</t:Subject>
          </t:Message>
        </m:Items>
      </m:GetItemResponseMessage>
    </m:ResponseMessages>
  </m:GetItemResponse>
</s:Body>

Tratamento de erros e avisos

Quando você recebe uma resposta e o atributo ResponseClass é definido como Error, a operação não foi concluída com êxito em um ou mais itens. Corrija o problema e repita a solicitação ou a parte da solicitação que falhou. Um valor de atributo ResponseClass do valor Warning só é retornado pela operação ResolveNames e indica que a entidade não pôde ser resolvida para uma identidade exclusiva. Você pode ignorá-lo para todas as outras operações.

Na resposta a seguir, o atributo ResponseClass tem um valor de Error.

<m:GetItemResponseMessage ResponseClass="Error">
  <m:MessageText>Property is not valid for this object type.</m:MessageText>
  <m:ResponseCode>ErrorInvalidPropertyRequest</m:ResponseCode>
  <m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
  <m:MessageXml>
    <t:FieldURI FieldURI="meeting:AssociatedCalendarItemId" />
  </m:MessageXml>
  <m:Items />
</m:GetItemResponseMessage>

Neste exemplo, o EWS fornece dicas para depurar o problema. Quando o atributo ResponseClass tem um valor de Error, os seguintes elementos adicionais são incluídos na resposta quando aplicável:

Você pode usar as informações fornecidas nesses elementos para investigar seu problema. No exemplo anterior, o MessageText indica que a propriedade não é válida para o tipo de objeto. A solicitação era para receber uma mensagem de email, mas o conjunto de propriedades incluía o AssociatedCalendarItemId, que é válido apenas para itens de compromisso.

O exemplo a seguir mostra um erro recebido como parte de uma operação em lote para obter vários itens de email. O primeiro item foi recuperado com sucesso e ResponseClass é definido como Success. O segundo item não pôde ser encontrado e o ResponseClass está definido como Error.

<m:GetItemResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
                        xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
  <m:ResponseMessages>
    <m:GetItemResponseMessage ResponseClass="Success">
      <m:ResponseCode>NoError</m:ResponseCode>
      <m:Items>
        <t:Message>
          <t:ItemId Id="Er5cAAA="
                    ChangeKey="CQAAABYAAAD32nSTjepyT63rYH17n9THAAAhE0/O" />
          <t:Subject>Business plans</t:Subject>
        </t:Message>
      </m:Items>
    </m:GetItemResponseMessage>
    <m:GetItemResponseMessage ResponseClass="Error">
      <m:MessageText>The specified object was not found in the store.</m:MessageText>
      <m:ResponseCode>ErrorItemNotFound</m:ResponseCode>
      <m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
      <m:Items />
    </m:GetItemResponseMessage>
  </m:ResponseMessages>
</m:GetItemResponse>

Quando um ou mais itens em uma solicitação em lote não podem ser processados conforme solicitado, um erro é retornado para cada item que falhou e o restante dos itens no lote são processados conforme o esperado. Podem ocorrer falhas no processamento em lote se o item tiver sido excluído e, portanto, não puder ser enviado, recuperado ou atualizado, ou se o item for movido para uma pasta diferente e, portanto, tiver uma nova ID de item. Como a operação será concluída para alguns itens e não retornará um erro quando um ou mais itens não puderem ser processados, é importante verificar cada atributo ResponseClass antes de passar para a próxima operação.

Se as informações fornecidas pelos elementos de resposta não ajudarem você a corrigir sua solicitação ou desbloqueá-lo, consulte Próximas etapas.

Verificando os resultados de uma chamada de método de API gerenciada do EWS

Se você estiver usando a API gerenciada do EWS e chamando um método em um objeto ExchangeService, seu método provavelmente retornará um objeto ServiceResponseCollection, que contém uma coleção de objetos ServiceResponseou uma coleção de objetos derivados dos objetos ServiceResponse. Os objetos ServiceResponseCollection e ServiceResponse incluídos contêm informações sobre o resultado da chamada do método, que você pode usar para verificar seus resultados.

Se você estiver usando a API gerenciada do EWS e chamando um método em um objeto Item ou um dos objetos derivados, o método provavelmente não retornará um objeto de resposta para verificar o êxito, mas lançará uma Exceção se o método não for concluído com êxito.

Verificando o êxito

Um benefício de usar a API gerenciada do EWS é que ela fornece um status geral ao lidar com vários itens em uma resposta. Portanto, se o método que você chamou retornar um ServiceResponseCollection, você poderá verificar se a propriedade OverallResult do ServiceResponseCollection é igual a ServiceResult.Success. Em caso afirmativo, todos os itens do processo em lote foram concluídos com êxito; você não precisa verificar cada objeto ServiceResponse individualmente. Se a propriedade OverallResult não estiver definida como ServiceResult.Success, você deverá manipular o erro ou aviso.

Se o método que você está chamando não retorna um ServiceResponseCollection, mas retorna um objeto ServiceResponse, você deve verificar o valor da propriedade Result. Se o valor Result for definido como Success, você saberá que o método foi concluído com êxito.

Se o método que você está chamando não tiver valor de retorno, não há como verificar o sucesso por meio da API gerenciada do EWS. Contanto que uma exceção não seja lançada, você pode assumir que o método foi concluído com êxito. Para validação adicional, você também pode verificar a resposta SOAP para verificar os resultados.

Tratamento de erros, avisos e exceções

Se o código da API gerenciada do EWS gerar uma Exception, você poderá usar o valor Exception.Message para determinar a origem do erro. A propriedade Message contém o conteúdo do elemento MessageText na resposta SOAP subjacente. Além disso, se a exceção for do tipo objeto ServiceResponseException, uma das exceções mais comuns, você também poderá recuperar o ErrorCode contido no elemento SOAP ResponseCode subjacente e a propriedade Response que identifica o objeto ServiceResponseassociado. O código a seguir mostra como capturar e exibir o conteúdo de um ServiceResponseException.

try
    {
         …
    }
    catch (ServiceResponseException ex)
    {
        Console.WriteLine("Error code: " + ex.ErrorCode);
        Console.WriteLine("Error message: " + ex.Message);
        Console.WriteLine("Response: " + ex.Response);
    }

Se o método que você chamou retornar um ServiceResponseCollection e o valor da propriedade OverallResult for igual a Warning ou Error, você terá que percorrer cada objeto no ServiceResponseCollection para encontrar o erro. A propriedade OverallResult é definida como Warning se pelo menos uma resposta tiver seu valor Result definido como Warning e todas as outras respostas tiverem seus valores Result definidos como Success. A propriedade OverallResult será definida como Error se pelo menos uma resposta tiver seu valor Result definido como Error. Quando o OverallResult é definido como Warning ou Error, as seguintes propriedades são definidas nos objetos ServiceResponse conforme apropriado:

  • ErrorCode — Contém o código de erro, que pode ser usado para encontrar recursos adicionais de solução de problemas.

  • ErrorDetails — Contém detalhes sobre o erro de alguns ErrorCodes. Por exemplo, quando o código de erro é ErrorRecurrenceHasNoOccurrence, o ErrorDetails conterá chaves para EffectiveStartDate e EffectiveEndDate.

  • ErrorMessage — Descreve o erro.

  • ErrorProperties — Se disponível, identifica as propriedades que causaram o erro. Por exemplo, quando o código de erro é ErrorInvalidPropertyForOperation, ErrorProperties contém a definição da propriedade que era inválida para a solicitação.

  • Result — Contém Erro ou Warning quando um problema é encontrado.

Se as informações fornecidas pelas propriedades ServiceResponse não fornecerem informações suficientes para corrigir sua chamada de método ou desbloqueá-lo, consulte Próximas etapas para obter mais informações sobre os valores de ErrorCode.

Você pode procurar informações adicionais de solução de problemas nos seguintes tópicos:

Além disso, dependendo do que você está tentando realizar em sua solicitação, você pode encontrar informações úteis adicionais sobre o código de erro nos seguintes tópicos:

Confira também