Управление параметрами сохраняемого приложения с помощью EWS в ExchangeManage persistent application settings by using EWS in Exchange

Узнайте, как создавать, искать, получать, обновлять и удалять параметры сохраняемого приложения с помощью управляемого API EWS или EWS в Exchange.Learn how to create, find, get, update, and delete persistent application settings by using the EWS Managed API or EWS in Exchange.

Объекты конфигурации пользователя — это оптимальный способ хранения параметров конфигурации для клиентского приложения Exchange, в основном потому, что они скрыты от результатов поиска в большинстве клиентских приложений.User configuration objects are the best option for storing configuration settings for your Exchange client application, primarily because they are hidden from search results in most client applications. Как правило, клиентские приложения скрывают эти параметры, так как конечный пользователь не видит их, а пользователь случайно не получает доступ к этой информации.Client applications typically hide these settings because the end user doesn't need to see them, and so that the user doesn't accidentally access this information. В примерах кода, приведенных в этой статье, показано, как можно использовать объекты конфигурации пользователей для управления сохраняемыми параметрами, включая создание, поиск, получение, обновление и удаление параметров постоянного приложения, хранящихся в пользовательских объектах конфигурации.The code examples in this article show you how you can use user configuration objects to manage persistent settings, including how to create, find, get, update, and delete persistent application settings that are stored in user configuration objects.

Создание параметра приложения с помощью управляемого API EWSCreate an application setting by using the EWS Managed API

Для создания настраиваемого параметра конфигурации можно использовать метод усерконфигуратион. Save для управляемого API EWS.You can use the UserConfiguration.Save EWS Managed API method to create a custom configuration setting. Объект конфигурации пользователя может содержать XML-файл, двоичный код, словарь данных или сочетание этих трех типов данных.A user configuration object can contain XML, binary, a data dictionary, or a combination of those three data types. В приведенном ниже примере показано, как сохранить объект конфигурации пользователя с именем Контосодрафтсеттингс, который содержит двоичные данные в папке "Черновики", с помощью управляемого API EWS.The following example shows how to save a user configuration object named ContosoDraftSettings that contains binary data to your Drafts folder by using the EWS Managed API. Это может быть полезно, если вы хотите хранить сведения о конфигурации для отображения элементов черновиков в клиентском приложении.This might be useful if you want to store configuration information about how draft items are displayed in your client application.

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);
}

Создание параметра приложения с помощью EWSCreate an application setting by using EWS

Для создания настраиваемых параметров конфигурации можно использовать операцию CreateUserConfiguration EWS.You can use the CreateUserConfiguration EWS operation to create a custom configuration setting. В следующем примере показан XML-код запроса для создания объекта конфигурации пользователя с именем Контосодрафтсеттингс.The following example shows the request XML for creating a user configuration object named ContosoDraftSettings. Запрос пытается сохранить двоичный поток в объект конфигурации пользователя в папке "Черновики".The request attempts to save a binary stream to a user configuration object on the Drafts folder. Это тот же XML-код, который создается в примере управляемого API EWS.This is the same XML that is generated by the EWS Managed API example.

<?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 является простым и указывает, был ли запрос на создание успешным или возникла ошибка.The response XML is simple and indicates whether the create request was successful or whether an error occurred.

Поиск параметра приложения с помощью управляемого API EWSFind an application setting by using the EWS Managed API

Для поиска объектов конфигурации пользователя можно использовать метод Managed API Folder. FindItems EWS с соответствующим параметром обхода.You can use the Folder.FindItems EWS Managed API method with the associated traversal option to find user configuration objects. В приведенном ниже примере кода показано, как найти объекты конфигурации пользователя, хранящиеся в папке "Черновики", с помощью управляемого API EWS.The following code example shows you how to find user configuration objects stored on the Drafts folder by using the EWS Managed API.

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);
        }
    }
}

Поиск параметров приложения с помощью EWSFind an application setting by using EWS

Для поиска объектов конфигурации пользователя можно использовать операцию FindItem EWS.You can use the FindItem EWS operation to find user configuration objects.

В следующем примере показан XML-код запроса для поиска объектов конфигурации пользователя.The following example shows the request XML for finding user configuration objects. Это тот же XML-код, который создается в примере управляемого API EWS.This is the same XML that is generated by the EWS Managed API example.

<?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-код ответа для поиска объектов конфигурации пользователя.The following example shows the successful response XML for finding user configuration objects. Это тот же XML-код, который обрабатывается в примере управляемого API EWS.This is the same XML that is processed by the EWS Managed API example. Обратите внимание на следующее в этом ответе XML:Note the following in this response XML:

  • Мы сократили идентификатор и изменили ключи для удобочитаемости.We shortened the identifier and change keys for readability.

  • Два объекта конфигурации пользователя возвращаются в виде сообщений.The two user configuration objects are returned as messages. Это связано с тем, что операция FindItem возвращает все элементы, не определенные в схеме EWS в виде элементов сообщения.This is because the FindItem operation returns all items that are not defined in the EWS schema as message items.

  • Свойства ItemClass для двух объектов конфигурации пользователей отличаются.The ItemClass properties for the two user configuration objects are different. Первый объект конфигурации пользователя был создан с помощью EWS.The first user configuration object was created by using EWS. Второй объект был создан другим API.The second object was created by another 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 EWSGet and update application settings by using the EWS Managed API

Найдя объект конфигурации пользователя, вы можете использовать метод управляемого API усерконфигуратион. Bind EWS, чтобы получить объект Configuration из почтового ящика.After you find a user configuration object, you can use the UserConfiguration.Bind EWS Managed API method to get the configuration object from the mailbox. После получения объекта Configuration можно использовать метод усерконфигуратион. Update , чтобы обновить его.After you get the configuration object, you can use the UserConfiguration.Update method to update it. В приведенном ниже примере показано, как получить и обновить объект конфигурации пользователя с помощью управляемого API EWS.The following example shows how to get and update a user configuration object by using the EWS Managed API.

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();
    }
}

Получение и обновление параметров приложения с помощью EWSGet and update application settings by using EWS

С помощью операции GetUserConfiguration EWS можно получить объект конфигурации из почтового ящика и UpdateUserConfiguration для обновления объекта.You can use the GetUserConfiguration EWS operation to retrieve the configuration object from the mailbox, and the UpdateUserConfiguration to update the object. В следующем примере показан XML-код запроса для получения объекта конфигурации пользователя с именем Тестконфиг.The following example shows the request XML for getting a user configuration object named TestConfig. Запрос утверждает, что все конфигурации должны быть возвращены в ответе.The request states that all configurations should be returned in the response. Это тот же XML-код, который создается в примере управляемого API EWS.This is the same XML that is generated by the EWS Managed API example.

<?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-код отклика для возврата объектов конфигурации пользователя.The following example shows the successful response XML for getting a user configuration objects. Ответ содержит словарь данных.The response contains a data dictionary. Это тот же XML-код, который обрабатывается в примере управляемого API EWS.This is the same XML that is processed by the EWS Managed API example.

<?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-код запроса для обновления объекта конфигурации пользователя.The following example shows the request XML for updating a user configuration object. Запрос утверждает, что все конфигурации должны быть возвращены в ответе.The request states that all configurations should be returned in the response. Это тот же XML-код, который создается с помощью управляемого API EWS в примере, в котором вызывается метод усерконфигуратион. Update .This is the same XML that is generated by the EWS Managed API example that calls the UserConfiguration.Update method. Вы видите, что XML-файл обновления содержит существующие записи словаря и дополнительный, добавленный перед обновлением.You can see that the update XML contains the existing dictionary entries and the additional one that was added before the update.

<?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 является простым и указывает, было ли обновление успешным или произошла ошибка.The response XML is simple and indicates whether the update was successful or whether an error occurred.

Удаление параметра приложения с помощью управляемого API EWSDelete an application setting by using the EWS Managed API

Для удаления объектов конфигурации пользователя можно использовать метод усерконфигуратион. Delete для управляемого API EWS.You can use the UserConfiguration.Delete EWS Managed API method to delete user configuration objects. В приведенном ниже примере кода показано, как удалить объект конфигурации пользователя Контосодрафтсеттингс с помощью управляемого API EWS.The following code example shows you how to delete the ContosoDraftSettings user configuration object by using the EWS Managed API.

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();
}

Удаление параметра приложения с помощью EWSDelete an application setting by using EWS

Для удаления объектов конфигурации пользователя можно использовать операцию DeleteUserConfiguration EWS.You can use the DeleteUserConfiguration EWS operation to delete user configuration objects.

В следующем примере показан XML-код запроса для удаления объекта конфигурации пользователя с именем Контосодрафтсеттингс, который был применен к папке "Черновики".The following example shows the request XML for deleting a user configuration object named ContosoDraftSettings that was applied to the Drafts folder. Это тот же XML-код, который создается в примере управляемого API EWS.This is the same XML that is generated by the EWS Managed API example.

<?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-код отклика прост и указывает, был ли запрос на удаление успешным, или возникла ли ошибка.The response XML is simple and indicates whether the delete request was a success or whether an error occurred.

См. такжеSee also