Propriedades e propriedades estendidas no EWS no Exchange

  • Artigo

Descubra como você pode definir e acessar propriedades em itens e pastas usando o EWS no Exchange.

Uma caixa de correio do Exchange contém um grande número de itens, incluindo mensagens de email, compromissos, reuniões e assim por diante. Esses itens são compostos por propriedades; as propriedades descrevem os itens. Você pode usar propriedades de item para executar uma pesquisa, sincronizar alterações de item e criar tipos de propriedade personalizados. Este artigo fornece uma visão geral das propriedades e como você pode trabalhar com propriedades em seu aplicativo.

Propriedades do item exchange

Itens e pastas no Exchange são essencialmente linhas em tabelas. A propriedade principal que identifica um item ou pasta é seu identificador EWS. Embora haja outras propriedades relacionadas ao identificador no banco de dados exchange, para EWS, o identificador EWS atua como a chave primária para a coleção de propriedades que descrevem um item. A propriedade identificador EWS contém duas partes:

  • Uma propriedade ItemId ou FolderId que identifica o item

  • Uma propriedade ChangeKey que contém informações com estado sobre se um item ou pasta foi alterado

Todos os itens em uma caixa de correio são armazenados no mesmo banco de dados do Exchange e usam o mesmo esquema de banco de dados. Os itens são distinguidos por uma combinação da propriedade ItemClass , restrições de propriedade e as camadas lógicas de negócios que afetam a forma como são gerenciados no repositório exchange. A Tabela 1 mostra como as propriedades são aplicadas em diferentes tipos de item; neste exemplo, itens de email e compromisso. Ambos os itens têm um valor para a propriedade Subject . Mas observe que a propriedade IsAllDayEvent não está definida no item de email e a propriedade IsReadReceiptRequested não está definida no compromisso. Felizmente, você não precisa saber quais propriedades são aplicáveis para cada classe de item; O EWS manipula isso para você.

Tabela 1. Comparação de propriedades de compromisso e email

Tipo de item Classe item Assunto IsAllDayEvent IsReadReceiptRequested
Email
 Ipm. Nota
 Relatório de status: Projeto X concluído
 NULL
 verdadeiro
Compromisso
 Ipm. Nomeação
 Reunião da empresa Contoso
 falso
 NULL

O esquema EWS dá suporte a muitas das restrições gerenciadas pelo banco de dados exchange e pelas camadas lógicas de negócios entre o EWS e o banco de dados exchange. O esquema EWS aplica um conjunto definido de propriedades a cada tipo de item. A seguir estão os itens de banco de dados do Exchange fortemente tipado fornecidos pelo EWS:

  • Mensagens de email

  • Compromissos

  • Contatos

  • Listas de distribuição

  • Mensagens de reunião

  • Solicitações de reunião

  • Respostas de reunião

  • Cancelamentos de reunião

  • Tarefas

  • Postar itens

Itens genéricos são retornados pelo EWS como mensagens de email. A API Gerenciada do EWS implementa todos esses tipos de item.

Observação

Os objetos de resposta são enviados apenas pelo cliente para o servidor em resposta aos itens recebidos de outras pessoas. Eles não existem no banco de dados do Exchange.

Quais são as propriedades no EWS?

O esquema EWS descreve os dados enviados entre um cliente EWS e o Exchange. Grande parte do esquema descreve as propriedades de item e pasta que você pode acessar no banco de dados do Exchange. O esquema EWS descreve a representação XML das propriedades do banco de dados do Exchange que estão disponíveis para seu aplicativo. As propriedades reais, em termos de quais propriedades estão disponíveis, qual forma elas tomam e os valores que retornam, variam de acordo com o que você está tentando fazer. Por exemplo, a propriedade Body retornará apenas os primeiros 512 caracteres em uma operação FindItem , mas a operação GetItem retorna o texto completo do item. Embora a maioria das propriedades seja settable e recuperável, algumas propriedades são definidas apenas pelo Exchange. Cada propriedade existe no esquema em um formato XML que reflete a propriedade como ela é armazenada no banco de dados do Exchange ou é calculada a partir de propriedades armazenadas no banco de dados exchange. A propriedade Subject é um exemplo de uma propriedade settable; A propriedade UnreadCount em uma pasta é um exemplo de uma propriedade computada. Um conjunto principal de propriedades é comum aos tipos de item principais.

Os seguintes fatores determinam o conjunto de propriedades que seu aplicativo obtém do Exchange:

  • A operação que seu aplicativo está chamando

  • A forma de resposta base

  • O tipo de item

  • Os caminhos de propriedade especificados

É importante entender como esses diferentes fatores afetam os dados que você pode acessar. Assim como acontece com o exemplo da propriedade Body mencionada anteriormente, algumas informações estão condicionalmente disponíveis dependendo de vários fatores. Entender esses fatores pode economizar tempo ajudando você a escolher as opções corretas para acessar as informações desejadas. Para descobrir quais propriedades estão acessíveis, você precisará testar esses fatores para determinar como acessar as propriedades que seu aplicativo precisa. Esta seção descreve como esses diferentes fatores afetam quais propriedades são retornadas em respostas EWS.

Formas de resposta EWS

O Exchange armazena muitas informações sobre itens. Às vezes, seu aplicativo não precisa de todas essas informações e, em muitos casos, é melhor não obter tudo. Formas de resposta EWS, também chamadas de formas de propriedade, indicam quais propriedades são retornadas do servidor. O elemento principal da forma de resposta é a forma base. Uma forma base é um saco de propriedade predefinido padrão para itens fortemente tipado. A API Gerenciada do EWS equivalente à forma base é o BasePropertySet. O EWS inclui três formas de resposta padrão.

Tabela 2. Formas de resposta padrão

Nome da forma de resposta padrão Equivalente à API Gerenciada do EWS Descrição
IdOnly
 Valor BasePropertySet.IdOnly
 Somente o identificador EWS e a chave de alteração são retornados. A menos que o cliente use todas as propriedades retornadas pela forma AllProperties ou Default, use a forma IdOnly e especifique propriedades adicionais usando o caminho de propriedade definido na classe PropertySet . A maioria dos aplicativos deve usar a forma de resposta IdOnly com propriedades adicionais especificadas. Isso reduz a quantidade de dados não utilizados solicitados pelos clientes.
Padrão
 N/D
 Um conjunto de propriedades padrão para o tipo de item. Use somente essa forma de resposta se o aplicativo usar todas as propriedades.
AllProperties
 Valor BasePropertySet.FirstClassProperties
 Um conjunto maior de propriedades do que a forma Padrão. Embora o nome o insira, essa opção não retorna todas as propriedades em um item. Esse conjunto de propriedades retorna as propriedades que os aplicativos cliente usam com mais frequência. Se você precisar de propriedades adicionais, poderá solicitá-las pelo caminho da propriedade.
Se o aplicativo não usar todas as propriedades retornadas com essa forma de resposta, use a forma de resposta IdOnly com propriedades adicionais especificadas.

Muitas operações EWS retornam itens e suas propriedades. Independentemente das formas de resposta especificadas, diferentes operações podem retornar diferentes conjuntos de propriedades. Diferentes tipos de item também retornam propriedades diferentes, dependendo da operação e da forma de resposta especificada. As operações a seguir usam formas de resposta para identificar quais propriedades devem ser retornadas.

Tabela 3. Operações que usam formas de resposta

Operação do EWS Método da API Gerenciada do EWS
GetConversationItems
Método ExchangeService.GetConversationItems
GetFolder
Método Folder.Bind
GetItem
Método Item.Bind
Método ExchangeService.BindToItems
FindConversation
Método ExchangeService.FindConversation
FindFolder
Método Folder.FindFolders
Método ExchangeService.FindFolders
FindItem
Método Folder.FindItems
Método ExchangeService.FindItems
FindPeople
Não implementado.
ResolveNames
Método ExchangeService.ResolveNames
SearchMailboxes
Método ExchangeService.SearchMailboxes
Método ExchangeService.BeginSearchMailboxes
SyncFolderHierarchy
Método ExchangeService.SyncFolderHierarchy
SyncFolderItems
Método ExchangeService.SyncFolderItems

As formas de propriedade são uma maneira rudimentar de identificar as propriedades que você deseja que seu aplicativo retorne. Às vezes, no entanto, seu aplicativo precisa de um conjunto mais refinado de propriedades específicas. Para isso, você pode usar o caminho da propriedade.

Escolher propriedades por seu caminho de propriedade

Um caminho de propriedade EWS é metadados usados para identificar propriedades em uma solicitação ou resposta.

Tabela 4. Tipos de caminho de propriedade

Tipo de caminho de propriedade Tipo de esquema Implementação da API Gerenciada do EWS Descrição
FieldUri
 Pathtounindexedfieldtype
 Tipos que herdam do ServiceObjectSchema.
O caminho de propriedade mais comum. Os caminhos da propriedade FieldUri são especificados em um objeto PropertySet na API Gerenciada do EWS. A maioria das propriedades EWS pode ser especificada pelo caminho da propriedade FieldUri. Isso é descrito pelo UnindexedFieldURIType no esquema EWS.
O caminho da propriedade FieldUri XML se parece com este:
XML<FieldURI FieldURI="item:Subject"/>Esse caminho de propriedade é o equivalente a ItemSchema.Subject na API Gerenciada do EWS.
IndexedFieldUri
 Pathtoindexedfieldtype
 Tipos que herdam do ItemSchema.
Identifica propriedades de dicionário que exigem um índice de propriedade para especificar o valor a ser retornado. Use esse caminho quando uma propriedade pode ter mais de um valor. Isso é descrito pela propriedade DictionaryURIType no esquema EWS. Os caminhos de propriedade DictionaryURIType são especificados em um objeto PropertySet na API Gerenciada do EWS.
O caminho da propriedade IndexedFieldUri XML tem a seguinte aparência:
XML<IndexedFieldURI FieldURI="contacts:PhysicalAddress:Street FieldIndex="Home"/>
ExtendedFieldUri
 Pathtoextendedfieldtype
 ExtendedPropertyDefinition
Identifica uma definição de propriedade estendida que identifica propriedades personalizadas ou não esquematizadas em itens.
O XML da propriedade ExtendedFieldUri tem a seguinte aparência:
XML<ExtendedFieldURI> PropertyTag="0x1234" PropertyType="Integer" />
ExceptionFieldUri
 ExceptionFieldURI
 ServiceResponse
Especifica propriedades associadas a um erro em uma resposta EWS. Isso é descrito pelo tipo ExceptionPropertyURIType no esquema EWS. Isso ocorre apenas no elemento MessageXml de respostas de erro que ocorrem quando você está trabalhando com padrões de recorrência de calendário.

Como prática recomendada, ao solicitar propriedades, use a forma de base IdOnly (BasePropertySet.IdOnly na API Gerenciada do EWS) e solicite apenas as propriedades que seu aplicativo precisa especificando os caminhos da propriedade.

Propriedades esquematizadas

A maioria das propriedades que seu cliente EWS precisa são descritas pelo esquema EWS. As definições de tipo de item e pasta primária, que contêm as definições de propriedade, são encontradas no esquema types.xsd. Os tipos de esquema a seguir contêm as definições de propriedade para a maioria dos objetos que você pode usar.

Tabela 5. Tipos de esquema que contêm definições de propriedade

Tipo de esquema EWS Equivalente ao tipo de API Gerenciada do EWS Define o...
ItemType
Classe item
Conjunto de propriedades de tipo de item base. Esse tipo pode ser criado a partir de um cliente, mas nunca é retornado pelo Exchange. O Exchange retorna um objeto MessageType para todos os objetos genéricos.
MessageType
Classe EmailMessage
Email conjunto de propriedades de objeto de mensagem e a propriedade definida para todos os objetos genéricos.
CalendarItemType
Classe de compromisso
Conjunto de propriedades de item de calendário; isso inclui compromissos únicos e recorrentes.
Contactitemtype
Classe contact
Contate o conjunto de propriedades do item.
Distributionlisttype
Classe ContactGroup
Conjunto de propriedades da lista de distribuição pessoal.
Meetingmessagetype
Classe MeetingMessage
Conjunto de propriedades de tipo de mensagem de reunião.
Meetingrequestmessagetype
Classe MeetingRequest
Conjunto de propriedades de tipo de solicitação de reunião.
MeetingResponseMessageType
Classe MeetingResponse
Conjunto de propriedades de tipo de resposta de reunião.
MeetingCancellationMessageType
Classe MeetingCancellation
Conjunto de propriedades de tipo de cancelamento de reunião.
Tasktype
Classe de tarefa
Conjunto de propriedades do tipo de tarefa.
PostItemType
Classe PostItem
Conjunto de propriedades de tipo postitem.
Foldertype
Classe pasta
Conjunto de propriedades de tipo de pasta.
Calendarfoldertype
Classe CalendarFolder
Conjunto de propriedades do tipo SearchFolder.
Contactsfoldertype
Classe ContactsFolder
Conjunto de propriedades tipo ContactsFolder.
Searchfoldertype
Classe SearchFolder
Conjunto de propriedades do tipo SearchFolder.
TasksFolderType
Classe TasksFolder
Conjunto de propriedades do tipo TasksFolder.
UserConfigurationType
Classe UserConfiguration
Conjunto de propriedades de tipo UserConfiguration.

Embora as propriedades no esquema EWS sejam suficientes para muitos aplicativos, você não pode implementar alguns cenários usando apenas o que é descrito no esquema. Para esses cenários, você pode estender as propriedades.

Propriedades estendidas (também conhecidas como propriedades não esquematizadas)

As propriedades estendidas permitem criar propriedades personalizadas, que lhe dão acesso a propriedades em itens e pastas no repositório exchange que não são definidas no esquema EWS. Você pode usá-los para acessar o item MAPI nativo e as propriedades da pasta no banco de dados do Exchange. Você pode usar propriedades estendidas para acessar todas as propriedades esquematizadas, pois, sob as capas, essas propriedades esquematizadas não são nada mais do que propriedades MAPI no banco de dados exchange.

O tipo de esquema PathToExtendedFieldType, localizado no esquema types.xsd, define o XML que representa uma propriedade estendida. Esse tipo de esquema define o elemento ExtendedFieldURI em instâncias XML; em outras palavras, ele define o XML enviado entre o serviço e o cliente. O tipo de esquema ExtendedPropertyType define o elemento ExtendedFieldURI e o valor ou a matriz de valores que uma propriedade estendida contém. A tabela a seguir mostra o mapeamento aproximado da propriedade estendida XML e como ela é implementada em itens na API Gerenciada do EWS.

Tabela 6. XML de propriedade estendida conforme implementado na API Gerenciada do EWS

Implementação da API Gerenciada do EWS O que ele contém O que ele mapeia para
Propriedade Item.ExtendedProperties
Uma coleção de propriedades estendidas em um item.
Uma ou mais instâncias de propriedades estendidas em um item.
Classe ExtendedProperty
A definição de propriedade estendida e os valores.
O tipo de esquema ExtendedPropertyType.
Classe ExtendedPropertyDefinition
Uma definição de propriedade estendida.
O tipo de esquema PathToExtendedFieldType.

Se quiser saber mais sobre como usar propriedades estendidas em seu aplicativo, você poderá explorar os seguintes exemplos de código:

Nesta seção

Confira também