Gérer les paramètres d’application persistants à l’aide d’EWS dans Exchange
Découvrez comment créer, rechercher, obtenir, mettre à jour et supprimer des paramètres d’application persistants à l’aide de l’API managée EWS ou EWS dans Exchange.
Les objets de configuration utilisateur sont la meilleure option pour stocker les paramètres de configuration de votre application cliente Exchange, principalement parce qu’ils sont masqués dans les résultats de recherche dans la plupart des applications clientes. En règle générale, les applications clientes masquent ces paramètres, car l’utilisateur final n’a pas besoin de les voir et pour que l’utilisateur n’accède pas accidentellement à ces informations. Les exemples de code de cet article vous montrent comment utiliser des objets de configuration utilisateur pour gérer les paramètres persistants, notamment comment créer, rechercher, obtenir, mettre à jour et supprimer des paramètres d’application persistants stockés dans des objets de configuration utilisateur.
Créer un paramètre d’application à l’aide de l’API managée EWS
Vous pouvez utiliser la méthode d’API managée UserConfiguration.Save EWS pour créer un paramètre de configuration personnalisé. Un objet de configuration utilisateur peut contenir du code XML, binaire, un dictionnaire de données ou une combinaison de ces trois types de données. L’exemple suivant montre comment enregistrer un objet de configuration utilisateur nommé ContosoDraftSettings qui contient des données binaires dans votre dossier Brouillons à l’aide de l’API managée EWS. Cela peut être utile si vous souhaitez stocker des informations de configuration sur la façon dont les éléments brouillons sont affichés dans votre application cliente.
private static void CreateUserConfiguration(ExchangeService service, byte[] binaryData)
{
// Create the user configuration object.
UserConfiguration configDrafts = new UserConfiguration(service);
// Add user configuration data to the BinaryData property.
configDrafts.BinaryData = binaryData;
// Name and save the user configuration object on the Drafts folder.
// This results in a call to EWS.
configDrafts.Save("ContosoDraftSettings", WellKnownFolderName.Drafts);
}
Créer un paramètre d’application à l’aide d’EWS
Vous pouvez utiliser l’opération EWS CreateUserConfiguration pour créer un paramètre de configuration personnalisé. L’exemple suivant montre le code XML de demande pour la création d’un objet de configuration utilisateur nommé ContosoDraftSettings. La demande tente d’enregistrer un flux binaire dans un objet de configuration utilisateur dans le dossier Brouillons. Il s’agit du même code XML que celui généré par l’exemple d’API managée EWS.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2013" />
</soap:Header>
<soap:Body>
<m:CreateUserConfiguration>
<m:UserConfiguration>
<t:UserConfigurationName Name="ContosoDraftSettings">
<t:DistinguishedFolderId Id="drafts" />
</t:UserConfigurationName>
<t:BinaryData>iVBORw0KGH5UhKquRSzaeAAAAAElFTkSuQmCC</t:BinaryData>
</m:UserConfiguration>
</m:CreateUserConfiguration>
</soap:Body>
</soap:Envelope>
Le xml de réponse est simple et indique si la demande de création a réussi ou si une erreur s’est produite.
Rechercher un paramètre d’application à l’aide de l’API managée EWS
Vous pouvez utiliser la méthode d’API managée EWS Folder.FindItems avec l’option de traversée associée pour rechercher des objets de configuration utilisateur. L’exemple de code suivant montre comment rechercher des objets de configuration utilisateur stockés dans le dossier Brouillons à l’aide de l’API managée EWS.
private static void FindAssociated(ExchangeService service)
{
// This is the ItemClass prefix of user configuration objects that are created by using EWS.
const string userConfigPrefix = "IPM.Configuration.";
// This is the name of a configuration setting created by using EWS.
string userConfigName = "TestConfig";
// Return the first five items.
ItemView view = new ItemView(5);
// Request only the properties that you need. Because all the results will be user configuration
// objects, you won't need to request the ItemSchema.IsAssociated property, which identifies
// user configuration objects.
PropertySet props = new PropertySet(BasePropertySet.IdOnly,
ItemSchema.ItemClass);
view.PropertySet = props;
// Set the traversal to find user configuration objects.
view.Traversal = ItemTraversal.Associated;
// Send the request to search the Drafts folder for all the user configuration objects
// in the folder. You do not have to use a search restriction because you will not return
// a large number of search results. For this scenario, it is better to sort the results
// on the client. This method results in a call to EWS.
FindItemsResults<Item> findResults = service.FindItems(WellKnownFolderName.Drafts, view);
// Output a list of the item classes for the associated items.
foreach (Item item in findResults)
{
if (item.ItemClass == userConfigPrefix + userConfigName)
{
Console.WriteLine("You found the configuration: " + userConfigPrefix + userConfigName);
}
}
}
Rechercher un paramètre d’application à l’aide d’EWS
Vous pouvez utiliser l’opération FindItem EWS pour rechercher des objets de configuration utilisateur.
L’exemple suivant montre le code XML de requête pour rechercher des objets de configuration utilisateur. Il s’agit du même code XML que celui généré par l’exemple d’API managée EWS.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2013" />
</soap:Header>
<soap:Body>
<m:FindItem Traversal="Associated">
<m:ItemShape>
<t:BaseShape>IdOnly</t:BaseShape>
<t:AdditionalProperties>
<t:FieldURI FieldURI="item:ItemClass" />
</t:AdditionalProperties>
</m:ItemShape>
<m:IndexedPageItemView MaxEntriesReturned="5" Offset="0" BasePoint="Beginning" />
<m:ParentFolderIds>
<t:DistinguishedFolderId Id="drafts" />
</m:ParentFolderIds>
</m:FindItem>
</soap:Body>
</soap:Envelope>
L’exemple suivant montre le code XML de réponse réussi pour rechercher des objets de configuration utilisateur. Il s’agit du même code XML que celui traité par l’exemple d’API managée EWS. Notez les éléments suivants dans cette réponse XML :
Nous avons raccourci l’identificateur et modifié les clés pour plus de lisibilité.
Les deux objets de configuration utilisateur sont retournés sous forme de messages. En effet, l’opération FindItem retourne tous les éléments qui ne sont pas définis dans le schéma EWS en tant qu’éléments de message.
Les propriétés ItemClass des deux objets de configuration utilisateur sont différentes. Le premier objet de configuration utilisateur a été créé à l’aide d’EWS. Le deuxième objet a été créé par une autre API.
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ServerVersionInfo MajorVersion="15"
MinorVersion="0"
MajorBuildNumber="800"
MinorBuildNumber="5"
Version="V2_6"
xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<m:FindItemResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:FindItemResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:RootFolder IndexedPagingOffset="2"
TotalItemsInView="2"
IncludesLastItemInRange="true">
<t:Items>
<t:Message>
<t:ItemId Id="AAMkDEY9M6AAA=" ChangeKey="CQAAACYnYF5aFMwP0T" />
<t:ItemClass>IPM.Configuration.TestConfig</t:ItemClass>
</t:Message>
<t:Message>
<t:ItemId Id="AAkADEzOzFAAA=" ChangeKey="CQAAABQAAABAByOw==" />
<t:ItemClass>IPM.Microsoft.FolderDesign.NamedView</t:ItemClass>
</t:Message>
</t:Items>
</m:RootFolder>
</m:FindItemResponseMessage>
</m:ResponseMessages>
</m:FindItemResponse>
</s:Body>
</s:Envelope>
Obtenir et mettre à jour les paramètres d’application à l’aide de l’API managée EWS
Une fois que vous avez trouvé un objet de configuration utilisateur, vous pouvez utiliser la méthode d’API managée UserConfiguration.Bind EWS pour obtenir l’objet de configuration à partir de la boîte aux lettres. Une fois l’objet de configuration obtenu, vous pouvez utiliser la méthode UserConfiguration.Update pour le mettre à jour. L’exemple suivant montre comment obtenir et mettre à jour un objet de configuration utilisateur à l’aide de l’API managée EWS.
private static void GetAndUpdateUserConfiguration(ExchangeService service)
{
// Binds to a user configuration object named "TestConfig" in the user's mailbox.
// Results in a call to EWS. You can also use the Load method to get the latest
// server version of the user configuration object.
UserConfiguration usrConfig = UserConfiguration.Bind(service,
"TestConfig",
WellKnownFolderName.Drafts,
UserConfigurationProperties.All);
// Display the returned configuration object property values.
if (usrConfig.XmlData != null)
{
Console.WriteLine("XmlData: " + Encoding.UTF8.GetString(usrConfig.XmlData));
}
if (usrConfig.BinaryData != null)
{
Console.WriteLine("BinaryData: " + Encoding.UTF8.GetString(usrConfig.BinaryData));
}
if (usrConfig.Dictionary.Count > 0)
{
Console.WriteLine("Contains {0} dictionary entries", usrConfig.Dictionary.Count);
}
// Add dictionary property values to the local copy of the object.
usrConfig.Dictionary.Add("Key5", 1);
// Updates the server version of the user configuration object
// if it has changed on the client. Results in a call to EWS.
if (usrConfig.IsDirty)
{
usrConfig.Update();
}
}
Obtenir et mettre à jour les paramètres d’application à l’aide d’EWS
Vous pouvez utiliser l’opération EWS GetUserConfiguration pour récupérer l’objet de configuration de la boîte aux lettres, et l’opération UpdateUserConfiguration pour mettre à jour l’objet. L’exemple suivant montre le code XML de requête pour obtenir un objet de configuration utilisateur nommé TestConfig. La requête indique que toutes les configurations doivent être retournées dans la réponse. Il s’agit du même code XML que celui généré par l’exemple d’API managée EWS.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2013" />
</soap:Header>
<soap:Body>
<m:GetUserConfiguration>
<m:UserConfigurationName Name="TestConfig">
<t:DistinguishedFolderId Id="drafts" />
</m:UserConfigurationName>
<m:UserConfigurationProperties>All</m:UserConfigurationProperties>
</m:GetUserConfiguration>
</soap:Body>
</soap:Envelope>
L’exemple suivant montre le code XML de réponse réussi pour obtenir des objets de configuration utilisateur. La réponse contient un dictionnaire de données. Il s’agit du même code XML que celui traité par l’exemple d’API managée EWS.
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ServerVersionInfo MajorVersion="15"
MinorVersion="0"
MajorBuildNumber="800"
MinorBuildNumber="5"
Version="V2_6"
xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<m:GetUserConfigurationResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:GetUserConfigurationResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:UserConfiguration>
<t:UserConfigurationName Name="TestConfig">
<t:DistinguishedFolderId Id="drafts" />
</t:UserConfigurationName>
<t:ItemId Id="AAMkDEY9M6AAA=" ChangeKey="CQAAACYnYF5aFMwP0T" />
<t:Dictionary>
<t:DictionaryEntry>
<t:DictionaryKey>
<t:Type>String</t:Type>
<t:Value>Key1</t:Value>
</t:DictionaryKey>
<t:DictionaryValue>
<t:Type>Integer32</t:Type>
<t:Value>1</t:Value>
</t:DictionaryValue>
</t:DictionaryEntry>
<t:DictionaryEntry>
<t:DictionaryKey>
<t:Type>String</t:Type>
<t:Value>PhoneNumber</t:Value>
</t:DictionaryKey>
<t:DictionaryValue>
<t:Type>String</t:Type>
<t:Value>555-555-1111</t:Value>
</t:DictionaryValue>
</t:DictionaryEntry>
</t:Dictionary>
</m:UserConfiguration>
</m:GetUserConfigurationResponseMessage>
</m:ResponseMessages>
</m:GetUserConfigurationResponse>
</s:Body>
</s:Envelope>
L’exemple suivant montre le code XML de demande pour la mise à jour d’un objet de configuration utilisateur. La requête indique que toutes les configurations doivent être retournées dans la réponse. Il s’agit du même code XML que celui généré par l’exemple d’API managée EWS qui appelle la méthode UserConfiguration.Update . Vous pouvez voir que le code XML de mise à jour contient les entrées de dictionnaire existantes et l’entrée supplémentaire qui a été ajoutée avant la mise à jour.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2013" />
</soap:Header>
<soap:Body>
<m:UpdateUserConfiguration>
<m:UserConfiguration>
<t:UserConfigurationName Name="TestConfig">
<t:DistinguishedFolderId Id="drafts" />
</t:UserConfigurationName>
<t:Dictionary>
<t:DictionaryEntry>
<t:DictionaryKey>
<t:Type>String</t:Type>
<t:Value>Key1</t:Value>
</t:DictionaryKey>
<t:DictionaryValue>
<t:Type>Integer32</t:Type>
<t:Value>1</t:Value>
</t:DictionaryValue>
</t:DictionaryEntry>
<t:DictionaryEntry>
<t:DictionaryKey>
<t:Type>String</t:Type>
<t:Value>PhoneNumber</t:Value>
</t:DictionaryKey>
<t:DictionaryValue>
<t:Type>String</t:Type>
<t:Value>555-555-1111</t:Value>
</t:DictionaryValue>
</t:DictionaryEntry>
<t:DictionaryEntry>
<t:DictionaryKey>
<t:Type>String</t:Type>
<t:Value>Key5</t:Value>
</t:DictionaryKey>
<t:DictionaryValue>
<t:Type>Integer32</t:Type>
<t:Value>1</t:Value>
</t:DictionaryValue>
</t:DictionaryEntry>
</t:Dictionary>
</m:UserConfiguration>
</m:UpdateUserConfiguration>
</soap:Body>
</soap:Envelope>
Le code XML de la réponse est simple et indique si la mise à jour a réussi ou si une erreur s’est produite.
Supprimer un paramètre d’application à l’aide de l’API managée EWS
Vous pouvez utiliser la méthode d’API managée UserConfiguration.Delete EWS pour supprimer des objets de configuration utilisateur. L’exemple de code suivant montre comment supprimer l’objet de configuration utilisateur ContosoDraftSettings à l’aide de l’API managée EWS.
private static void DeleteUserConfiguration(ExchangeService service)
{
// Binds to a user configuration object. Results in a call to EWS.
UserConfiguration usrConfig = UserConfiguration.Bind(service,
"ContosoDraftSettings",
WellKnownFolderName.Drafts,
UserConfigurationProperties.Id);
// Deletes the user configuration object.
// Results in a call to EWS.
usrConfig.Delete();
}
Supprimer un paramètre d’application à l’aide d’EWS
Vous pouvez utiliser l’opération EWS DeleteUserConfiguration pour supprimer des objets de configuration utilisateur.
L’exemple suivant montre le code XML de demande pour la suppression d’un objet de configuration utilisateur nommé ContosoDraftSettings qui a été appliqué au dossier Drafts. Il s’agit du même code XML que celui généré par l’exemple d’API managée EWS.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2013" />
</soap:Header>
<soap:Body>
<m:DeleteUserConfiguration>
<m:UserConfigurationName Name="ContosoDraftSettings">
<t:DistinguishedFolderId Id="drafts" />
</m:UserConfigurationName>
</m:DeleteUserConfiguration>
</soap:Body>
</soap:Envelope>
Le code XML de réponse est simple et indique si la demande de suppression a réussi ou si une erreur s’est produite.