Trabajar con carpetas mediante EWS en Exchange
Obtenga información sobre cómo crear, obtener, actualizar y eliminar carpetas mediante la API administrada de EWS o EWS en Exchange.
EWS en Exchange usa carpetas para estructurar y organizar buzones. Puede crear carpetas nuevas, obtenerlas, actualizarlas y eliminarlas mediante la API administrada de EWS o EWS. Cada uno de los métodos u operaciones enumerados en la tabla siguiente se realiza en un objeto Folder, un tipo Folder o una de las clases o tipos de carpetas derivadas.
Tabla 1. Métodos y operaciones para crear, obtener, actualizar y eliminar carpetas
| Para | Método de la API administrada de EWS | Operación de EWS |
|---|---|---|
| Crear una carpeta | Folder.Save | CreateFolder |
| Crear una jerarquía de carpetas | No disponible | CreateFolderPath |
| Obtener una carpeta | Folder.Bind | GetFolder |
| Obtener una jerarquía de carpetas | Folder.FindFolders | FindFolder |
| Actualizar una carpeta | Folder.Update | UpdateFolder |
| Eliminar una carpeta | Folder.Delete | DeleteFolder |
Creación de una carpeta mediante la API administrada de EWS
En el ejemplo de código siguiente se muestra cómo usar la clase Folder para crear una nueva carpeta genérica con un DisplayName de "Carpeta personalizada" y un valor de propiedad FolderClass de IPF.Note. El método Folder.Save guarda la carpeta como una carpeta secundaria de la carpeta Bandeja de entrada.
En estos ejemplos se supone que service es un objeto ExchangeService válido y que el usuario se ha autenticado en un servidor Exchange.
// Create a custom folder.
Folder folder = new Folder(service);
folder.DisplayName = "Custom Folder";
folder.FolderClass = "IPF.Note";
// Save the folder as a child folder of the Inbox.
folder.Save(WellKnownFolderName.Inbox);
Para crear un tipo de carpeta diferente, como un CalendarFolder, ContactsFolder, SearchFoldero TasksFolder, cree una nueva instancia de la clase específica (en lugar de la clase Folder genérica) y no establezca la propiedad FolderClass. Por ejemplo, en el ejemplo de código siguiente se muestra cómo crear una nueva TasksFolder.
// Create a custom Tasks folder.
TasksFolder folder = new TasksFolder(service);
folder.DisplayName = "Custom Tasks";
// Save the folder as a child folder in the Inbox folder.
// This method call results in a CreateFolder call to EWS.
folder.Save(WellKnownFolderName.Inbox);
Si intenta crear una instancia de una clase específica y también establece la propiedad FolderClass, se produce el error ErrorNoFolderClassOverride.
Tenga en cuenta que no puede procesar por lotes la creación de varias carpetas en una sola llamada de método mediante la API administrada de EWS.
Crear una carpeta mediante EWS
Puede crear una sola carpeta o varias carpetas mediante EWS.
Para crear una sola carpeta, envíe un mensaje de solicitud de operación CreateFolder. La solicitud de operación CreateFolder indica que la carpeta principal es la Bandeja de entrada, la "Carpeta personalizada" es DisplayName y el valor del elemento FolderClass es IPF.Note.
Esta también es la solicitud XML que la API administrada de EWS envía al crear una nueva carpeta y llamar al método Folder.Save.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2007_SP1" />
</soap:Header>
<soap:Body>
<m:CreateFolder>
<m:ParentFolderId>
<t:DistinguishedFolderId Id="inbox" />
</m:ParentFolderId>
<m:Folders>
<t:Folder>
<t:FolderClass>IPF.Note</t:FolderClass>
<t:DisplayName>Custom Folder</t:DisplayName>
</t:Folder>
</m:Folders>
</m:CreateFolder>
</soap:Body>
</soap:Envelope>
El servidor responde a la solicitud CreateFolder con un mensaje CreateFolderResponse que incluye un valor ResponseCode de NoError, que indica que la carpeta se creó correctamente y el FolderId del mensaje recién creado.
Para crear varias carpetas, incluya varios elementos Folder en el mensaje de solicitud de operación CreateFolder. Todas las carpetas nuevas deben estar en la misma carpeta principal.
Crear una jerarquía de carpetas mediante EWS
Puede crear una jerarquía de carpetas en una sola llamada mediante la operación EWS CreateFolderPath. La misma funcionalidad no está disponible en la API administrada de EWS. En su lugar, si usa la API administrada de EWS, puede crear carpetas una por una, como se muestra en Crear una carpeta mediante EWS.
Nota:
La API administrada de EWS no implementa esta funcionalidad.
Obtener una carpeta mediante la API administrada de EWS
En el ejemplo de código siguiente se muestra cómo usar el método Folder.Bind para obtener la carpeta Bandeja de entrada. Como procedimiento recomendado, limite las propiedades devueltas solo a las necesarias para la aplicación. En este ejemplo se limitan las propiedades devueltas para incluir solo la propiedad Id creando una PropertySet y aplicando el valor IdOnly a la propiedad BasePropertySet.
En este ejemplo se supone que service es un objeto ExchangeService válido y que el usuario se ha autenticado en un servidor Exchange.
// As a best practice, limit the properties returned to only those that are required.
// In this scenario, you only need the FolderId.
PropertySet propSet = new PropertySet(BasePropertySet.IdOnly);
// Bind to an existing folder and get only the properties specified in the PropertySet.
// This method call results in a GetFolder call to EWS.
Folder rootfolder = Folder.Bind(service, WellKnownFolderName.Inbox, propSet);
Si necesita devolver propiedades adicionales, agregue propiedades de la clase FolderSchema a PropertySet o use uno de los métodos sobrecargados Bind que devuelve todas las propiedades de primera clase.
Tenga en cuenta que no puede obtener varias carpetas a la vez mediante la API administrada de EWS. Debe llamar al método Bind en cada carpeta por separado.
Obtener una carpeta mediante EWS
Puede obtener una sola carpeta o varias carpetas mediante EWS.
Para obtener una sola carpeta, envíe un mensaje de solicitud de operación GetFolder al servidor. En el ejemplo siguiente, el BaseShape se establece en IdOnly, por lo que solo se devuelve el FolderId de la carpeta especificada. El elemento FolderIds indica que la carpeta que se va a recuperar es la carpeta Bandeja de entrada.
Esta también es la solicitud XML que la API administrada de EWS envía al enlazar a una carpeta mediante el método Folder.Bind.
Para obtener varias carpetas, incluya varios elementos FolderIds en el mensaje de solicitud de operación GetFolder.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2007_SP1" />
</soap:Header>
<soap:Body>
<m:GetFolder>
<m:FolderShape>
<t:BaseShape>IdOnly</t:BaseShape>
</m:FolderShape>
<m:FolderIds>
<t:DistinguishedFolderId Id="inbox" />
</m:FolderIds>
</m:GetFolder>
</soap:Body>
</soap:Envelope>
En el ejemplo XML siguiente se muestra el mensaje GetFolderResponse que se envía desde el servidor al cliente en respuesta a la solicitud de operación GetFolder. Solo contiene el valor FolderId de la carpeta Bandeja de entrada. Los valores de algunos atributos y elementos se han acortado para mejorar la legibilidad.
<?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="16"
Version="V2_6"
xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns="http://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:GetFolderResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:GetFolderResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:Folders>
<t:Folder>
<t:FolderId Id="AAAENAAA=" ChangeKey="AQAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAEkbCr"/>
</t:Folder>
</m:Folders>
</m:GetFolderResponseMessage>
</m:ResponseMessages>
</m:GetFolderResponse>
</s:Body>
</s:Envelope>
Obtención de una jerarquía de carpetas mediante la API administrada de EWS
En el ejemplo de código siguiente se muestra cómo recuperar las subcarpetas de una carpeta raíz especificada. En este ejemplo se recuperan las subcarpetas de la carpeta MsgFolderRoot, que es la raíz del subárbol IPM (donde se almacenan las carpetas y los elementos del buzón).
En este ejemplo, se crea un objeto de clase FolderView para limitar los resultados de la respuesta del método Folder.FindFolders. Este escenario limita las propiedades para volver a lo siguiente: IdDisplayName y la propiedad extendida que indica si la carpeta es una carpeta oculta. Establezca el valor FolderView.Traversal en Deep para realizar una búsqueda recursiva de modo que el servidor recupere las subcarpetas, y establezca la carpeta raíz en MsgFolderRoot para que el servidor devuelva todas las carpetas del usuario (y el servidor no devuelva carpetas del sistema en el subárbol que no sea IPM).
En este ejemplo se supone que service es un objeto ExchangeService válido y que el usuario se ha autenticado en un servidor Exchange.
// Create a new folder view, and pass in the maximum number of folders to return.
FolderView view = new FolderView(folderViewSize);
// Create an extended property definition for the PR_ATTR_HIDDEN property,
// so that your results will indicate whether the folder is a hidden folder.
ExtendedPropertyDefinition isHiddenProp = new ExtendedPropertyDefinition(0x10f4, MapiPropertyType.Boolean);
// As a best practice, limit the properties returned to only those required.
// In this case, return the folder ID, DisplayName, and the value of the isHiddenProp
// extended property.
view.PropertySet = new PropertySet(BasePropertySet.IdOnly, FolderSchema.DisplayName, isHiddenProp);
// Indicate a Traversal value of Deep, so that all subfolders are retrieved.
view.Traversal = FolderTraversal.Deep;
// Call FindFolders to retrieve the folder hierarchy, starting with the MsgFolderRoot folder.
// This method call results in a FindFolder call to EWS.
FindFoldersResults findFolderResults = service.FindFolders(WellKnownFolderName.MsgFolderRoot, view);
Obtener una jerarquía de carpetas mediante EWS
Los siguientes ejemplos XML muestran cómo usar la operación FindFolder para recuperar una jerarquía de carpetas mediante EWS. En este ejemplo se recupera la carpeta msgfolderroot, que es la raíz del subárbol IPM y todas sus subcarpetas. El atributo Traversal se establece en Deep para que el servidor realice una búsqueda recursiva de la jerarquía de carpetas y solo devuelva carpetas y subcarpetas bajo la raíz especificada en la respuesta. En este ejemplo, el elemento BaseShape se establece en IdOnly para que el servidor solo devuelva el elemento FolderId. Para facilitar la comprensión de la salida, incluya el elemento DisplayName en los resultados incluyéndolo en el elemento AdditionalProperties en la solicitud, junto con el valor ExtendedFieldURI para la propiedad PR_ATTR_HIDDEN, para que sepa si las carpetas son carpetas ocultas.
Esta también es la solicitud XML que envía la API administrada de EWS cuando se llama al método FindFolders.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2007_SP1" />
</soap:Header>
<soap:Body>
<m:FindFolder Traversal="Deep">
<m:FolderShape>
<t:BaseShape>IdOnly</t:BaseShape>
<t:AdditionalProperties>
<t:FieldURI FieldURI="folder:DisplayName" />
<t:ExtendedFieldURI PropertyTag="4340"
PropertyType="Boolean" />
</t:AdditionalProperties>
</m:FolderShape>
<m:IndexedPageFolderView MaxEntriesReturned="100"
Offset="0"
BasePoint="Beginning" />
<m:ParentFolderIds>
<t:DistinguishedFolderId Id="msgfolderroot" />
</m:ParentFolderIds>
</m:FindFolder>
</soap:Body>
</soap:Envelope>
En el ejemplo XML siguiente se muestra el mensaje FindFolderResponse que se envía desde el servidor al cliente en respuesta a la solicitud de operación FindFolder. Contiene solo el FolderId, el DisplayName, y el valor de la propiedad extendida PR_ATTR_HIDDEN para todas las subcarpetas de la carpeta msgrootfolder. Si el elemento Value se establece en true, la carpeta debe estar oculta en la vista de cliente.
Esta también es la respuesta XML que la API administrada de EWS envía cuando se obtienen varias carpetas mediante el método FindFolder. Los valores de algunos atributos y elementos se han acortado para mejorar la legibilidad y algunas carpetas no se han incluido por motivos de brevedad.
<?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="815"
MinorBuildNumber="6"
Version="V2_7"
xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns="http://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:FindFolderResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:FindFolderResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:RootFolder IndexedPagingOffset="16"
TotalItemsInView="16"
IncludesLastItemInRange="true">
<t:Folders>
<t:CalendarFolder>
<t:FolderId Id="AAAEOAAA="
ChangeKey="AgAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAAA3"/>
<t:DisplayName>Calendar</t:DisplayName>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean"/>
<t:Value>false</t:Value>
</t:ExtendedProperty>
</t:CalendarFolder>
<t:ContactsFolder>
<t:FolderId Id="AAAEPAAA="
ChangeKey="AwAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAAA4"/>
<t:DisplayName>Contacts</t:DisplayName>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean"/>
<t:Value>false</t:Value>
</t:ExtendedProperty>
</t:ContactsFolder>
<t:ContactsFolder>
<t:FolderId Id="AAAUKAAA="
ChangeKey="AwAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAAS5"/>
<t:DisplayName>Recipient Cache</t:DisplayName>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean"/>
<t:Value>true</t:Value>
</t:ExtendedProperty>
</t:ContactsFolder>
<t:Folder>
<t:FolderId Id="AAAUJAAA="
ChangeKey="AQAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAASx"/>
<t:DisplayName>Conversation Action Settings</t:DisplayName>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean"/>
<t:Value>true</t:Value>
</t:ExtendedProperty>
</t:Folder>
…
</t:Folders>
</m:RootFolder>
</m:FindFolderResponseMessage>
</m:ResponseMessages>
</m:FindFolderResponse>
</s:Body>
</s:Envelope>
Actualización de una carpeta mediante la API administrada de EWS
En el ejemplo de código siguiente se muestra cómo actualizar el nombre para mostrar de una carpeta mediante la API administrada de EWS.
En primer lugar, cree un PropertySet para limitar el número de propiedades que devuelve el servidor en la respuesta Folder.Bind. Se recomienda usar IdOnlyBasePropertySet para reducir las llamadas a la base de datos de Exchange. A continuación, use el método Bind para enlazar a la carpeta que se va a actualizar. A continuación, actualice la propiedad DisplayName y use el método <Folder.Update para guardar los cambios.
En este ejemplo, se supone que service es un objeto ExchangeService válido y que el usuario se ha autenticado en un servidor Exchange. La variable local folderId es el identificador de la carpeta que se va a actualizar.
// As a best practice, only include the ID value in the PropertySet.
PropertySet propertySet = new PropertySet(BasePropertySet.IdOnly);
// Bind to an existing folder and get the FolderId.
// This method call results in a GetFolder call to EWS.
Folder folder = Folder.Bind(service, folderId, propertySet);
// Update the display name of the folder.
folder.DisplayName = "Updated folder name";
// Save the updates.
// This method call results in an UpdateFolder call to EWS.
folder.Update();
Actualizar una carpeta mediante EWS
En los siguientes ejemplos XML se muestra cómo actualizar el nombre para mostrar de una carpeta mediante EWS.
En primer lugar, envíe un mensaje de solicitud de operación GetFolder para obtener la carpeta que se va a actualizar, como se muestra en Obtener una jerarquía de carpetas mediante EWS.
A continuación, envíe un mensaje de solicitud de operación UpdateFolder al servidor para actualizar una carpeta. La solicitud de operación UpdateFolder actualiza el DisplayName a "Carpeta personalizada actualizada".
Esta también es la solicitud XML que la API administrada de EWS envía al actualizar una carpeta mediante el método Folder.Update. Los valores de algunos atributos y elementos se han acortado para mejorar la legibilidad.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2007_SP1" />
</soap:Header>
<soap:Body>
<m:UpdateFolder>
<m:FolderChanges>
<t:FolderChange>
<t:FolderId Id="OrV9ZAAA=" ChangeKey="AQAAABYAAABVzRdyy/cHS4XTC9itCRdUAAAOrXWb" />
<t:Updates>
<t:SetFolderField>
<t:FieldURI FieldURI="folder:DisplayName" />
<t:Folder>
<t:DisplayName>Updated Custom Folder</t:DisplayName>
</t:Folder>
</t:SetFolderField>
</t:Updates>
</t:FolderChange>
</m:FolderChanges>
</m:UpdateFolder>
</soap:Body>
</soap:Envelope>
El servidor responde a la solicitud UpdateFolder con un mensaje UpdateFolderResponse que incluye el valor ResponseCode de NoError y el FolderId de la carpeta que se actualizó con un valor de atributo actualizado ChangeKey.
Eliminación de una carpeta mediante la API administrada de EWS
En este artículo se proporciona un ejemplo básico que muestra cómo eliminar una carpeta mediante la API administrada de EWS. Para obtener más información sobre cómo eliminar carpetas, vea Eliminar elementos mediante EWS en Exchange.
Para eliminar una carpeta mediante la API administrada de EWS, en primer lugar, use el método Folder.Bind para enlazar al objeto de servicio a la carpeta que se va a eliminar. A continuación, use el métodoFolder.Delete para eliminar la carpeta mediante el modo de eliminaciónHardDelete.
En este ejemplo se supone que service es un objeto ExchangeService válido y que el usuario se ha autenticado en un servidor Exchange. La variable local folderId es el identificador de la carpeta que se va a eliminar.
// Bind to an existing folder and get all its properties.
// This method call results in a GetFolder call to EWS.
Folder folder = Folder.Bind(service, folderId);
// HardDelete the folder.
// This method call results in a DeleteFolder call to EWS.
folder.Delete(DeleteMode.HardDelete);
Eliminar una carpeta mediante EWS
En este artículo se proporciona un ejemplo XML básico que muestra cómo eliminar una carpeta mediante EWS. Para obtener más información sobre cómo eliminar carpetas, vea Eliminar elementos mediante EWS en Exchange.
Para eliminar una carpeta mediante EWS, en primer lugar, envíe un mensaje de solicitud de operación GetFolder para que la carpeta se actualice como se muestra en Obtener una carpeta mediante EWS.
A continuación, envíe un mensaje de solicitud de operación DeleteFolder al servidor para eliminar la carpeta. La solicitud de operación DeleteFolder indica que el DeleteType es HardDelete e incluye el FolderId de la carpeta que se va a eliminar.
Esta también es la solicitud XML que la API administrada de EWS envía al eliminar una carpeta mediante el método Folder.Delete. Los valores de algunos atributos y elementos se han acortado para mejorar la legibilidad.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2007_SP1" />
</soap:Header>
<soap:Body>
<m:DeleteFolder DeleteType="HardDelete">
<m:FolderIds>
<t:FolderId Id="OrV9ZAAA=" ChangeKey="AQAAABYAAABVzRdyy/cHS4XTC9itCRdUAAAOrXWf" />
</m:FolderIds>
</m:DeleteFolder>
</soap:Body>
</soap:Envelope>
El servidor responde a la solicitud DeleteFolder con un mensaje DeleteFolderResponse que incluye el valor ResponseCode de NoError, que indica que la eliminación de la carpeta se realizó correctamente.
Siguientes pasos
Después de recuperar las carpetas en el servidor o de realizar cambios en las carpetas, es posible que desee sincronizar la jerarquía de carpetas o suscribirse a las notificaciones sobre los cambios de carpeta en el servidor.