Les propriétés et les propriétés étendues dans EWS dans Exchange

  • Article

Découvrez comment définir des propriétés sur des éléments et des dossiers et y accéder à l’aide d’EWS dans Exchange.

Une boîte aux lettres Exchange contient un grand nombre d’éléments, notamment des messages électroniques, des rendez-vous, des réunions, etc. Ces éléments sont constitués de propriétés ; les propriétés décrivent les éléments. Vous pouvez utiliser les propriétés d’élément pour effectuer une recherche, synchroniser les modifications d’élément et créer des types de propriétés personnalisés. Cet article fournit une vue d’ensemble des propriétés et de la façon dont vous pouvez utiliser les propriétés dans votre application.

Propriétés de l’élément Exchange

Les éléments et les dossiers dans Exchange sont essentiellement des lignes dans des tables. La propriété principale qui identifie un élément ou un dossier est son identificateur EWS. Bien qu’il existe d’autres propriétés liées aux identificateurs dans la base de données Exchange, pour EWS, l’identificateur EWS fait office de clé primaire pour la collection de propriétés qui décrivent un élément. La propriété d’identificateur EWS contient deux parties :

  • Propriété ItemId ou FolderId qui identifie l’élément

  • Propriété ChangeKey qui contient des informations avec état indiquant si un élément ou un dossier a été modifié

Tous les éléments d’une boîte aux lettres sont stockés dans la même base de données Exchange et utilisent le même schéma de base de données. Les éléments se distinguent par une combinaison de la propriété ItemClass , des contraintes de propriété et des couches de logique métier qui affectent la façon dont ils sont gérés dans le magasin Exchange. Le tableau 1 montre comment les propriétés sont appliquées à différents types d’éléments . dans cet exemple, les éléments de courrier électronique et de rendez-vous. Les deux éléments ont une valeur pour la propriété Subject . Notez toutefois que la propriété IsAllDayEvent n’est pas définie sur l’élément de messagerie et que la propriété IsReadReceiptRequested n’est pas définie sur le rendez-vous. Heureusement, vous n’avez pas besoin de savoir quelles propriétés sont applicables pour chaque classe d’élément ; EWS gère cela pour vous.

Tableau 1. Comparaison des propriétés de rendez-vous et d’e-mail

Type d’élément Item, classe Sujet IsAllDayEvent IsReadReceiptRequested
E-mail
 Ipm. Note
 Rapport d’état : Projet X terminé
 NULL
 true
Rendez-vous
 Ipm. Nomination
 Réunion d’entreprise Contoso
 false
 NULL

Le schéma EWS prend en charge la plupart des contraintes gérées par la base de données Exchange et les couches de logique métier entre EWS et la base de données Exchange. Le schéma EWS applique un ensemble défini de propriétés à chaque type d’élément. Voici les éléments de base de données Exchange fortement typés fournis par EWS :

  • Messages électroniques

  • Rendez-vous

  • Contacts

  • Listes de distribution

  • Messages de réunion

  • Demandes de réunion

  • Réponses aux réunions

  • Annulations de rendez-vous

  • Tâches

  • Publier des éléments

Les éléments génériques sont retournés par EWS sous forme de messages électroniques. L’API managée EWS implémente tous ces types d’éléments.

Remarque

Les objets Response sont uniquement envoyés par le client au serveur en réponse aux éléments reçus d’autres personnes. Ils n’existent pas dans la base de données Exchange.

Que sont les propriétés dans EWS ?

Le schéma EWS décrit les données envoyées entre un client EWS et Exchange. Une grande partie du schéma décrit les propriétés d’élément et de dossier auxquelles vous pouvez accéder dans la base de données Exchange. Le schéma EWS décrit la représentation XML des propriétés de base de données Exchange disponibles pour votre application. Les propriétés réelles, en termes de propriétés disponibles, de la forme qu’elles prennent et des valeurs qu’elles retournent, varient en fonction de ce que vous essayez de faire. Par exemple, la propriété Body renvoie uniquement les 512 premiers caractères d’une opération FindItem , mais l’opération GetItem renvoie le texte intégral de l’élément. Bien que la plupart des propriétés soient à la fois définissables et récupérables, certaines propriétés ne sont définies que par Exchange. Chaque propriété existe dans le schéma dans un format XML qui reflète la propriété telle qu’elle est stockée dans la base de données Exchange ou est calculée à partir de propriétés stockées dans la base de données Exchange. La propriété Subject est un exemple de propriété pouvant être définie . La propriété UnreadCount d’un dossier est un exemple de propriété calculée. Un ensemble principal de propriétés est commun aux types d’éléments principaux.

Les facteurs suivants déterminent le jeu de propriétés que votre application obtient d’Exchange :

  • Opération que votre application appelle

  • Forme de réponse de base

  • Type d’élément

  • Chemins de propriété spécifiés

Il est important de comprendre comment ces différents facteurs affectent les données auxquelles vous pouvez accéder. Comme pour l’exemple de la propriété Body mentionnée précédemment, certaines informations sont disponibles de manière conditionnelle en fonction de différents facteurs. La compréhension de ces facteurs peut vous faire gagner du temps en vous aidant à choisir les options appropriées pour accéder aux informations souhaitées. Pour découvrir quelles propriétés sont accessibles, vous devez tester ces facteurs afin de déterminer comment accéder aux propriétés dont votre application a besoin. Cette section décrit comment ces différents facteurs affectent les propriétés retournées dans les réponses EWS.

Formes de réponse EWS

Exchange stocke un grand nombre d’informations sur les éléments. Parfois, votre application n’a pas besoin de toutes ces informations, et dans de nombreux cas, il est préférable de ne pas tout obtenir. Les formes de réponse EWS, également appelées formes de propriété, indiquent les propriétés retournées par le serveur. L’élément principal de la forme de réponse est la forme de base. Une forme de base est un conteneur de propriétés prédéfinies par défaut pour les éléments fortement typés. L’équivalent de l’API managée EWS de la forme de base est BasePropertySet. EWS comprend trois formes de réponse par défaut.

Tableau 2. Formes de réponse par défaut

Nom de la forme de réponse par défaut Équivalent de l’API managée EWS Description
IdOnly
 Valeur BasePropertySet.IdOnly
 Seuls l’identificateur EWS et la clé de modification sont retournés. À moins que le client n’utilise toutes les propriétés retournées par la forme AllProperties ou Default, utilisez la forme IdOnly et spécifiez des propriétés supplémentaires à l’aide du chemin d’accès de propriété défini sur la classe PropertySet . La plupart des applications doivent utiliser la forme de réponse IdOnly avec des propriétés supplémentaires spécifiées. Cela réduit la quantité de données inutilisées demandées par les clients.
Valeur par défaut
 S/O
 Ensemble de propriétés standard pour le type d’élément. Utilisez cette forme de réponse uniquement si votre application utilise toutes les propriétés.
AllProperties
 Valeur BasePropertySet.FirstClassProperties
 Ensemble de propriétés plus grand que la forme par défaut. Bien que le nom l’indique, cette option ne retourne pas toutes les propriétés d’un élément. Cet ensemble de propriétés retourne les propriétés que les applications clientes utilisent le plus souvent. Si vous avez besoin de propriétés supplémentaires, vous pouvez les demander par leur chemin de propriété.
Si votre application n’utilise pas toutes les propriétés retournées avec cette forme de réponse, utilisez la forme de réponse IdOnly avec des propriétés supplémentaires spécifiées.

De nombreuses opérations EWS retournent des éléments et leurs propriétés. Quelles que soient les formes de réponse que vous spécifiez, différentes opérations peuvent retourner différents jeux de propriétés. Différents types d’éléments retournent également des propriétés différentes, en fonction de l’opération et de la forme de réponse spécifiée. Les opérations suivantes utilisent des formes de réponse pour identifier les propriétés à retourner.

Tableau 3. Opérations qui utilisent des formes de réponse

Opération EWS Méthode d'API managée EWS
GetConversationItems
Méthode ExchangeService.GetConversationItems
GetFolder
Folder.Bind, méthode
GetItem
Item.Bind, méthode
Méthode ExchangeService.BindToItems
FindConversation
Méthode ExchangeService.FindConversation
FindFolder
Méthode Folder.FindFolders
Méthode ExchangeService.FindFolders
FindItem
Méthode Folder.FindItems
Méthode ExchangeService.FindItems
FindPeople
Non implémenté.
ResolveNames
Méthode ExchangeService.ResolveNames
SearchMailboxes
Méthode ExchangeService.SearchMailboxes
Méthode ExchangeService.BeginSearchMailboxes
SyncFolderHierarchy
Méthode ExchangeService.SyncFolderHierarchy
SyncFolderItems
Méthode ExchangeService.SyncFolderItems

Les formes de propriété sont un moyen rudimentaire d’identifier les propriétés que vous souhaitez que votre application retourne. Toutefois, votre application a parfois besoin d’un ensemble plus affiné de propriétés spécifiques. Pour cela, vous pouvez utiliser le chemin de propriété .

Choisir des propriétés par chemin d’accès de propriété

Un chemin de propriété EWS est des métadonnées utilisées pour identifier les propriétés dans une demande ou une réponse.

Tableau 4. Types de chemins d’accès aux propriétés

Type de chemin d’accès à la propriété Type de schéma Implémentation de l’API managée EWS Description
FieldUri
 PathToUnindexedFieldType
 Types qui héritent de ServiceObjectSchema.
Chemin de propriété le plus courant. Les chemins de propriété FieldUri sont spécifiés sur un objet PropertySet dans l’API managée EWS. La plupart des propriétés EWS peuvent être spécifiées par le chemin de propriété FieldUri. Cela est décrit par un unindexedFieldURIType dans le schéma EWS.
Le xml du chemin d’accès à la propriété FieldUri se présente comme suit :
XML<FieldURI FieldURI="item:Subject"/>Ce chemin de propriété est l’équivalent de ItemSchema.Subject dans l’API managée EWS.
IndexedFieldUri
 PathToIndexedFieldType
 Types qui héritent de ItemSchema.
Identifie les propriétés de dictionnaire qui nécessitent un index de propriété pour spécifier la valeur à retourner. Utilisez ce chemin lorsqu’une propriété peut avoir plusieurs valeurs. Cela est décrit par la propriété DictionaryURIType dans le schéma EWS. Les chemins de propriété DictionaryURIType sont spécifiés sur un objet PropertySet dans l’API managée EWS.
Le chemin d’accès à la propriété IndexedFieldUri se présente comme suit :
XML<IndexedFieldURI FieldURI="contacts:PhysicalAddress:Street FieldIndex="Home"/>
ExtendedFieldUri
 PathToExtendedFieldType
 ExtendedPropertyDefinition
Identifie une définition de propriété étendue qui identifie les propriétés personnalisées ou non schématisées sur les éléments.
Le code XML du chemin de propriété ExtendedFieldUri ressemble à ceci :
XML<ExtendedFieldURI> PropertyTag="0x1234" PropertyType="Integer" />
ExceptionFieldUri
 ExceptionFieldURI
 ServiceResponse
Spécifie les propriétés associées à une erreur dans une réponse EWS. Cela est décrit par le type ExceptionPropertyURIType dans le schéma EWS. Cela se produit uniquement dans l’élément MessageXml des réponses d’erreur qui se produisent lorsque vous utilisez des modèles de périodicité de calendrier.

En guise de bonne pratique, lorsque vous demandez des propriétés, utilisez la forme de base IdOnly (BasePropertySet.IdOnly dans l’API managée EWS), puis demandez uniquement les propriétés dont votre application a besoin en spécifiant les chemins de propriété.

Propriétés schématisées

La plupart des propriétés dont votre client EWS a besoin sont décrites par le schéma EWS. Les définitions de dossier principal et de type d’élément, qui contiennent les définitions de propriété, se trouvent dans le schéma types.xsd. Les types de schéma suivants contiennent les définitions de propriété de la plupart des objets que vous pouvez utiliser.

Tableau 5. Types de schémas qui contiennent des définitions de propriété

Type de schéma EWS Équivalent du type d’API managée EWS Définit le...
ItemType
Item, classe
Jeu de propriétés de type d’élément de base. Ce type peut être créé à partir d’un client, mais n’est jamais retourné par Exchange. Exchange renvoie un objet MessageType pour tous les objets génériques.
MessageType
Classe EmailMessage
Email jeu de propriétés d’objet message et de propriété pour tous les objets génériques.
CalendarItemType
Classe Appointment
Jeu de propriétés d’élément de calendrier ; cela inclut les rendez-vous uniques et périodiques.
ContactItemType
Classe contact
Jeu de propriétés d’élément de contact.
DistributionListType
Classe ContactGroup
Ensemble de propriétés de liste de distribution personnelles.
MeetingMessageType
Classe MeetingMessage
Ensemble de propriétés de type de message de réunion.
MeetingRequestMessageType
Classe MeetingRequest
Ensemble de propriétés de type de demande de réunion.
MeetingResponseMessageType
Classe MeetingResponse
Ensemble de propriétés de type de réponse de réunion.
MeetingCancellationMessageType
Classe MeetingCancellation
Ensemble de propriétés de type d’annulation de réunion.
TaskType
Classe Task
Jeu de propriétés de type de tâche.
PostItemType
PostItem, classe
Jeu de propriétés de type Postitem.
FolderType
Classe Folder
Jeu de propriétés de type de dossier.
CalendarFolderType
Classe CalendarFolder
Jeu de propriétés de type SearchFolder.
ContactsFolderType
ContactsFolder, classe
Jeu de propriétés de type ContactsFolder.
SearchFolderType
Classe SearchFolder
Jeu de propriétés de type SearchFolder.
TasksFolderType
Classe TasksFolder
Jeu de propriétés de type TasksFolder.
UserConfigurationType
Classe UserConfiguration
Jeu de propriétés de type UserConfiguration.

Bien que les propriétés du schéma EWS soient suffisantes pour de nombreuses applications, vous ne pouvez pas implémenter certains scénarios en utilisant uniquement ce qui est décrit dans le schéma. Pour ces scénarios, vous pouvez étendre les propriétés.

Propriétés étendues (également appelées propriétés non schématisées)

Les propriétés étendues vous permettent de créer des propriétés personnalisées, qui vous donnent accès aux propriétés des éléments et dossiers du magasin Exchange qui ne sont pas définis dans le schéma EWS. Vous pouvez les utiliser pour accéder aux propriétés natives de l’élément MAPI et du dossier dans la base de données Exchange. Vous pouvez utiliser des propriétés étendues pour accéder à toutes les propriétés schématisées, car sous les couvertures, ces propriétés schématisées ne sont rien de plus que des propriétés MAPI dans la base de données Exchange.

Le type de schéma PathToExtendedFieldType, situé dans le schéma types.xsd, définit le code XML qui représente une propriété étendue. Ce type de schéma définit l’élément ExtendedFieldURI dans les instances XML ; en d’autres termes, il définit le code XML envoyé entre le service et le client. Le type de schéma ExtendedPropertyType définit à la fois l’élément ExtendedFieldURI et la valeur ou le tableau de valeurs qu’une propriété étendue contient. Le tableau suivant présente le mappage approximatif de la propriété étendue XML et la façon dont il est implémenté sur les éléments de l’API managée EWS.

Tableau 6. Xml de propriété étendue implémentée dans l’API managée EWS

Implémentation de l’API managée EWS Ce qu’il contient Ce à quoi il correspond
Propriété Item.ExtendedProperties
Collection de propriétés étendues sur un élément.
Une ou plusieurs instances de propriétés étendues sur un élément.
Classe ExtendedProperty
Définition et valeurs de propriété étendues.
Type de schéma ExtendedPropertyType.
Classe ExtendedPropertyDefinition
Définition de propriété étendue.
Type de schéma PathToExtendedFieldType.

Si vous souhaitez en savoir plus sur l’utilisation des propriétés étendues dans votre application, vous pouvez explorer les exemples de code suivants :

Dans cette section

Voir aussi