Trabalhar com pastas usando o EWS no Exchange
Saiba como criar, obter, atualizar e excluir pastas usando a API Gerenciada do EWS ou o EWS no Exchange.
O EWS no Exchange usa pastas para estruturar e organizar caixas de correio. Você pode obter, atualizar, excluir ou criar novas pastas usando a API Gerenciada do EWS ou o EWS. Cada um dos métodos ou operações listados na tabela a seguir é executado em um objeto Folder, um tipo Folder ou uma das classes ou tipos de pasta derivadas.
Tabela 1. Métodos e operações para criar, obter, atualizar e eliminar pastas
| Para... | Método da API Gerenciada do EWS | Operação do EWS |
|---|---|---|
| Criar uma pasta | Folder.Save | CreateFolder |
| Criar uma hierarquia de pastas | Não disponível | CreateFolderPath |
| Obter uma pasta | Folder.Bind | GetFolder |
| Obter uma hierarquia de pastas | Folder.FindFolders | FindFolder |
| Atualizar uma pasta | Folder.Update | UpdateFolder |
| Excluir uma pasta | Folder.Delete | DeleteFolder |
Criar uma pasta usando a API Gerenciada do EWS
O exemplo de código a seguir mostra como usar a classe Folder para criar uma nova pasta genérica com um DisplayName de "Pasta Personalizada" e um valor de propriedade FolderClass de IPF.Note. O método Folder.Save salva a pasta como uma pasta filho da pasta Caixa de Entrada.
Esses exemplos pressupõem que serviço seja um objeto ExchangeService válido e que o usuário tenha sido autenticado em um 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 criar um tipo diferente de pasta, como CalendarFolder, ContactsFolder, SearchFolder ou TasksFolder, crie uma nova instância da classe específica (em vez da classe Folder genérica) e não defina a propriedade FolderClass. Por exemplo, o exemplo de código a seguir mostra como criar uma nova 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);
Se você tentar criar uma instância de uma classe específica e também definir a propriedade FolderClass, o erro ErrorNoFolderClassOverride será gerado.
Observe que você não pode criar em lote várias pastas em uma única chamada de método usando a API Gerenciada do EWS.
Criar uma pasta usando o EWS
Você pode criar uma única pasta ou várias pastas usando o EWS.
Para criar uma única pasta, envie uma mensagem de solicitação de operação CreateFolder. A solicitação de operação CreateFolder indica que a pasta pai é a Caixa de Entrada, DisplayName é a "Pasta Personalizada" e o valor do elemento FolderClass é IPF.Note.
Essa também é a solicitação XML que a API Gerenciada do EWS envia quando você cria uma nova pasta e chama o 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>
O servidor responde à solicitação CreateFolder com uma mensagem CreateFolderResponse que inclui um valor ResponseCode de NoError, que indica que a pasta foi criada com êxito e a FolderId da mensagem recém-criada.
Para criar várias pastas, inclua vários elementos Folder na mensagem de solicitação de operação CreateFolder. Todas as novas pastas devem estar na mesma pasta pai.
Criar uma hierarquia de pastas usando o EWS
Você pode criar uma hierarquia de pastas em uma única chamada usando a operação CreateFolderPath do EWS. As mesmas funcionalidades não estão disponíveis na API Gerenciada do EWS. Em vez disso, se você estiver usando a API Gerenciada do EWS, poderá criar pastas uma por uma, conforme mostrado em Criar uma pasta usando o EWS.
Observação
A API gerenciada EWS não implementa essa funcionalidade.
Obter uma pasta usando a API Gerenciada do EWS
O exemplo de código a seguir mostra como usar o método Folder.Bind para obter a pasta Caixa de Entrada. Como prática recomendada, limite as propriedades retornadas apenas àquelas necessárias para seu aplicativo. Este exemplo limita as propriedades de retorno para incluir apenas a propriedade Id criando um objeto PropertySet e aplicando o valor IdOnly à propriedade BasePropertySet.
Esse exemplo pressupõe que serviço seja um objeto ExchangeService válido e que o usuário tenha sido autenticado em um 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);
Se você precisar retornar propriedades adicionais, adicione propriedades da classe FolderSchema ao PropertySet ou use um dos métodos Bind sobrecarregados que retorna todas as propriedades de primeira classe.
Observe que você não pode obter várias pastas ao mesmo tempo usando a API Gerenciada do EWS. Você precisa chamar o método Bind em cada pasta separadamente.
Obter uma pasta usando o EWS
Você pode obter uma única pasta ou várias pastas usando o EWS.
Para obter uma única pasta, envie uma mensagem de solicitação de operação GetFolder para o servidor. No exemplo a seguir, BaseShape é definido como IdOnly, portanto, somente FolderId da pasta especificada é retornada. O elemento FolderIds indica que a pasta a ser recuperada é a pasta Caixa de Entrada.
Essa também é a solicitação XML que a API Gerenciada do EWS envia quando você vincula a uma pasta usando o método Folder.Bind.
Para obter várias pastas, inclua vários elementos FolderIds na mensagem de solicitação de operação 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>
O exemplo XML a seguir mostra a mensagem GetFolderResponse que é enviada do servidor para o cliente em resposta à solicitação de operação GetFolder. Ele contém apenas o valor FolderId da pasta Caixa de Entrada. Os valores de alguns atributos e elementos foram reduzidos para legibilidade.
<?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>
Obter uma hierarquia de pastas usando a API Gerenciada do EWS
O exemplo de código a seguir mostra como recuperar as subpastas de uma pasta raiz especificada. Este exemplo recupera as subpastas da pasta MsgFolderRoot, que é a raiz da Subárvore IPM (onde suas pastas de caixa de correio e itens são armazenados).
Neste exemplo, um objeto de classe FolderView é criado para limitar os resultados da resposta do método Folder.FindFolders. Esse cenário limita as propriedades a retornar ao seguinte: Id, DisplayName e a propriedade estendida que indica se a pasta é uma pasta oculta. Defina o valor FolderView.Traversal como Deep para executar uma pesquisa recursiva para que o servidor recupere as subpastas. Defina a pasta raiz como MsgFolderRoot, para que o servidor retorne todas as pastas do usuário (e o servidor não retorne pastas do sistema na Subárvore não-IPM).
Esse exemplo pressupõe que serviço seja um objeto ExchangeService válido e que o usuário tenha sido autenticado em um 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);
Obter uma hierarquia de pastas usando o EWS
Os exemplos XML a seguir mostram como usar a operação FindFolder para recuperar uma hierarquia de pastas usando o EWS. Este exemplo recupera a pasta msgfolderroot, que é pasta raiz da Subárvore IPM e todas as suas subpastas. O atributo Traversal é definido como Deep para que o servidor execute uma pesquisa recursiva da hierarquia de pastas e retorne apenas pastas e subpastas sob a raiz especificada na resposta. Neste exemplo, o elemento BaseShape é definido como IdOnly para que o servidor retorne apenas o elemento FolderId. Para facilitar a compreensão do resultado, inclua o elemento DisplayName em seus resultados, incluindo-o no elemento AdditionalProperties na solicitação, junto com o valor ExtendedFieldURI para a propriedade PR_ATTR_HIDDEN, para você saber se as pastas são pastas ocultas.
Essa também é a solicitação XML que a API Gerenciada do EWS envia quando você chama o 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>
O exemplo XML a seguir mostra a mensagem FindFolderResponse que é enviada do servidor para o cliente em resposta à solicitação de operação FindFolder. Ela contém apenas FolderId, DisplayName e o valor da propriedade estendida PR_ATTR_HIDDEN para todas as subpastas na pasta msgrootfolder. Se o elemento Value estiver definido como true, a pasta deve estar oculta na exibição do cliente.
Essa também é a resposta XML que a API Gerenciada do EWS envia quando você obtém várias pastas usando o método FindFolder. Os valores de alguns atributos e elementos foram reduzidos para legibilidade e algumas pastas não foram incluídas para brevidade.
<?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>
Atualizar uma pasta usando a API Gerenciada do EWS
O exemplo de código a seguir mostra como atualizar o nome de exibição de uma pasta usando a API Gerenciada do EWS.
Primeiro, crie um PropertySet para limitar o número de propriedades que o servidor retorna na resposta Folder.Bind. Recomendamos que utilize o IdOnlyBasePropertySet para reduzir as chamadas para a base de dados do Exchange. Em seguida, use o método Bind para vincular à pasta a ser atualizada. Em seguida, atualize a propriedade DisplayName e use o método Folder.Update para salvar as alterações.
Nesse exemplo, supomos que serviço seja um objeto ExchangeService válido e que o usuário tenha sido autenticado em um servidor Exchange. O folderId da variável local é o ID da pasta a atualizar.
// 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();
Atualizar uma pasta usando o EWS
Os exemplos XML a seguir mostram como atualizar o nome de exibição de uma pasta usando o EWS.
Primeiro, envie uma mensagem de solicitação de operação GetFolder para atualizar a pasta, conforme mostrado em Obter uma hierarquia de pastas usando o EWS.
Em seguida, envie uma mensagem de solicitação de operação UpdateFolder ao servidor para atualizar uma pasta. A solicitação de operação UpdateFolder atualiza DisplayName como "Pasta Personalizada Atualizada".
Essa também é a solicitação XML que a API Gerenciada do EWS envia quando você atualiza uma pasta usando o método Folder.Update. Os valores de alguns atributos e elementos foram reduzidos para legibilidade.
<?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>
O servidor responde à solicitação UpdateFolder com uma mensagem UpdateFolderResponse que inclui o valor ResponseCode de NoError e FolderId da pasta que foi atualizada com um valor do atributo ChangeKey atualizado.
Excluir uma pasta usando a API Gerenciada do EWS
Este artigo fornece um exemplo básico que mostra como excluir uma pasta usando a API Gerenciada do EWS. Para obter mais detalhes sobre como excluir pastas, confira Excluir itens usando o EWS no Exchange.
Para excluir uma pasta usando a API Gerenciada do EWS, primeiro, use o método Folder.Bind para vincular o objeto de serviço à pasta a ser excluída. Depois, use o método Folder.Delete para excluir a pasta usando o modo de exclusão HardDelete.
Esse exemplo pressupõe que serviço seja um objeto ExchangeService válido e que o usuário tenha sido autenticado em um servidor Exchange. O folderId da variável local é o ID da pasta 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);
Excluir uma pasta usando o EWS
Este artigo fornece um exemplo XML básico que mostra como excluir uma pasta usando o EWS. Para obter mais detalhes sobre como excluir pastas, confira Excluir itens usando o EWS no Exchange.
Para excluir uma pasta usando o EWS, primeiro, envie uma mensagem de solicitação de operação GetFolder para atualizar a pasta conforme mostrado em Obter uma pasta usando o EWS.
Em seguida, envie uma mensagem de solicitação de operação DeleteFolder ao servidor para excluir a pasta. A solicitação de operação DeleteFolder indica que DeleteType é HardDelete e inclui FolderId da pasta a ser excluída.
Essa também é a solicitação XML que a API Gerenciada do EWS envia quando você exclui uma pasta usando o método Folder.Delete. Os valores de alguns atributos e elementos foram reduzidos para legibilidade.
<?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>
O servidor responde à solicitação DeleteFolder com uma mensagem DeleteFolderResponse que inclui o valor ResponseCode de NoError, que indica que a exclusão da pasta foi bem-sucedida.
Próximas etapas
Depois de recuperar as pastas no servidor ou fazer alterações em pastas, talvez você queira sincronizar sua hierarquia de pastas ou assinar notificações sobre alterações de pasta no servidor.