EWS Managed API

EWS Managed API to biblioteka programistyczna umożliwiająca integrację aplikacji z usługami Exchange Web Services.

Rola EWS Managed API w komunikacji z Exchange

EWS Managed API to biblioteka programistyczna firmy Microsoft dla platformy .NET, która ułatwia tworzenie aplikacji korzystających z usług Exchange Web Services. Nie jest osobnym serwerem pocztowym ani niezależnym protokołem transportowym. Stanowi warstwę kliencką ukrywającą część szczegółów komunikacji z usługą EWS, która udostępnia operacje dotyczące skrzynek pocztowych, folderów, wiadomości, spotkań, kontaktów i załączników.

Biblioteka wykorzystuje obiekty i metody języka C#, zamiast wymagać ręcznego konstruowania wszystkich żądań SOAP. Programista może utworzyć obiekt ExchangeService, wskazać wersję schematu Exchange, skonfigurować uwierzytelnianie oraz nawiązać połączenie z punktem końcowym EWS. W kodzie używa się między innymi przestrzeni nazw Microsoft.Exchange.WebServices.Data. Sama biblioteka nie przechowuje poczty lokalnie i nie zastępuje klienta użytkownika, takiego jak Outlook.

Obiekty, operacje i struktura danych

Model obiektowy EWS Managed API odwzorowuje podstawowe elementy skrzynki Exchange. Klasa EmailMessage służy do pracy z wiadomościami, Appointment z terminami kalendarza, Contact z kontaktami, a Folder z folderami. Elementy można tworzyć, odczytywać, aktualizować, przenosić, kopiować i usuwać, o ile konto oraz konfiguracja serwera pozwalają na wykonanie danej operacji.

Wiadomość może zawierać temat, treść, adres nadawcy, odbiorców, odbiorców kopii, załączniki oraz właściwości niestandardowe. Elementy są identyfikowane przez ItemId, natomiast foldery przez FolderId. Przy pobieraniu danych można określić zakres właściwości, aby nie przesyłać całego elementu, gdy aplikacja potrzebuje tylko kilku pól. Dla dużych skrzynek istotne jest używanie stronicowania wyników, ponieważ pojedyncze zapytanie zwracające tysiące elementów może zwiększać zużycie pamięci i obciążenie usługi.

Biblioteka udostępnia także wyszukiwanie elementów w folderach, odczytywanie załączników, sprawdzanie dostępności kalendarza oraz synchronizację zmian. Mechanizmy subskrypcji pozwalają otrzymywać informacje o zdarzeniach dotyczących elementów, lecz sposób dostarczania powiadomień zależy od wybranego rodzaju subskrypcji i konfiguracji Exchange.

Uwierzytelnianie, Autodiscover i zgodność środowiska

Połączenie z Exchange wymaga poprawnego uwierzytelnienia oraz dostępu do usługi EWS. EWS Managed API może korzystać z adresu punktu końcowego podanego bezpośrednio albo z mechanizmu Autodiscover. Autodiscover służy do odnalezienia ustawień usługi na podstawie adresu skrzynki, dlatego nieprawidłowy rekord DNS, błędny adres konta lub niedostępna usługa może spowodować niepowodzenie jeszcze przed wykonaniem operacji na wiadomości.

W praktyce należy rozróżnić wersję biblioteki, wersję schematu EWS oraz wersję serwera Exchange. Te wartości nie są tym samym. EWS Managed API 2.2 jest wersją biblioteki przeznaczoną do aplikacji .NET, natomiast parametr wersji usługi określa zestaw funkcji dostępny po stronie Exchange. Zgodność trzeba sprawdzać dla konkretnego środowiska: Exchange Server może mieć inne ustawienia dostępu niż Exchange Online, a administrator może ograniczyć lub wyłączyć dostęp EWS dla określonych skrzynek.

Podczas diagnostyki integracji warto sprawdzić adres EWS, wynik Autodiscover, używany mechanizm uwierzytelniania, uprawnienia konta oraz odpowiedź serwera. Błędy HTTP, wyjątki biblioteki i komunikaty SOAP mogą wskazywać różne problemy: od niepoprawnych danych logowania, przez brak uprawnień do folderu, po niedostępność usługi lub ograniczenie liczby żądań. Sam fakt, że aplikacja uruchamia się bez błędu, nie potwierdza jeszcze poprawności połączenia z konkretną skrzynką.

Znaczenie biblioteki przy analizie problemów z aplikacją pocztową

Problemy związane z EWS Managed API często wynikają z pomieszania warstw. Błąd w aplikacji może pochodzić z kodu obsługującego identyfikatory elementów, z nieprawidłowego adresu usługi, z braku uprawnień albo z różnic między funkcjami dostępnymi w poszczególnych wersjach Exchange. Szczególnie ważne jest rejestrowanie nazwy operacji, folderu, identyfikatora elementu, kodu odpowiedzi i treści wyjątku bez zapisywania haseł lub tokenów uwierzytelniających.

Jeżeli wiadomości są odczytywane, lecz nie są wysyłane, trzeba rozdzielić operację utworzenia elementu od operacji Send. Jeżeli wyszukiwanie zwraca pusty wynik, należy zweryfikować folder, filtr, zakres dat i paginację. Przy problemach z kalendarzem trzeba dodatkowo uwzględnić strefę czasową oraz właściwości spotkania. Takie rozdzielenie pozwala ustalić, czy awaria występuje w bibliotece, w komunikacji z EWS, w uprawnieniach konta, czy w logice programu korzystającego z danych Exchange.

EWS Managed API dotyczy integracji aplikacji z usługami Exchange, dlatego jego analiza wymaga sprawdzenia zarówno kodu .NET, jak i odpowiedzi serwera. W przypadku komputera, na którym uruchamiana jest aplikacja kliencka, Warszawskie Pogotowie Komputerowe wykonuje profesjonalną naprawę laptopów i komputerów PC, obejmującą diagnostykę problemów z oprogramowaniem oraz konfiguracją stanowiska.