Administración de la configuración de la aplicación persistente mediante EWS en 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.
Los objetos de configuración de usuario son la mejor opción para almacenar los valores 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. Las aplicaciones cliente suelen ocultar esta configuración porque el usuario final no necesita verla y para que el usuario no acceda accidentalmente a esta información. En los ejemplos de código de este artículo se muestra cómo puede usar objetos de configuración de usuario para administrar la configuración persistente, incluido cómo crear, buscar, obtener, actualizar y eliminar valores de aplicación persistentes almacenados en objetos de configuración de usuario.
Creación de una configuración de aplicación mediante la API administrada de EWS
Puede usar el método UserConfiguration.Save EWS Managed API para crear una configuración personalizada. Un objeto de configuración de usuario puede contener XML, binario, un diccionario de datos o una combinación de esos tres tipos de datos. En el ejemplo siguiente se muestra cómo guardar un objeto de configuración de usuario denominado ContosoDraftSettings que contiene datos binarios en la carpeta Drafts mediante la API administrada de EWS. Esto podría ser útil si desea almacenar información de configuración sobre cómo se muestran los elementos de borrador en la aplicación cliente.
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);
}
Creación de una configuración de aplicación mediante EWS
Puede usar la operación EWS CreateUserConfiguration para crear una configuración personalizada. En el ejemplo siguiente se muestra el XML de solicitud para crear un objeto de configuración de usuario denominado ContosoDraftSettings. La solicitud intenta guardar una secuencia binaria en un objeto de configuración de usuario en la carpeta Borradores. Este es el mismo XML generado por el ejemplo de API administrada de EWS.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2013" />
</soap:Header>
<soap:Body>
<m:CreateUserConfiguration>
<m:UserConfiguration>
<t:UserConfigurationName Name="ContosoDraftSettings">
<t:DistinguishedFolderId Id="drafts" />
</t:UserConfigurationName>
<t:BinaryData>iVBORw0KGH5UhKquRSzaeAAAAAElFTkSuQmCC</t:BinaryData>
</m:UserConfiguration>
</m:CreateUserConfiguration>
</soap:Body>
</soap:Envelope>
El XML de respuesta es simple e indica si la solicitud de creación se realizó correctamente o si se produjo un error.
Búsqueda de una configuración de aplicación mediante la API administrada de EWS
Puede usar el método Folder.FindItems EWS Managed API con la opción de recorrido asociada para buscar objetos de configuración de usuario. En el ejemplo de código siguiente se muestra cómo buscar objetos de configuración de usuario almacenados en la carpeta Drafts mediante la API administrada de EWS.
private static void FindAssociated(ExchangeService service)
{
// This is the ItemClass prefix of user configuration objects that are created by using EWS.
const string userConfigPrefix = "IPM.Configuration.";
// This is the name of a configuration setting created by using EWS.
string userConfigName = "TestConfig";
// Return the first five items.
ItemView view = new ItemView(5);
// Request only the properties that you need. Because all the results will be user configuration
// objects, you won't need to request the ItemSchema.IsAssociated property, which identifies
// user configuration objects.
PropertySet props = new PropertySet(BasePropertySet.IdOnly,
ItemSchema.ItemClass);
view.PropertySet = props;
// Set the traversal to find user configuration objects.
view.Traversal = ItemTraversal.Associated;
// Send the request to search the Drafts folder for all the user configuration objects
// in the folder. You do not have to use a search restriction because you will not return
// a large number of search results. For this scenario, it is better to sort the results
// on the client. This method results in a call to EWS.
FindItemsResults<Item> findResults = service.FindItems(WellKnownFolderName.Drafts, view);
// Output a list of the item classes for the associated items.
foreach (Item item in findResults)
{
if (item.ItemClass == userConfigPrefix + userConfigName)
{
Console.WriteLine("You found the configuration: " + userConfigPrefix + userConfigName);
}
}
}
Búsqueda de una configuración de aplicación mediante EWS
Puede usar la operación EWS FindItem para buscar objetos de configuración de usuario.
En el ejemplo siguiente se muestra el XML de solicitud para buscar objetos de configuración de usuario. Este es el mismo XML generado por el ejemplo de API administrada de EWS.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2013" />
</soap:Header>
<soap:Body>
<m:FindItem Traversal="Associated">
<m:ItemShape>
<t:BaseShape>IdOnly</t:BaseShape>
<t:AdditionalProperties>
<t:FieldURI FieldURI="item:ItemClass" />
</t:AdditionalProperties>
</m:ItemShape>
<m:IndexedPageItemView MaxEntriesReturned="5" Offset="0" BasePoint="Beginning" />
<m:ParentFolderIds>
<t:DistinguishedFolderId Id="drafts" />
</m:ParentFolderIds>
</m:FindItem>
</soap:Body>
</soap:Envelope>
En el ejemplo siguiente se muestra el XML de respuesta correcta para buscar objetos de configuración de usuario. Este es el mismo XML que procesa el ejemplo de API administrada de EWS. Tenga en cuenta lo siguiente en este XML de respuesta:
Hemos acortado el identificador y las claves de cambio para mejorar la legibilidad.
Los dos objetos de configuración de usuario se devuelven como mensajes. 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.
Las propiedades ItemClass de los dos objetos de configuración de usuario son diferentes. El primer objeto de configuración de usuario se creó mediante EWS. Otra API creó el segundo objeto.
<?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 EWS
Después de encontrar un objeto de configuración de usuario, puede usar el método UserConfiguration.Bind EWS Managed API para obtener el objeto de configuración del buzón. Después de obtener el objeto de configuración, puede usar el método UserConfiguration.Update para actualizarlo. En el ejemplo siguiente se muestra cómo obtener y actualizar un objeto de configuración de usuario mediante la API administrada de EWS.
private static void GetAndUpdateUserConfiguration(ExchangeService service)
{
// Binds to a user configuration object named "TestConfig" in the user's mailbox.
// Results in a call to EWS. You can also use the Load method to get the latest
// server version of the user configuration object.
UserConfiguration usrConfig = UserConfiguration.Bind(service,
"TestConfig",
WellKnownFolderName.Drafts,
UserConfigurationProperties.All);
// Display the returned configuration object property values.
if (usrConfig.XmlData != null)
{
Console.WriteLine("XmlData: " + Encoding.UTF8.GetString(usrConfig.XmlData));
}
if (usrConfig.BinaryData != null)
{
Console.WriteLine("BinaryData: " + Encoding.UTF8.GetString(usrConfig.BinaryData));
}
if (usrConfig.Dictionary.Count > 0)
{
Console.WriteLine("Contains {0} dictionary entries", usrConfig.Dictionary.Count);
}
// Add dictionary property values to the local copy of the object.
usrConfig.Dictionary.Add("Key5", 1);
// Updates the server version of the user configuration object
// if it has changed on the client. Results in a call to EWS.
if (usrConfig.IsDirty)
{
usrConfig.Update();
}
}
Obtener y actualizar la configuración de la aplicación mediante EWS
Puede usar la operación EWS GetUserConfiguration para recuperar el objeto de configuración del buzón y UpdateUserConfiguration para actualizar el objeto. En el ejemplo siguiente se muestra el XML de solicitud para obtener un objeto de configuración de usuario denominado TestConfig. La solicitud indica que todas las configuraciones deben devolverse en la respuesta. Este es el mismo XML generado por el ejemplo de API administrada de EWS.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2013" />
</soap:Header>
<soap:Body>
<m:GetUserConfiguration>
<m:UserConfigurationName Name="TestConfig">
<t:DistinguishedFolderId Id="drafts" />
</m:UserConfigurationName>
<m:UserConfigurationProperties>All</m:UserConfigurationProperties>
</m:GetUserConfiguration>
</soap:Body>
</soap:Envelope>
En el ejemplo siguiente se muestra el XML de respuesta correcta para obtener objetos de configuración de usuario. La respuesta contiene un diccionario de datos. Este es el mismo XML que procesa el ejemplo de API administrada de EWS.
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ServerVersionInfo MajorVersion="15"
MinorVersion="0"
MajorBuildNumber="800"
MinorBuildNumber="5"
Version="V2_6"
xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<m:GetUserConfigurationResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:GetUserConfigurationResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:UserConfiguration>
<t:UserConfigurationName Name="TestConfig">
<t:DistinguishedFolderId Id="drafts" />
</t:UserConfigurationName>
<t:ItemId Id="AAMkDEY9M6AAA=" ChangeKey="CQAAACYnYF5aFMwP0T" />
<t:Dictionary>
<t:DictionaryEntry>
<t:DictionaryKey>
<t:Type>String</t:Type>
<t:Value>Key1</t:Value>
</t:DictionaryKey>
<t:DictionaryValue>
<t:Type>Integer32</t:Type>
<t:Value>1</t:Value>
</t:DictionaryValue>
</t:DictionaryEntry>
<t:DictionaryEntry>
<t:DictionaryKey>
<t:Type>String</t:Type>
<t:Value>PhoneNumber</t:Value>
</t:DictionaryKey>
<t:DictionaryValue>
<t:Type>String</t:Type>
<t:Value>555-555-1111</t:Value>
</t:DictionaryValue>
</t:DictionaryEntry>
</t:Dictionary>
</m:UserConfiguration>
</m:GetUserConfigurationResponseMessage>
</m:ResponseMessages>
</m:GetUserConfigurationResponse>
</s:Body>
</s:Envelope>
En el ejemplo siguiente se muestra el XML de solicitud para actualizar un objeto de configuración de usuario. La solicitud indica que todas las configuraciones deben devolverse en la respuesta. Este es el mismo XML generado por el ejemplo de API administrada de EWS que llama al método UserConfiguration.Update . 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.
<?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 realizó correctamente o si se produjo un error.
Eliminación de una configuración de aplicación mediante la API administrada de EWS
Puede usar el método UserConfiguration.Delete EWS Managed API para eliminar objetos de configuración de usuario. En el ejemplo de código siguiente se muestra cómo eliminar el objeto de configuración de usuario ContosoDraftSettings mediante la API administrada de EWS.
private static void DeleteUserConfiguration(ExchangeService service)
{
// Binds to a user configuration object. Results in a call to EWS.
UserConfiguration usrConfig = UserConfiguration.Bind(service,
"ContosoDraftSettings",
WellKnownFolderName.Drafts,
UserConfigurationProperties.Id);
// Deletes the user configuration object.
// Results in a call to EWS.
usrConfig.Delete();
}
Eliminación de una configuración de aplicación mediante EWS
Puede usar la operación DeleteUserConfiguration EWS para eliminar objetos de configuración de usuario.
En el ejemplo siguiente se muestra el XML de solicitud para eliminar un objeto de configuración de usuario denominado ContosoDraftSettings que se aplicó a la carpeta Borradores. Este es el mismo XML generado por el ejemplo de API administrada de EWS.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2013" />
</soap:Header>
<soap:Body>
<m:DeleteUserConfiguration>
<m:UserConfigurationName Name="ContosoDraftSettings">
<t:DistinguishedFolderId Id="drafts" />
</m:UserConfigurationName>
</m:DeleteUserConfiguration>
</soap:Body>
</soap:Envelope>
El XML de respuesta es simple e indica si la solicitud de eliminación se realizó correctamente o si se produjo un error.
Vea también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de