Управление настойчивыми настройками приложений с помощью EWS в Exchange
Узнайте, как создавать, находить, получать, обновлять и удалять настойчивые параметры приложений с помощью управляемого API или EWS EWS в Exchange.
Объекты конфигурации пользователей — это оптимальный вариант для хранения параметров конфигурации для Exchange клиентского приложения, в первую очередь потому, что они скрыты от результатов поиска в большинстве клиентских приложений. Клиентские приложения обычно скрывают эти параметры, так как конечный пользователь не должен их видеть, и чтобы пользователь не случайно мог получить доступ к этой информации. В примерах кода в этой статье покажите, как можно использовать объекты конфигурации пользователей для управления настойчивыми настройками, в том числе для создания, поиска, получения, обновления и удаления настойчивых параметров приложений, хранимых в объектах конфигурации пользователей.
Создание параметра приложения с помощью управляемого API EWS
Для создания настраиваемого параметра конфигурации можно использовать метод UserConfiguration.Save метод управляемого API EWS. Объект конфигурации пользователя может содержать XML, двоичный, словарь данных или сочетание этих трех типов данных. В следующем примере показано, как сохранить объект конфигурации пользователя с именем ContosoDraftSettings, который содержит двоичные данные в папку Drafts с помощью управляемого API EWS. Это может быть полезно, если вы хотите сохранить сведения о конфигурации, как отображаются черновики элементов в клиентских приложениях.
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);
}
Создание параметра приложения с помощью EWS
Вы можете использовать операцию CreateUserConfiguration EWS для создания настраиваемой настройки конфигурации. В следующем примере показан XML запроса для создания объекта конфигурации пользователя с именем ContosoDraftSettings. Запрос пытается сохранить двоичный поток для объекта конфигурации пользователя в папке Drafts. Это тот же XML, который создается в примере управляемого API EWS.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://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>
XML-ответ прост и указывает, был ли запрос на создание успешным или произошла ошибка.
Поиск параметра приложения с помощью управляемого API EWS
Чтобы найти объекты конфигурации пользователя, можно использовать метод Управляемый API Folder.FindItems EWS с связанной опцией обхода. В следующем примере кода показано, как найти объекты конфигурации пользователей, хранимые в папке Drafts с помощью API управляемых 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);
}
}
}
Поиск параметра приложения с помощью EWS
Вы можете использовать операцию FindItem EWS для поиска объектов конфигурации пользователей.
В следующем примере показан XML запроса для поиска объектов конфигурации пользователей. Это тот же XML, который создается в примере управляемого API EWS.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://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>
В следующем примере показан XML успешного отклика для поиска объектов конфигурации пользователей. Это тот же XML, который обрабатывается в примере управляемого API EWS. Обратите внимание на следующее в этом ответе XML:
Мы сократили идентификатор и изменили ключи для чтения.
Два объекта конфигурации пользователя возвращаются в качестве сообщений. Это потому, что операция FindItem возвращает все элементы, которые не определены в схеме EWS в качестве элементов сообщений.
Свойства ItemClass для двух объектов конфигурации пользователей отличаются. Первый объект конфигурации пользователя был создан с помощью EWS. Второй объект был создан другим 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="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns="https://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="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://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>
Получение и обновление параметров приложений с помощью управляемого API EWS
После поиска объекта конфигурации пользователя можно использовать метод UserConfiguration.Bind EWS Managed API для получения объекта конфигурации из почтового ящика. После получения объекта конфигурации для его обновления можно использовать метод UserConfiguration.Update. В следующем примере показано, как получить и обновить объект конфигурации пользователя с помощью управляемого API 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();
}
}
Получение и обновление параметров приложений с помощью EWS
Для получения объекта конфигурации из почтового ящика можно использовать операцию GetUserConfiguration EWS и updateUserConfiguration для обновления объекта. В следующем примере показан XML запроса для получения объекта конфигурации пользователя с именем TestConfig. В запросе говорится, что все конфигурации должны быть возвращены в ответе. Это тот же XML, который создается в примере управляемого API EWS.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://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>
В следующем примере показан XML успешного отклика для получения объектов конфигурации пользователя. Ответ содержит словарь данных. Это тот же XML, который обрабатывается в примере управляемого API 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="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns="https://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="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://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>
В следующем примере показан XML запроса для обновления объекта конфигурации пользователя. В запросе говорится, что все конфигурации должны быть возвращены в ответе. Это тот же XML, который создается в примере управляемого API EWS, который вызывает метод UserConfiguration.Update. Вы можете видеть, что XML обновления содержит существующие записи словаря и дополнительные, которые были добавлены перед обновлением.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://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>
XML ответа прост и указывает, было ли обновление успешным или произошла ошибка.
Удаление параметра приложения с помощью управляемого API EWS
Для удаления объектов конфигурации пользователей можно использовать метод UserConfiguration.Delete EWS Managed API. В следующем примере кода показано, как удалить объект конфигурации пользователя ContosoDraftSettings с помощью управляемого API 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();
}
Удаление параметра приложения с помощью EWS
Для удаления объектов конфигурации пользователей можно использовать операцию DeleteUserConfiguration EWS.
В следующем примере показан XML запроса на удаление объекта конфигурации пользователя с именем ContosoDraftSettings, который был применен к папке Drafts. Это тот же XML, который создается в примере управляемого API EWS.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://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>
XML-ответ прост и указывает, был ли запрос на удаление успешным или произошла ошибка.