Utiliser des dossiers masqués à l’aide d’EWS dans Exchange
Découvrez comment masquer un dossier et rechercher des dossiers masqués à l’aide de l’API managée EWS ou EWS dans Exchange.
À une exception près, les dossiers à la racine d’une boîte aux lettres Exchange (la sous-arborescence non IPM) sont masqués pour l’utilisateur. À l’inverse, tous les dossiers de msgFolderRoot (sous-arborescence IPM) sont visibles par l’utilisateur. Comment masquer un dossier sous MsgFolderRoot ? Ce n’est pas si compliqué: il s’agit d’une seule propriété, la propriété étendue PidTagAttributeHidden (0x10F4000B). Lorsque cette propriété a la valeur true, Outlook ou un autre client qui utilise la propriété pour déterminer la visibilité du dossier masque le dossier de l’affichage de l’utilisateur. Comme il s’agit d’une propriété étendue, elle est plus complexe à utiliser que votre propriété de dossier moyenne. Cet article vous guide dans les principaux scénarios.
Tableau 1. Méthodes d’API managée EWS et opérations EWS pour l’utilisation de dossiers masqués
| Tâche | Méthode d'API managée EWS | Opération EWS |
|---|---|---|
| Masquer un dossier |
Folder.Bind suivi de Folder.Update |
GetFolder suivi de UpdateFolder |
| Rechercher des dossiers masqués |
FindFolders |
FindFolder |
Vous demandez-vous quelle est la seule exception , c’est-à-dire, quel dossier de la racine EST visible par les utilisateurs ? Il s’agit du dossier Finder (également appelé valeur d’énumération SearchFoldersWellKnownFolder ou valeur de l’élément SearchFolderId) qui contient les dossiers de recherche des utilisateurs. Les dossiers de recherche créés dans le dossier Finder sont visibles par les utilisateurs Outlook. Si vous devez créer un dossier de recherche qui n’est pas visible par les utilisateurs, déplacez-le sous le dossier racine pour le masquer. Contrairement à d’autres dossiers, la définition de la propriété PidTagAttributeHidden sur true ne masque pas un dossier de recherche dans le dossier Finder.
Masquer un dossier à l’aide de l’API managée EWS
Vous pouvez faire d’un dossier existant un dossier masqué en remplaçant la propriété étendue PidTagAttributeHidden sur true. Tout d’abord, créez une définition de propriété étendue pour la propriété . Ensuite, utilisez la méthode Bind pour accéder au dossier, puis mettez à jour la valeur de la propriété PidTagAttributeHidden sur true, puis utilisez la méthode Update pour enregistrer les modifications.
Cet exemple suppose que le service est un objet ExchangeService valide pour le propriétaire de la boîte aux lettres, que l’utilisateur a été authentifié auprès d’un serveur Exchange et que folderId est un Folder.Id valide qui identifie le dossier à masquer.
private static void MakeHidden(FolderId folderId, ExchangeService service)
{
// Create an extended property definition for the PidTagAttributeHidden property.
ExtendedPropertyDefinition isHiddenProp = new ExtendedPropertyDefinition(0x10f4, MapiPropertyType.Boolean);
PropertySet propSet = new PropertySet(isHiddenProp);
// Bind to a folder and retrieve the PidTagAttributeHidden property.
Folder folder = Folder.Bind(service, folderId, propSet);
// Set the PidTagAttributeHidden property to true.
folder.SetExtendedProperty(isHiddenProp, true);
// Save the changes.
folder.Update();
}
Masquer un dossier à l’aide d’EWS
Vous pouvez utiliser EWS pour faire d’un dossier existant un dossier masqué en remplaçant la propriété étendue PidTagAttributeHidden par true. Tout d’abord, utilisez l’opération GetFolder pour accéder au dossier, puis récupérez la propriété PidTagAttributeHidden en incluant l’élément ExtendedFieldURI et en définissant la valeur PropertyTag sur 4340 et la valeur PropertyType sur Boolean.
Il s’agit également de la requête XML envoyée par l’API managée EWS lorsque vous utilisez la méthode Bind pour obtenir un dossier avant d’en faire un dossier masqué.
La valeur FolderId est raccourcie pour plus de lisibilité.
<?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>
<t:AdditionalProperties>
<t:ExtendedFieldURI PropertyTag="4340"
PropertyType="Boolean" />
</t:AdditionalProperties>
</m:FolderShape>
<m:FolderIds>
<t:FolderId Id="IQywAAAA==" />
</m:FolderIds>
</m:GetFolder>
</soap:Body>
</soap:Envelope>
Le serveur répond à la requête GetFolder avec un message GetFolderResponse qui inclut une valeur d’élément ResponseCodenoError, ce qui indique que le dossier a été récupéré avec succès. La réponse inclut également une valeur pour ExtendedProperty. Dans cet exemple, la valeur est définie sur false, ce qui signifie que le dossier n’est actuellement pas masqué.
<?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="898"
MinorBuildNumber="23"
Version="V2_10"
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="IQywAAAA=="
ChangeKey="AQAAABYAAAD32nSTjepyT63rYH17n9THAAAAABED" />
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean" />
<t:Value>false</t:Value>
</t:ExtendedProperty>
</t:Folder>
</m:Folders>
</m:GetFolderResponseMessage>
</m:ResponseMessages>
</m:GetFolderResponse>
</s:Body>
</s:Envelope>
Pour remplacer la valeur de ExtendedProperty par true, utilisez l’opération UpdateFolder . Incluez les éléments ExtendedProperty, ExtendedFieldURI et Value pour la propriété étendue PidTagAttributeHidden et définissez l’élément Value sur true pour masquer le dossier.
Il s’agit également de la requête XML que l’API managée EWS envoie lorsque vous utilisez la méthode Update pour mettre à jour un dossier afin qu’il soit un dossier masqué.
<?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="IQywAAAA=="
ChangeKey="AQAAABYAAAD32nSTjepyT63rYH17n9THAAAAABED" />
<t:Updates>
<t:SetFolderField>
<t:ExtendedFieldURI PropertyTag="4340"
PropertyType="Boolean" />
<t:Folder>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="4340"
PropertyType="Boolean" />
<t:Value>true</t:Value>
</t:ExtendedProperty>
</t:Folder>
</t:SetFolderField>
</t:Updates>
</t:FolderChange>
</m:FolderChanges>
</m:UpdateFolder>
</soap:Body>
</soap:Envelope>
Le serveur répond à la requête UpdateFolder avec un message UpdateFolderResponse qui inclut une valeur d’élément ResponseCodeNoError, ce qui indique que le dossier a été mis à jour correctement et qu’il est désormais masqué.
Rechercher tous les dossiers masqués à l’aide de l’API managée EWS
Vous pouvez trouver tous les dossiers masqués sous un dossier parent en créant une définition de propriété étendue pour la propriété étendue PidTagAttributeHidden , puis en utilisant la méthode FindFolders pour rechercher les dossiers avec une valeur PidTagAttributeHidden définie sur true. Cet exemple utilise msgFolderRoot, également appelé Top of Information Store, ou IPM Subtree, comme dossier parent sous lequel effectuer la recherche.
Cet exemple suppose que le service est un objet ExchangeService valide pour le propriétaire de la boîte aux lettres et que l’utilisateur a été authentifié auprès d’un serveur Exchange.
private static void FindHiddenFolders(ExchangeService service)
{
// Create an extended property definition for the PidTagAttributeHidden property.
ExtendedPropertyDefinition isHiddenProp = new ExtendedPropertyDefinition(0x10f4, MapiPropertyType.Boolean);
// Create a folder view to retrieve up to 100 folders and
// retrieve only the PidTagAttributeHidden and the display name.
FolderView folderView = new FolderView(100);
folderView.PropertySet = new PropertySet(isHiddenProp, FolderSchema.DisplayName);
// Indicate a Traversal value of Deep, so that all subfolders are retrieved.
folderView.Traversal = FolderTraversal.Deep;
// Find all hidden folders under the MsgFolderRoot.
// This call results in a FindFolder call to EWS.
FindFoldersResults findFolder = service.FindFolders(WellKnownFolderName.MsgFolderRoot,
new SearchFilter.IsEqualTo(isHiddenProp, true), folderView);
// Display the folder ID and display name of each hidden folder.
foreach (Folder folder in findFolder)
{
Console.WriteLine("FolderId: {0}", folder.Id);
Console.WriteLine("DisplayName: {0}", folder.DisplayName);
Console.WriteLine("\r\n");
}
}
Rechercher tous les dossiers masqués à l’aide d’EWS
Vous pouvez utiliser EWS pour rechercher tous les dossiers masqués sous un dossier existant en appelant l’opération FindFolder et en recherchant les dossiers dont la propriété étendue PidTagAttributeHidden a la valeur true. Pour ce faire, incluez une restrictionIsEqualTo qui recherche l’élément ExtendedFieldURI pour la propriété PidTagAttributeHidden ( valeur PropertyTag à 4243 et la valeur PropertyType à Boolean), comme indiqué dans la requête suivante. Cet exemple utilise msgFolderRoot, également appelé Top of Information Store, ou IPM Subtree, comme dossier parent sous lequel effectuer la recherche.
Il s’agit également de la requête XML que l’API managée EWS envoie lorsque vous utilisez la méthode FindFolders pour rechercher tous les dossiers masqués.
<?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" />
<t:TimeZoneContext>
<t:TimeZoneDefinition Id="Central Standard Time" />
</t:TimeZoneContext>
</soap:Header>
<soap:Body>
<m:FindFolder Traversal="Deep">
<m:FolderShape>
<t:BaseShape>IdOnly</t:BaseShape>
<t:AdditionalProperties>
<t:ExtendedFieldURI PropertyTag="4340"
PropertyType="Boolean" />
<t:FieldURI FieldURI="folder:DisplayName" />
</t:AdditionalProperties>
</m:FolderShape>
<m:IndexedPageFolderView MaxEntriesReturned="100"
Offset="0"
BasePoint="Beginning" />
<m:Restriction>
<t:IsEqualTo>
<t:ExtendedFieldURI PropertyTag="4340"
PropertyType="Boolean" />
<t:FieldURIOrConstant>
<t:Constant Value="true" />
</t:FieldURIOrConstant>
</t:IsEqualTo>
</m:Restriction>
<m:ParentFolderIds>
<t:DistinguishedFolderId Id="msgfolderroot" />
</m:ParentFolderIds>
</m:FindFolder>
</soap:Body>
</soap:Envelope>
Le serveur répond à la requête FindFolder avec un message FindFolderResponse qui inclut une valeur d’élément ResponseCodeNoError, ce qui indique que la recherche de dossiers a réussi, ainsi que tous les dossiers masqués sous le dossier de message racine.
Les valeurs FolderId sont raccourcies pour plus de lisibilité.
<?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="898"
MinorBuildNumber="23"
Version="V2_10"
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="6"
TotalItemsInView="6"
IncludesLastItemInRange="true">
<t:Folders>
<t:ContactsFolder>
<t:FolderId Id="IBHgAAAA=="
ChangeKey="AwAAABYAAAD32nSTjepyT63rYH17n9THAAAAAACz" />
<t:DisplayName>{06967759-274D-40B2-A3EB-D7F9E73727D7}</t:DisplayName>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean" />
<t:Value>true</t:Value>
</t:ExtendedProperty>
</t:ContactsFolder>
<t:ContactsFolder>
<t:FolderId Id="IBHwAAAA=="
ChangeKey="AwAAABYAAAD32nSTjepyT63rYH17n9THAAAAAAC7" />
<t:DisplayName>{A9E2BC46-B3A0-4243-B315-60D991004455}</t:DisplayName>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean" />
<t:Value>true</t:Value>
</t:ExtendedProperty>
</t:ContactsFolder>
<t:ContactsFolder>
<t:FolderId Id="IBIQAAAA=="
ChangeKey="AwAAABYAAAD32nSTjepyT63rYH17n9THAAAAAADO" />
<t:DisplayName>GAL Contacts</t:DisplayName>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean" />
<t:Value>true</t:Value>
</t:ExtendedProperty>
</t:ContactsFolder>
<t:ContactsFolder>
<t:FolderId Id="IBHQAAAA=="
ChangeKey="AwAAABYAAAD32nSTjepyT63rYH17n9THAAAAAACa" />
<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="HAAAAA=="
ChangeKey="AQAAABYAAAD32nSTjepyT63rYH17n9THAAAAAACS" />
<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:Folder>
<t:FolderId Id="IQywAAAA=="
ChangeKey="AQAAABYAAAD32nSTjepyT63rYH17n9THAAAeZIBf" />
<t:DisplayName>TestFolder</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>
Une fois que vous avez masqué ou non masqué des dossiers, vous souhaiterez peut-être obtenir la hiérarchie des dossiers ou synchroniser la hiérarchie des dossiers. Les exemples qui montrent comment obtenir une hiérarchie de dossiers à l’aide de l’API managée EWS ou obtenir une hiérarchie de dossiers à l’aide d’EWS indiquent également les dossiers de la hiérarchie qui sont masqués.