透過 Exchange Web Service (EWS) 來取得人員與會議室空閒的時段

前言

要 Book 一堆人及會議室時，是一件很累人的事情。
平常 Book 的方式就是，將與會人員及會議室加在一起，
然後努力地看那個時間點是大家有空閒的時間，
那個會議室在那個區段也是空閒的，如下，

那是不是有什麼方式可以節省肉搜的時間呢?
使用 Exchange Web Service (EWS) 提供的 GetUserAvailability 就可以達到這個需求哦~

實作

Q.要如何知道 2023/05/19 這天，chris, ericlin 及 janet 有那些會議呢?
Q.在 2023/05/19 這天， chris, ericlin 及 janet 要開會 1.5 小時，他們有那些時段可以選呢?
Q.在 2023/05/19 這天， 要 Book chris, ericlin 及 janet 及 會議室 1.5 小時，他們有那些時段可以選呢?

以下就下述的問題透過 EWS 取出需要的資訊，

1.專案請加入 Microsoft.Exchange.WebServices Nuget 套件及 System.DirectoryServices 參考。

2.接下來 EWS 的 Web Service URL 及設定連線人員帳/密，呼叫 GetAvailability 來取得資訊，如下，

using Microsoft.Exchange.WebServices.Data;
using System.Collections.ObjectModel;
using System.DirectoryServices;

var adhost = "LDAP://你的 dns server";
var adUser = "要查的User";
var adUserPwd = "password";
var domainName = "你的exchangeDomain";
var dateFormat = "yyyy/MM/dd";
var timeFormat = "HH:mm:ss";

var service = new ExchangeService();
service.Credentials = new WebCredentials(adUser, adUserPwd);
//service.TraceEnabled = true;
//service.TraceFlags = TraceFlags.All;
var serverUrl = @"https://你的exchangeFQDN//EWS/Exchange.asmx";
service.Url = new Uri(serverUrl);
DateTime from = new DateTime(2023, 5, 19);
DateTime to = new DateTime(2023, 5, 19, 23, 59, 59);

//取得這群人有空的時間
var users = new List<AttendeeInfo>();
users.Add(new AttendeeInfo($"chris@{domainName}"));
users.Add(new AttendeeInfo($"ericlin@{domainName}"));
users.Add(new AttendeeInfo($"janet@{domainName}"));
//1.5小時
var meetingHours = 1.5;
//取得這些人會議時間跟建議的空閒時間
var freeBusyResults = GetAvailability(service, users, meetingHours, from, to
    , AvailabilityData.FreeBusyAndSuggestions);

//Q.要如何知道 2023/05/19 這天，chris, ericlin 及 janet 有那些會議資訊呢?
//那些人有會議時間 (AvailabilityData.FreeBusy or AvailabilityData.FreeBusyAndSuggestions) 才會有資料
Console.WriteLine("Q.要如何知道 2023/05/19 這天，chris, ericlin 及 janet 有那些會議呢?");
int i = 0;
foreach (var availability in freeBusyResults.AttendeesAvailability)
{
    if(availability.CalendarEvents.Count > 0)
    {
        Console.WriteLine("使用者:{0}:\n", users[i].SmtpAddress);
        foreach (CalendarEvent calEvent in availability.CalendarEvents)
        {
            Console.WriteLine("\t{0}~{1}({2}) \n"
                , calEvent.StartTime.ToString($"{dateFormat} {timeFormat}")
                , calEvent.EndTime.ToString($"{dateFormat} {timeFormat}")
                , calEvent.Details?.Subject);
        }
    }
    i++;
}
//註: calEvent.Details 如果為 null ，表示該使用者沒有給別人看 行事曆的權限

//Q.在 2023/05/19 這天， chris, ericlin 及 janet 要開會 1.5 小時，他們有那些時段可以選呢?
//建議的空閒時間 (AvailabilityData.Suggestions or AvailabilityData.FreeBusyAndSuggestions) 才會有資料
Console.WriteLine("Q.在 2023/05/19 這天， chris, ericlin 及 janet 要開會 1.5 小時，他們有那些時段可以選呢?");
foreach (Suggestion suggestion in freeBusyResults.Suggestions)
{
    Console.WriteLine($"Suggested date: {suggestion.Date}，會議期間 {meetingHours}\n", suggestion.Date.ToString(dateFormat));
    Console.WriteLine("Suggested meeting times:\n");
    foreach (TimeSuggestion timeSuggestion in suggestion.TimeSuggestions)
    {
        Console.WriteLine("\t{0} - {1}\n",
            timeSuggestion.MeetingTime.ToString(timeFormat),
            timeSuggestion.MeetingTime.Add(TimeSpan.FromHours(meetingHours)).ToString(timeFormat));
    }
}

//Q.在 2023/05/19 這天， 要 Book chris, ericlin 及 janet 及 會議室 1.5 小時，他們有那些時段可以選呢?
Console.WriteLine("====== 取出所有會議室的 Email ==========");
var root = new DirectoryEntry(adhost, adUser, adUserPwd);
//找出 Exchange 中所有的會議室
string filter = "(&(objectClass=*)(msExchRecipientDisplayType=7))";
DirectorySearcher search = new DirectorySearcher(filter);
search.SearchRoot = root;
List<AttendeeInfo> rooms = new List<AttendeeInfo>();
foreach (SearchResult result in search.FindAll())
{
    ResultPropertyCollection r = result.Properties;
    DirectoryEntry entry = result.GetDirectoryEntry();
    var pns = entry.Properties.PropertyNames;
    var roomMailAddr = entry.Properties["mail"].Value.ToString().Trim();
    var roomName = entry.Properties["name"].Value.ToString().Trim();
    //容納人數
    var capacity = Convert.ToInt32(entry.Properties["msExchResourceCapacity"].Value);
    if(capacity <= 5)
    {
        //只需5人以下的會議室
        rooms.Add(new AttendeeInfo(roomMailAddr));
    }
    Console.WriteLine($"{roomName}:{roomMailAddr}/容納人數:{capacity}");
}

Console.WriteLine("Q.在 2023/05/19 這天， 要 Book chris, ericlin 及 janet 及 會議室 1.5 小時，他們有那些時段可以選呢?");
//取得使用者們跟各個會議室的空間時間，
foreach (AttendeeInfo room in rooms)
{
    Console.WriteLine($"會議室:{room.SmtpAddress} ======");
    var roomUsers = users.Concat(new[] {room }).ToList();
    //只取建議空間時間，所以最後一個參數用 AvailabilityData.Suggestions
    var roomSuggestions = GetAvailability(service, roomUsers, meetingHours, from, to
        , AvailabilityData.Suggestions);
    foreach (Suggestion roomSuggestion in roomSuggestions.Suggestions)
    {
        Console.WriteLine($"date: {roomSuggestion.Date}，會議期間 {meetingHours}\n", roomSuggestion.Date.ToString(dateFormat));
        Console.WriteLine("Suggested meeting times:\n");
        foreach (var timeSuggestion in roomSuggestion.TimeSuggestions)
        {
            Console.WriteLine("\t{0} - {1}\n",
                timeSuggestion.MeetingTime.ToString($"{dateFormat} {timeFormat}"),
                timeSuggestion.MeetingTime.Add(TimeSpan.FromHours(meetingHours)).ToString($"{dateFormat} {timeFormat}"));
        }
    }
    Console.WriteLine($"會議室:{room.SmtpAddress}======");
}
Console.ReadKey();

static GetUserAvailabilityResults GetAvailability(ExchangeService service,
   List<AttendeeInfo> users, double meetingHours
   , DateTime from, DateTime to
   , AvailabilityData availabilityData)
{
    var meetingDuration = TimeSpan.FromHours(meetingHours).TotalMinutes;
    //最小單位是 30 分
    if (meetingDuration < 30)
        meetingDuration = 30;

    var dur = to.Subtract(from);
    var toOriginal = to;
    //最小是一天
    if (dur.TotalHours < 24)
        to = from.AddDays(1);

    var suggestionDuration = new TimeWindow(from, to);
    var options = new AvailabilityOptions();

    //0~48 預設是 10 ，可自行調整
    options.MaximumSuggestionsPerDay = 10;
    options.MeetingDuration = Convert.ToInt32(meetingDuration);
    options.RequestedFreeBusyView = FreeBusyViewType.Detailed;
    var freeBusyResults = service.GetUserAvailability(users
        , suggestionDuration
        , availabilityData
        , options);
    return freeBusyResults;
}

• 註: 因為我會議室沒有放到 RoomList 之中，所以透過 AD 來 Search 出來

執行結果如下，

可以發現在 5/19 ，只有 chis 及 janet 有會議

可以發現，這 3 人最合適的時間為 2023/05/19 16:30:00 - 2023/05/19 18:00:00

列出所有的會議室及容納人數

參考資源

Get free/busy information by using EWS in Exchange
Exchange Development: Finding Rooms and Busy/Free status with Suggestions for Meeting
GetUserAvailability