Exchange で EWS を使用して永続的なアプリケーションの設定を管理するManage persistent application settings by using EWS in Exchange

Exchange で EWS マネージ API または EWS を使用して、永続的なアプリケーションの設定を作成、検索、取得、更新、削除する方法について説明します。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.

EWS マネージ API を使用してアプリケーション設定を作成するCreate an application setting by using the EWS Managed API

EWS マネージ API の UserConfiguration.Save メソッドを使用して、カスタム構成設定を作成できます。You can use the UserConfiguration.Save EWS Managed API method to create a custom configuration setting. ユーザー構成オブジェクトには、XML、バイナリ、データ辞書、またはこれらの 3 つのデータ型の組み合わせを含めることができます。A user configuration object can contain XML, binary, a data dictionary, or a combination of those three data types. 次の例では、EWS マネージ API を使用して、バイナリ データを含む ContosoDraftSettings という名前のユーザー構成オブジェクトを下書きフォルダーに保存する方法を示します。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);
}

EWS を使用してアプリケーション設定を作成するCreate an application setting by using EWS

EWS の CreateUserConfiguration 操作を使用して、カスタム構成設定を作成できます。次の例は、ContosoDraftSettings という名前のユーザー構成オブジェクトを作成するための要求 XML を示しています。この要求は、バイナリ ストリームを下書きフォルダーのユーザー構成オブジェクトに保存しようとします。これは、EWS マネージ API の例で生成されるものと同じ XML です。You can use the CreateUserConfiguration EWS operation to create a custom configuration setting. 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. 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.

EWS マネージ API を使用してアプリケーション設定を検索するFind an application setting by using the EWS Managed API

関連付けられているトラバーサル オプションと共に EWS マネージ API の Folder.FindItems メソッドを使用して、ユーザー構成オブジェクトを検索できます。You can use the Folder.FindItems EWS Managed API method with the associated traversal option to find user configuration objects. 次のコード例では、EWS マネージ API を使用して、下書きフォルダーに保存されているユーザー構成オブジェクトを検索する方法を示します。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);
        }
    }
}

EWS を使用してアプリケーション設定を検索するFind an application setting by using EWS

EWS の FindItem 操作を使用して、ユーザー構成オブジェクトを検索できます。You can use the FindItem EWS operation to find user configuration objects.

次の例は、ユーザー構成オブジェクトを検索するための要求 XML を示しています。これは、EWS マネージ API の例で生成されるものと同じ XML です。The following example shows the request XML for finding user configuration objects. 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 を示しています。これは、EWS マネージ API の例で処理されるものと同じ XML です。この応答 XML では次の点に注意してください。 The following example shows the successful response XML for finding user configuration objects. This is the same XML that is processed by the EWS Managed API example. Note the following in this response XML:

  • 読みやすいように識別子と変更キーが短縮されています。We shortened the identifier and change keys for readability.

  • メッセージとして 2 つのユーザー構成オブジェクトが返されます。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.

  • 2 つのユーザー構成オブジェクトでは、ItemClass プロパティが異なります。The ItemClass properties for the two user configuration objects are different. 最初のユーザー構成オブジェクトは、EWS を使用して作成されました。The first user configuration object was created by using EWS. 2 番目のオブジェクトは、他の 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>

EWS マネージ API を使用してアプリケーション設定を取得して更新するGet and update application settings by using the EWS Managed API

ユーザー構成オブジェクトの検索後、EWS マネージ API の UserConfiguration.Bind メソッドを使用して、メールボックスから構成オブジェクトを取得できます。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. 構成オブジェクトを取得すると、UserConfiguration.Update メソッドを使用して、それを更新できます。After you get the configuration object, you can use the UserConfiguration.Update method to update it. 次の例では、EWS マネージ API を使用して、ユーザー構成オブジェクトを取得して更新する方法を示します。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();
    }
}

EWS を使用してアプリケーション設定を取得して更新するGet and update application settings by using EWS

EWS の GetUserConfiguration 操作を使用して、メールボックスから構成オブジェクトを取得できます。また UpdateUserConfiguration を使用してオブジェクトを更新できます。次の例は、TestConfig という名前のユーザー構成オブジェクトを取得するための要求 XML を示しています。この要求は、すべての構成を応答で返す必要があることを示しています。これは、EWS マネージ API の例で生成されるものと同じ XML です。You can use the GetUserConfiguration EWS operation to retrieve the configuration object from the mailbox, and the UpdateUserConfiguration to update the object. 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. 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 を示しています。応答にはデータ辞書が含まれます。これは、EWS マネージ API の例で処理されるものと同じ XML です。 The following example shows the successful response XML for getting a user configuration objects. The response contains a data dictionary. 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. これは、UserConfiguration.Update メソッドを呼び出す EWS マネージ API の例で生成されるものと同じ XML です。This is the same XML that is generated by the EWS Managed API example that calls the UserConfiguration.Update method. 更新 XML に既存の辞書エントリと、更新前に追加された他の 1 つの辞書エントリが含まれていることが確認できます。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.

EWS マネージ API を使用してアプリケーション設定を削除するDelete an application setting by using the EWS Managed API

EWS マネージ API の UserConfiguration.Delete メソッドを使用して、ユーザー構成オブジェクトを削除できます。You can use the UserConfiguration.Delete EWS Managed API method to delete user configuration objects. 次のコード例は、EWS マネージ API を使用して、ユーザー構成オブジェクト ContosoDraftSettings を削除する方法を示します。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();
}

EWS を使用してアプリケーション設定を削除するDelete an application setting by using EWS

EWS の DeleteUserConfiguration 操作を使用して、ユーザー構成オブジェクトを削除できます。You can use the DeleteUserConfiguration EWS operation to delete user configuration objects.

次の例は、下書きフォルダーに適用されていた ContosoDraftSettings という名前のユーザー構成オブジェクトを削除するための要求 XML を示しています。これは、EWS マネージ API の例で生成されるものと同じ XML です。The following example shows the request XML for deleting a user configuration object named ContosoDraftSettings that was applied to the Drafts folder. 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