Persistente Anwendungseinstellungen mithilfe von EWS in Exchange verwalten
Erfahren Sie, wie Sie permanente Anwendungseinstellungen mithilfe der verwalteten EWS-API oder EWS in Exchange erstellen, suchen, abrufen, aktualisieren und löschen.
Benutzerkonfigurationsobjekte sind die beste Option zum Speichern von Konfigurationseinstellungen für Ihre Exchange-Clientanwendung, hauptsächlich weil sie in den Suchergebnissen in den meisten Clientanwendungen ausgeblendet sind. Clientanwendungen blenden diese Einstellungen in der Regel aus, da der Endbenutzer sie nicht sehen muss und der Benutzer nicht versehentlich auf diese Informationen zugreift. Die Codebeispiele in diesem Artikel zeigen Ihnen, wie Sie Benutzerkonfigurationsobjekte verwenden können, um persistente Einstellungen zu verwalten, einschließlich des Erstellens, Suchens, Abrufens, Aktualisierens und Löschens persistenter Anwendungseinstellungen, die in Benutzerkonfigurationsobjekten gespeichert sind.
Erstellen einer Anwendungseinstellung mithilfe der verwalteten EWS-API
Sie können die Methode UserConfiguration.Save verwaltete EWS-API verwenden, um eine benutzerdefinierte Konfigurationseinstellung zu erstellen. Ein Benutzerkonfigurationsobjekt kann XML, Binärdateien, ein Datenwörterbuch oder eine Kombination dieser drei Datentypen enthalten. Das folgende Beispiel zeigt, wie Sie ein Benutzerkonfigurationsobjekt mit dem Namen ContosoDraftSettings, das Binärdaten enthält, mithilfe der verwalteten EWS-API in Ihrem Ordner Drafts speichern. Dies kann nützlich sein, wenn Sie Konfigurationsinformationen darüber speichern möchten, wie Entwurfselemente in Ihrer Clientanwendung angezeigt werden.
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);
}
Erstellen einer Anwendungseinstellung mithilfe von EWS
Sie können den EWS-Vorgang CreateUserConfiguration verwenden, um eine benutzerdefinierte Konfigurationseinstellung zu erstellen. Das folgende Beispiel zeigt die Anforderungs-XML zum Erstellen eines Benutzerkonfigurationsobjekts mit dem Namen ContosoDraftSettings. Die Anforderung versucht, einen binärdatenstrom in einem Benutzerkonfigurationsobjekt im Ordner Drafts zu speichern. Dies ist derselbe XML-Code, der vom EwS Managed API-Beispiel generiert wird.
<?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>
Die Antwort-XML ist einfach und gibt an, ob die Erstellungsanforderung erfolgreich war oder ob ein Fehler aufgetreten ist.
Suchen einer Anwendungseinstellung mithilfe der verwalteten EWS-API
Sie können die Folder.FindItems EWS Managed API-Methode mit der zugehörigen Durchlaufoption verwenden, um Benutzerkonfigurationsobjekte zu finden. Im folgenden Codebeispiel wird gezeigt, wie Sie mithilfe der verwalteten EWS-API nach Benutzerkonfigurationsobjekten suchen, die im Ordner Entwürfe gespeichert sind.
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);
}
}
}
Suchen einer Anwendungseinstellung mithilfe von EWS
Sie können den EWS-Vorgang FindItem verwenden, um Benutzerkonfigurationsobjekte zu suchen.
Das folgende Beispiel zeigt die Anforderungs-XML zum Suchen von Benutzerkonfigurationsobjekten. Dies ist derselbe XML-Code, der vom EwS Managed API-Beispiel generiert wird.
<?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>
Das folgende Beispiel zeigt die erfolgreiche Antwort-XML zum Suchen von Benutzerkonfigurationsobjekten. Dies ist derselbe XML-Code, der im Beispiel für die verwaltete EWS-API verarbeitet wird. Beachten Sie Folgendes in dieser Antwort-XML:
Wir haben den Bezeichner und die Änderungsschlüssel aus Gründen der Lesbarkeit gekürzt.
Die beiden Benutzerkonfigurationsobjekte werden als Nachrichten zurückgegeben. Dies liegt daran, dass der FindItem-Vorgang alle Elemente zurückgibt, die nicht im EWS-Schema als Nachrichtenelemente definiert sind.
Die ItemClass-Eigenschaften für die beiden Benutzerkonfigurationsobjekte unterscheiden sich. Das erste Benutzerkonfigurationsobjekt wurde mithilfe von EWS erstellt. Das zweite Objekt wurde von einer anderen API erstellt.
<?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>
Abrufen und Aktualisieren von Anwendungseinstellungen mithilfe der verwalteten EWS-API
Nachdem Sie ein Benutzerkonfigurationsobjekt gefunden haben, können Sie die verwaltete EWS-API-Methode UserConfiguration.Bind verwenden, um das Konfigurationsobjekt aus dem Postfach abzurufen. Nachdem Sie das Konfigurationsobjekt abgerufen haben, können Sie es mithilfe der UserConfiguration.Update-Methode aktualisieren. Das folgende Beispiel zeigt, wie Sie ein Benutzerkonfigurationsobjekt mithilfe der verwalteten EWS-API abrufen und aktualisieren.
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();
}
}
Abrufen und Aktualisieren von Anwendungseinstellungen mithilfe von EWS
Sie können den EWS-Vorgang GetUserConfiguration verwenden, um das Konfigurationsobjekt aus dem Postfach abzurufen, und updateUserConfiguration , um das Objekt zu aktualisieren. Das folgende Beispiel zeigt die Anforderungs-XML zum Abrufen eines Benutzerkonfigurationsobjekts mit dem Namen TestConfig. Die Anforderung gibt an, dass alle Konfigurationen in der Antwort zurückgegeben werden sollen. Dies ist derselbe XML-Code, der vom EwS Managed API-Beispiel generiert wird.
<?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>
Das folgende Beispiel zeigt die erfolgreiche Antwort-XML zum Abrufen von Benutzerkonfigurationsobjekten. Die Antwort enthält ein Datenwörterbuch. Dies ist derselbe XML-Code, der im Beispiel für die verwaltete EWS-API verarbeitet wird.
<?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>
Das folgende Beispiel zeigt die Anforderungs-XML zum Aktualisieren eines Benutzerkonfigurationsobjekts. Die Anforderung gibt an, dass alle Konfigurationen in der Antwort zurückgegeben werden sollen. Dies ist derselbe XML-Code, der vom EwS Managed API-Beispiel generiert wird, das die UserConfiguration.Update-Methode aufruft. Sie können sehen, dass die XML-Aktualisierung die vorhandenen Wörterbucheinträge und den zusätzlichen enthält, der vor dem Update hinzugefügt wurde.
<?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>
Die Antwort-XML ist einfach und gibt an, ob das Update erfolgreich war oder ob ein Fehler aufgetreten ist.
Löschen einer Anwendungseinstellung mithilfe der verwalteten EWS-API
Sie können die Verwaltete EWS-API-Methode UserConfiguration.Delete verwenden, um Benutzerkonfigurationsobjekte zu löschen. Im folgenden Codebeispiel wird gezeigt, wie Sie das Benutzerkonfigurationsobjekt ContosoDraftSettings mithilfe der verwalteten EWS-API löschen.
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();
}
Löschen einer Anwendungseinstellung mithilfe von EWS
Sie können den EWS-Vorgang DeleteUserConfiguration verwenden, um Benutzerkonfigurationsobjekte zu löschen.
Das folgende Beispiel zeigt die Anforderungs-XML zum Löschen eines Benutzerkonfigurationsobjekts namens ContosoDraftSettings, das auf den Ordner Entwürfe angewendet wurde. Dies ist derselbe XML-Code, der vom EwS Managed API-Beispiel generiert wird.
<?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>
Die Antwort-XML ist einfach und gibt an, ob die Löschanforderung erfolgreich war oder ob ein Fehler aufgetreten ist.