Administración de la configuración de aplicaciones persistentes mediante EWS en ExchangeManage persistent application settings by using EWS in Exchange

Obtenga información sobre cómo crear, buscar, obtener, actualizar y eliminar la configuración de la aplicación persistente mediante la API administrada de EWS o EWS en Exchange.Learn how to create, find, get, update, and delete persistent application settings by using the EWS Managed API or EWS in Exchange.

Los objetos de configuración de usuario son la mejor opción para almacenar las opciones de configuración de la aplicación cliente de Exchange, principalmente porque están ocultos de los resultados de búsqueda en la mayoría de las aplicaciones 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. Normalmente, las aplicaciones cliente ocultan esta configuración porque el usuario final no tiene que verlas y, por lo tanto, el usuario no tiene acceso a esta información por accidente.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. Los ejemplos de código de este artículo muestran cómo puede usar los objetos de configuración de usuario para administrar la configuración persistente, incluido cómo crear, buscar, obtener, actualizar y eliminar la configuración de aplicaciones persistentes que se almacenan en los objetos de configuración de usuario.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.

Crear una configuración de aplicación mediante la API administrada de EWSCreate an application setting by using the EWS Managed API

Puede usar el método de la API administrada de EWS UserConfiguration. Save para crear una opción de configuración personalizada.You can use the UserConfiguration.Save EWS Managed API method to create a custom configuration setting. Un objeto de configuración de usuario puede contener XML, Binary, un diccionario de datos o una combinación de estos tres tipos de datos.A user configuration object can contain XML, binary, a data dictionary, or a combination of those three data types. En el siguiente ejemplo se muestra cómo guardar un objeto de configuración de usuario denominado ContosoDraftSettings que contiene datos binarios en la carpeta Borradores mediante la API administrada de 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. Esto puede ser útil si desea almacenar información de configuración acerca de cómo se muestran los elementos borradores en la aplicación 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);
}

Crear una configuración de aplicación mediante EWSCreate an application setting by using EWS

Puede usar la operación de EWS de CreateUserConfiguration para crear una opción de configuración personalizada.You can use the CreateUserConfiguration EWS operation to create a custom configuration setting. En el ejemplo siguiente se muestra el XML de la solicitud para crear un objeto de configuración de usuario denominado ContosoDraftSettings.The following example shows the request XML for creating a user configuration object named ContosoDraftSettings. La solicitud intenta guardar una secuencia binaria en un objeto de configuración de usuario de la carpeta Borradores.The request attempts to save a binary stream to a user configuration object on the Drafts folder. Se trata del mismo XML generado por el ejemplo de la API administrada de 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>

El XML de respuesta es sencillo e indica si la solicitud de creación se ha realizado correctamente o si se ha producido un error.The response XML is simple and indicates whether the create request was successful or whether an error occurred.

Buscar una configuración de aplicación mediante la API administrada de EWSFind an application setting by using the EWS Managed API

Puede usar el método de API administrada Folder. FindItems EWS con la opción de recorrido asociada para buscar objetos de configuración de usuario.You can use the Folder.FindItems EWS Managed API method with the associated traversal option to find user configuration objects. En el ejemplo de código siguiente se muestra cómo buscar objetos de configuración de usuario almacenados en la carpeta Borradores mediante la API administrada de 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);
        }
    }
}

Buscar una configuración de aplicación mediante EWSFind an application setting by using EWS

Puede usar la operación de EWS de FindItem para buscar objetos de configuración de usuario.You can use the FindItem EWS operation to find user configuration objects.

En el ejemplo siguiente se muestra la solicitud XML para buscar objetos de configuración de usuario.The following example shows the request XML for finding user configuration objects. Se trata del mismo XML generado por el ejemplo de la API administrada de 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>

En el ejemplo siguiente se muestra el XML de respuesta correcto para buscar objetos de configuración de usuario.The following example shows the successful response XML for finding user configuration objects. Este es el mismo XML que se procesa mediante el ejemplo de la API administrada de EWS.This is the same XML that is processed by the EWS Managed API example. Tenga en cuenta lo siguiente en este XML de respuesta:Note the following in this response XML:

  • Se ha abreviado el identificador y las teclas de cambio para facilitar su lectura.We shortened the identifier and change keys for readability.

  • Los dos objetos de configuración de usuario se devuelven como mensajes.The two user configuration objects are returned as messages. Esto se debe a que la operación FindItem devuelve todos los elementos que no están definidos en el esquema EWS como elementos de mensaje.This is because the FindItem operation returns all items that are not defined in the EWS schema as message items.

  • Las propiedades ItemClass de los dos objetos de configuración de usuario son diferentes.The ItemClass properties for the two user configuration objects are different. El primer objeto de configuración de usuario se creó con EWS.The first user configuration object was created by using EWS. El segundo objeto fue creado por otra 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>

Obtener y actualizar la configuración de la aplicación mediante la API administrada de EWSGet and update application settings by using the EWS Managed API

Después de encontrar un objeto de configuración de usuario, puede usar el método de la API administrada de EWS UserConfiguration. bind para obtener el objeto de configuración del buzón de correo.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. Después de obtener el objeto Configuration, puede usar el método UserConfiguration. Update para actualizarlo.After you get the configuration object, you can use the UserConfiguration.Update method to update it. En el siguiente ejemplo, se muestra cómo obtener y actualizar un objeto de configuración de usuario mediante la API administrada de 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();
    }
}

Obtener y actualizar la configuración de la aplicación mediante EWSGet and update application settings by using EWS

Puede usar la operación de EWS de GetUserConfiguration para recuperar el objeto de configuración del buzón de correo y el UpdateUserConfiguration para actualizar el objeto.You can use the GetUserConfiguration EWS operation to retrieve the configuration object from the mailbox, and the UpdateUserConfiguration to update the object. En el siguiente ejemplo se muestra la solicitud XML para obtener un objeto de configuración de usuario denominado TestConfig.The following example shows the request XML for getting a user configuration object named TestConfig. La solicitud indica que todas las configuraciones deben devolverse en la respuesta.The request states that all configurations should be returned in the response. Se trata del mismo XML generado por el ejemplo de la API administrada de 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>

En el ejemplo siguiente se muestra el XML de respuesta correcta para obtener objetos de configuración de usuario.The following example shows the successful response XML for getting a user configuration objects. La respuesta contiene un diccionario de datos.The response contains a data dictionary. Este es el mismo XML que se procesa mediante el ejemplo de la API administrada de 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>

En el ejemplo siguiente se muestra el XML de la solicitud para actualizar un objeto de configuración de usuario.The following example shows the request XML for updating a user configuration object. La solicitud indica que todas las configuraciones deben devolverse en la respuesta.The request states that all configurations should be returned in the response. Se trata del mismo XML generado por el ejemplo de la API administrada de EWS que llama al método UserConfiguration. Update .This is the same XML that is generated by the EWS Managed API example that calls the UserConfiguration.Update method. Puede ver que el XML de actualización contiene las entradas de diccionario existentes y la adicional que se agregó antes de la actualización.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>

El XML de respuesta es sencillo e indica si la actualización se ha realizado correctamente o si se ha producido un error.The response XML is simple and indicates whether the update was successful or whether an error occurred.

Eliminar una configuración de aplicación mediante la API administrada de EWSDelete an application setting by using the EWS Managed API

Puede usar el método UserConfiguration. Delete de la API administrada de EWS para eliminar objetos de configuración de usuario.You can use the UserConfiguration.Delete EWS Managed API method to delete user configuration objects. El siguiente ejemplo de código muestra cómo eliminar el objeto de configuración de usuario ContosoDraftSettings mediante la API administrada de 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();
}

Eliminar una configuración de aplicación mediante EWSDelete an application setting by using EWS

Puede usar la operación de EWS de DeleteUserConfiguration para eliminar objetos de configuración de usuario.You can use the DeleteUserConfiguration EWS operation to delete user configuration objects.

En el siguiente ejemplo se muestra el XML de la solicitud para eliminar un objeto de configuración de usuario denominado ContosoDraftSettings que se aplicó a la carpeta Borradores.The following example shows the request XML for deleting a user configuration object named ContosoDraftSettings that was applied to the Drafts folder. Se trata del mismo XML generado por el ejemplo de la API administrada de 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>

El XML de respuesta es sencillo e indica si la solicitud de eliminación se ha realizado correctamente o si se ha producido un error.The response XML is simple and indicates whether the delete request was a success or whether an error occurred.

Vea tambiénSee also