Propiedades y propiedades extendidas de EWS en Exchange

  • Artículo

Descubra cómo puede definir y acceder a las propiedades en elementos y carpetas mediante EWS en Exchange.

Un buzón de Exchange contiene un gran número de elementos, incluidos mensajes de correo electrónico, citas, reuniones, etc. Esos elementos se componen de propiedades; las propiedades describen los elementos. Puede usar propiedades de elemento para realizar una búsqueda, sincronizar los cambios de elementos y crear tipos de propiedad personalizados. En este artículo se proporciona información general sobre las propiedades y cómo puede trabajar con las propiedades de la aplicación.

Propiedades de elementos de Exchange

Los elementos y carpetas de Exchange son básicamente filas en tablas. La propiedad principal que identifica un elemento o carpeta es su identificador de EWS. Aunque hay otras propiedades relacionadas con el identificador en la base de datos de Exchange, para EWS, el identificador de EWS actúa como clave principal para la colección de propiedades que describen un elemento. La propiedad de identificador EWS contiene dos partes:

  • Propiedad ItemId o FolderId que identifica el elemento

  • Propiedad ChangeKey que contiene información con estado sobre si un elemento o carpeta ha cambiado

Todos los elementos de un buzón de correo se almacenan en la misma base de datos de Exchange y usan el mismo esquema de base de datos. Los elementos se distinguen por una combinación de la propiedad ItemClass , las restricciones de propiedad y las capas de lógica de negocios que afectan a cómo se administran en el almacén de Exchange. En la tabla 1 se muestra cómo se aplican las propiedades a los distintos tipos de elementos; en este ejemplo, elementos de correo electrónico y cita. Ambos elementos tienen un valor para la propiedad Subject . Pero tenga en cuenta que la propiedad IsAllDayEvent no está establecida en el elemento de correo electrónico y que la propiedad IsReadReceiptRequested no está establecida en la cita. Afortunadamente, no es necesario saber qué propiedades son aplicables para cada clase de elemento; EWS controla esto por usted.

Tabla 1. Comparación de las propiedades de cita y correo electrónico

Tipo de elemento Clase Item Asunto IsAllDayEvent IsReadReceiptRequested
Correo electrónico
 IPM.Note
 Informe de estado: Proyecto X completado
 NULL
 true
Cita
 IPM.Appointment
 Reunión de empresa de Contoso
 false
 NULL

El esquema EWS admite muchas de las restricciones administradas por la base de datos de Exchange y las capas de lógica de negocios entre EWS y la base de datos de Exchange. El esquema EWS aplica un conjunto definido de propiedades a cada tipo de elemento. Los siguientes son los elementos de base de datos de Exchange fuertemente tipados proporcionados por EWS:

  • Mensajes de correo electrónico

  • Citas

  • Contactos

  • Listas de distribución

  • Mensajes de reunión

  • Convocatorias de reunión

  • Respuestas de reunión

  • Cancelaciones de reunión

  • Tareas

  • Publicar elementos

EWS devuelve elementos genéricos como mensajes de correo electrónico. La API administrada de EWS implementa todos estos tipos de elementos.

Nota:

Los objetos de respuesta solo los envía el cliente al servidor en respuesta a los elementos recibidos de otras personas. No existen en la base de datos de Exchange.

¿Qué son las propiedades de EWS?

El esquema EWS describe los datos que se envían entre un cliente EWS y Exchange. Una gran parte del esquema describe las propiedades de elemento y carpeta a las que puede acceder en la base de datos de Exchange. El esquema EWS describe la representación XML de las propiedades de base de datos de Exchange que están disponibles para la aplicación. Las propiedades reales, en términos de qué propiedades están disponibles, de qué forma toman y de los valores que devuelven, varían en función de lo que intente hacer. Por ejemplo, la propiedad Body solo devolverá los primeros 512 caracteres de una operación FindItem , pero la operación GetItem devuelve el texto completo del elemento. Aunque la mayoría de las propiedades se pueden establecer y recuperar, Algunas propiedades solo se establecen mediante Exchange. Cada propiedad existe en el esquema en un formato XML que refleja la propiedad tal como se almacena en la base de datos de Exchange o se calcula a partir de las propiedades almacenadas en la base de datos de Exchange. La propiedad Subject es un ejemplo de una propiedad settable; La propiedad UnreadCount de una carpeta es un ejemplo de una propiedad calculada. Un conjunto principal de propiedades son comunes a los tipos de elementos principales.

Los siguientes factores determinan el conjunto de propiedades que la aplicación obtiene de Exchange:

  • La operación a la que llama la aplicación

  • La forma de respuesta base

  • Tipo de elemento

  • Rutas de acceso de propiedad especificadas

Es importante comprender cómo afectan estos diferentes factores a los datos a los que puede acceder. Como en el ejemplo de la propiedad Body mencionada anteriormente, hay información disponible condicionalmente en función de varios factores. Comprender estos factores podría ahorrarle tiempo ayudándole a elegir las opciones correctas para acceder a la información que desea. Para detectar qué propiedades son accesibles, deberá probar estos factores para determinar cómo acceder a las propiedades que necesita la aplicación. En esta sección se describe cómo afectan estos diferentes factores a qué propiedades se devuelven en las respuestas de EWS.

Formas de respuesta de EWS

Exchange almacena una gran cantidad de información sobre los elementos. A veces, la aplicación no necesita toda esa información y, en muchos casos, es mejor no obtenerla todo. Las formas de respuesta de EWS, también denominadas formas de propiedad, indican qué propiedades se devuelven desde el servidor. El elemento principal de la forma de respuesta es la forma base. Una forma base es un contenedor de propiedades preestablecido predeterminado para elementos fuertemente tipados. La API administrada de EWS equivalente a la forma base es BasePropertySet. EWS incluye tres formas de respuesta predeterminadas.

Tabla 2. Formas de respuesta predeterminadas

Nombre de forma de respuesta predeterminado Api administrada de EWS equivalente Descripción
IdOnly
 Valor basePropertySet.IdOnly
 Solo se devuelven el identificador de EWS y la clave de cambio. A menos que el cliente use todas las propiedades devueltas por la forma AllProperties o Default, use la forma IdOnly y especifique propiedades adicionales mediante la ruta de acceso de propiedad establecida en la clase PropertySet . La mayoría de las aplicaciones deben usar la forma de respuesta IdOnly con propiedades adicionales especificadas. Esto reduce la cantidad de datos no utilizados solicitados por los clientes.
Predeterminada
 N/D
 Conjunto de propiedades estándar para el tipo de elemento. Use solo esta forma de respuesta si la aplicación usa todas las propiedades.
AllProperties
 Valor basePropertySet.FirstClassProperties
 Un conjunto mayor de propiedades que la forma Predeterminada. Aunque el nombre lo implica, esta opción no devuelve todas las propiedades de un elemento. Este conjunto de propiedades devuelve las propiedades que las aplicaciones cliente usan con más frecuencia. Si necesita propiedades adicionales, puede solicitarlas por su ruta de acceso de propiedad.
Si la aplicación no usa todas las propiedades devueltas con esta forma de respuesta, use la forma de respuesta IdOnly con propiedades adicionales especificadas.

Muchas operaciones de EWS devuelven elementos y sus propiedades. Independientemente de las formas de respuesta que especifique, las distintas operaciones pueden devolver diferentes conjuntos de propiedades. Los distintos tipos de elementos también devuelven propiedades diferentes, en función de la operación y de la forma de respuesta especificada. Las operaciones siguientes usan formas de respuesta para identificar qué propiedades devolver.

Tabla 3. Operaciones que usan formas de respuesta

Operación de EWS Método de la API administrada de 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
No 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

Las formas de propiedad son una forma rudimentaria de identificar las propiedades que desea que devuelva la aplicación. Sin embargo, a veces, la aplicación necesita un conjunto más refinado de propiedades específicas. Para ello, puede usar la ruta de acceso de la propiedad.

Elección de propiedades por su ruta de acceso de propiedad

Una ruta de acceso de propiedad de EWS es metadatos que se usan para identificar propiedades en una solicitud o respuesta.

Tabla 4. Tipos de ruta de acceso de propiedad

Tipo de ruta de acceso de propiedad Tipo de esquema Implementación de la API administrada de EWS Descripción
FieldUri
 PathToUnindexedFieldType
 Tipos que heredan de ServiceObjectSchema.
La ruta de acceso de propiedad más común. Las rutas de acceso de propiedad FieldUri se especifican en un objeto PropertySet en la API administrada de EWS. La ruta de acceso de la propiedad FieldUri puede especificar la mayoría de las propiedades de EWS. Esto se describe mediante UnindexedFieldURIType en el esquema EWS.
La ruta de acceso de la propiedad FieldUri XML tiene este aspecto:
XML<FieldURI FieldURI="item:Subject"/>Esta ruta de acceso de propiedad es el equivalente de ItemSchema.Subject en la API administrada de EWS.
IndexedFieldUri
 PathToIndexedFieldType
 Tipos que heredan de ItemSchema.
Identifica las propiedades del diccionario que requieren un índice de propiedades para especificar el valor que se va a devolver. Use esta ruta de acceso cuando una propiedad pueda tener más de un valor. Esto se describe mediante la propiedad DictionaryURIType en el esquema EWS. Las rutas de acceso de propiedad DictionaryURIType se especifican en un objeto PropertySet de la API administrada de EWS.
La ruta de acceso de la propiedad IndexedFieldUri XML tiene este aspecto:
XML<IndexedFieldURI FieldURI="contacts:PhysicalAddress:Street FieldIndex="Home"/>
ExtendedFieldUri
 PathToExtendedFieldType
 ExtendedPropertyDefinition
Identifica una definición de propiedad extendida que identifica propiedades personalizadas o no esquematizadas en elementos.
La ruta de acceso de la propiedad ExtendedFieldUri XML tiene este aspecto:
XML<ExtendedFieldURI> PropertyTag="0x1234" PropertyType="Integer" />
ExceptionFieldUri
 ExceptionFieldURI
 ServiceResponse
Especifica las propiedades asociadas a un error en una respuesta de EWS. Esto se describe mediante el tipo ExceptionPropertyURIType en el esquema EWS. Esto solo se produce en el elemento MessageXml de las respuestas de error que se producen cuando se trabaja con patrones de periodicidad de calendario.

Como procedimiento recomendado, cuando solicite propiedades, use la forma base IdOnly (BasePropertySet.IdOnly en la API administrada de EWS) y, a continuación, solicite solo las propiedades que necesita la aplicación especificando las rutas de acceso de propiedad.

Propiedades esquematizadas

El esquema EWS describe la mayoría de las propiedades que necesita el cliente de EWS. Las definiciones de tipo de elemento y carpeta principal, que contienen las definiciones de propiedad, se encuentran en el esquema types.xsd. Los siguientes tipos de esquema contienen las definiciones de propiedad para la mayoría de los objetos que puede usar.

Tabla 5. Tipos de esquema que contienen definiciones de propiedad

Tipo de esquema EWS Tipo de API administrada de EWS equivalente Define el...
ItemType
Clase Item
Conjunto de propiedades de tipo de elemento base. Este tipo se puede crear a partir de un cliente, pero Exchange nunca lo devuelve. Exchange devuelve un objeto MessageType para todos los objetos genéricos.
MessageType
Clase EmailMessage
Email conjunto de propiedades de objeto de mensaje y la propiedad establecida para todos los objetos genéricos.
CalendarItemType
Appointment (clase)
Conjunto de propiedades de elemento de calendario; esto incluye citas únicas y periódicas.
ContactItemType
Clase Contact
Conjunto de propiedades de elemento de contacto.
DistributionListType
Clase ContactGroup
Conjunto de propiedades de lista de distribución personal.
MeetingMessageType
Clase MeetingMessage
Conjunto de propiedades de tipo de mensaje de reunión.
MeetingRequestMessageType
Clase MeetingRequest
Conjunto de propiedades de tipo de solicitud de reunión.
MeetingResponseMessageType
Clase MeetingResponse
Conjunto de propiedades de tipo de respuesta de reunión.
MeetingCancellationMessageType
Clase MeetingCancellation
Conjunto de propiedades de tipo de cancelación de reunión.
TaskType
Clase Task
Conjunto de propiedades de tipo de tarea.
PostItemType
Clase PostItem
Conjunto de propiedades de tipo Postitem.
FolderType
Clase Folder
Conjunto de propiedades de tipo de carpeta.
CalendarFolderType
Clase CalendarFolder
Conjunto de propiedades de tipo SearchFolder.
ContactsFolderType
ContactsFolder (clase)
Conjunto de propiedades de tipo ContactsFolder.
SearchFolderType
SearchFolder (clase)
Conjunto de propiedades de tipo SearchFolder.
TasksFolderType
TasksFolder (clase)
Conjunto de propiedades de tipo TasksFolder.
UserConfigurationType
Clase UserConfiguration
Conjunto de propiedades de tipo UserConfiguration.

Aunque las propiedades del esquema EWS son suficientes para muchas aplicaciones, no se pueden implementar algunos escenarios mediante solo lo que se describe en el esquema. Para esos escenarios, puede ampliar las propiedades.

Propiedades extendidas (también conocidas como propiedades no esquematizadas)

Las propiedades extendidas permiten crear propiedades personalizadas, lo que le da acceso a las propiedades de elementos y carpetas del almacén de Exchange que no están definidas en el esquema EWS. Puede usarlos para acceder a las propiedades nativas de elementos y carpetas MAPI en la base de datos de Exchange. Puede usar propiedades extendidas para tener acceso a todas las propiedades esquematizadas, ya que, en segundo plano, esas propiedades esquematizadas no son más que las propiedades MAPI en la base de datos de Exchange.

El tipo de esquema PathToExtendedFieldType, ubicado en el esquema types.xsd, define el XML que representa una propiedad extendida. Este tipo de esquema define el elemento ExtendedFieldURI en instancias XML; en otras palabras, define el XML que se envía entre el servicio y el cliente. El tipo de esquema ExtendedPropertyType define el elemento ExtendedFieldURI y el valor o matriz de valores que contiene una propiedad extendida. En la tabla siguiente se muestra la asignación aproximada del XML de propiedad extendida y cómo se implementa en los elementos de la API administrada de EWS.

Tabla 6. XML de propiedad extendida, tal como se implementa en la API administrada de EWS

Implementación de la API administrada de EWS Lo que contiene A qué se asigna
Propiedad Item.ExtendedProperties
Colección de propiedades extendidas en un elemento.
Una o varias instancias de propiedades extendidas en un elemento.
ExtendedProperty (clase)
La definición de propiedad extendida y los valores.
Tipo de esquema ExtendedPropertyType.
ExtendedPropertyDefinition (clase)
Definición de propiedad extendida.
Tipo de esquema PathToExtendedFieldType.

Si desea obtener más información sobre cómo puede usar propiedades extendidas en la aplicación, puede explorar los siguientes ejemplos de código:

En esta sección

Vea también