Gerenciar configurações de aplicativos persistentes usando o EWS no ExchangeManage persistent application settings by using EWS in Exchange

Saiba como criar, localizar, obter, atualizar e excluir configurações de aplicativos persistentes usando a API gerenciada do EWS ou o EWS no Exchange.Learn how to create, find, get, update, and delete persistent application settings by using the EWS Managed API or EWS in Exchange.

Os objetos de configuração do usuário são a melhor opção para armazenar definições de configuração para seu aplicativo de cliente do Exchange, principalmente por estarem ocultos dos resultados da pesquisa na maioria dos aplicativos cliente.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. Os aplicativos clientes normalmente ocultam essas configurações porque o usuário final não precisa vê-las e, portanto, o usuário não acessa acidentalmente essas informações.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. Os exemplos de código neste artigo mostram como você pode usar os objetos de configuração do usuário para gerenciar as configurações persistentes, incluindo como criar, localizar, obter, atualizar e excluir as configurações de aplicativo persistente que são armazenadas nos objetos de configuração do usuário.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.

Criar uma configuração de aplicativo usando a API gerenciada do EWSCreate an application setting by using the EWS Managed API

Você pode usar o método userconfiguration. Save do EWS Managed API para criar uma configuração personalizada.You can use the UserConfiguration.Save EWS Managed API method to create a custom configuration setting. Um objeto de configuração do usuário pode conter XML, binário, um dicionário de dados ou uma combinação desses três tipos de dados.A user configuration object can contain XML, binary, a data dictionary, or a combination of those three data types. O exemplo a seguir mostra como salvar um objeto de configuração do usuário chamado ContosoDraftSettings que contém dados binários na pasta Rascunhos usando a API gerenciada do 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. Isso pode ser útil se você quiser armazenar informações de configuração sobre como os itens de rascunho são exibidos no aplicativo cliente.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);
}

Criar uma configuração de aplicativo usando o EWSCreate an application setting by using EWS

Você pode usar a operação CreateUserConfiguration EWS para criar uma configuração personalizada.You can use the CreateUserConfiguration EWS operation to create a custom configuration setting. O exemplo a seguir mostra a solicitação de XML para a criação de um objeto de configuração do usuário chamado ContosoDraftSettings.The following example shows the request XML for creating a user configuration object named ContosoDraftSettings. A solicitação tenta salvar um fluxo binário em um objeto de configuração do usuário na pasta Rascunhos.The request attempts to save a binary stream to a user configuration object on the Drafts folder. Este é o mesmo XML que é gerado pelo exemplo de API gerenciada do 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>

O XML de resposta é simples e indica se a solicitação de criação foi bem-sucedida ou se ocorreu um erro.The response XML is simple and indicates whether the create request was successful or whether an error occurred.

Localizar uma configuração de aplicativo usando a API gerenciada do EWSFind an application setting by using the EWS Managed API

Você pode usar o método Folder. FindItems EWS Managed API com a opção transversal associada para localizar objetos de configuração do usuário.You can use the Folder.FindItems EWS Managed API method with the associated traversal option to find user configuration objects. O exemplo de código a seguir mostra como localizar objetos de configuração do usuário armazenados na pasta Rascunhos usando a API gerenciada do 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);
        }
    }
}

Localizar uma configuração de aplicativo usando o EWSFind an application setting by using EWS

Você pode usar a operação FindItem EWS para localizar objetos de configuração do usuário.You can use the FindItem EWS operation to find user configuration objects.

O exemplo a seguir mostra a solicitação de XML para localizar objetos de configuração do usuário.The following example shows the request XML for finding user configuration objects. Este é o mesmo XML que é gerado pelo exemplo de API gerenciada do 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>

O exemplo a seguir mostra o XML de resposta bem-sucedido para localizar objetos de configuração do usuário.The following example shows the successful response XML for finding user configuration objects. Este é o mesmo XML processado pelo exemplo de API gerenciada do EWS.This is the same XML that is processed by the EWS Managed API example. Observe o seguinte neste XML de resposta:Note the following in this response XML:

  • Reduzimos o identificador e alteramos as chaves para facilitar a leitura.We shortened the identifier and change keys for readability.

  • Os dois objetos de configuração do usuário são retornados como mensagens.The two user configuration objects are returned as messages. Isso ocorre porque a operação FindItem retorna todos os itens que não estão definidos no esquema do EWS como itens de mensagem.This is because the FindItem operation returns all items that are not defined in the EWS schema as message items.

  • As propriedades de @ Class para os dois objetos de configuração do usuário são diferentes.The ItemClass properties for the two user configuration objects are different. O primeiro objeto de configuração do usuário foi criado usando o EWS.The first user configuration object was created by using EWS. O segundo objeto foi criado por outra 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>

Obter e atualizar as configurações de aplicativo usando a API gerenciada do EWSGet and update application settings by using the EWS Managed API

Depois de encontrar um objeto de configuração do usuário, você pode usar o método userconfiguration. bind da API gerenciada do EWS para obter o objeto de configuração da caixa de correio.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. Depois de obter o objeto de configuração, você pode usar o método userconfiguration. Update para atualizá-lo.After you get the configuration object, you can use the UserConfiguration.Update method to update it. O exemplo a seguir mostra como obter e atualizar um objeto de configuração do usuário usando a API gerenciada do 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();
    }
}

Obter e atualizar as configurações de aplicativo usando o EWSGet and update application settings by using EWS

Você pode usar a operação GetUserConfiguration EWS para recuperar o objeto de configuração da caixa de correio e o UpdateUserConfiguration para atualizar o objeto.You can use the GetUserConfiguration EWS operation to retrieve the configuration object from the mailbox, and the UpdateUserConfiguration to update the object. O exemplo a seguir mostra o XML da solicitação para obter um objeto de configuração do usuário chamado TestConfig.The following example shows the request XML for getting a user configuration object named TestConfig. A solicitação afirma que todas as configurações devem ser retornadas na resposta.The request states that all configurations should be returned in the response. Este é o mesmo XML que é gerado pelo exemplo de API gerenciada do 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>

O exemplo a seguir mostra o XML de resposta bem-sucedido para obter os objetos de configuração do usuário.The following example shows the successful response XML for getting a user configuration objects. A resposta contém um dicionário de dados.The response contains a data dictionary. Este é o mesmo XML processado pelo exemplo de API gerenciada do 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>

O exemplo a seguir mostra a solicitação de XML para atualização de um objeto de configuração do usuário.The following example shows the request XML for updating a user configuration object. A solicitação afirma que todas as configurações devem ser retornadas na resposta.The request states that all configurations should be returned in the response. Este é o mesmo XML que é gerado pelo exemplo de API gerenciada do EWS que chama o método userconfiguration. Update .This is the same XML that is generated by the EWS Managed API example that calls the UserConfiguration.Update method. Você pode ver que o XML de atualização contém as entradas de dicionário existentes e outra que foi adicionada antes da atualização.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>

O XML de resposta é simples e indica se a atualização foi bem-sucedida ou se ocorreu um erro.The response XML is simple and indicates whether the update was successful or whether an error occurred.

Excluir uma configuração de aplicativo usando a API gerenciada do EWSDelete an application setting by using the EWS Managed API

Você pode usar o método userconfiguration. Delete EWS Managed API para excluir os objetos de configuração do usuário.You can use the UserConfiguration.Delete EWS Managed API method to delete user configuration objects. O exemplo de código a seguir mostra como excluir o objeto de configuração do usuário ContosoDraftSettings usando a API gerenciada do 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();
}

Excluir uma configuração de aplicativo usando o EWSDelete an application setting by using EWS

Você pode usar a operação DeleteUserConfiguration EWS para excluir objetos de configuração do usuário.You can use the DeleteUserConfiguration EWS operation to delete user configuration objects.

O exemplo a seguir mostra o XML da solicitação para excluir um objeto de configuração do usuário chamado ContosoDraftSettings que foi aplicado à pasta Rascunhos.The following example shows the request XML for deleting a user configuration object named ContosoDraftSettings that was applied to the Drafts folder. Este é o mesmo XML que é gerado pelo exemplo de API gerenciada do 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>

O XML de resposta é simples e indica se a solicitação de exclusão foi bem-sucedida ou se ocorreu um erro.The response XML is simple and indicates whether the delete request was a success or whether an error occurred.

Confira tambémSee also