Добавление возможностей электронной почты в приложения .NET с помощью Microsoft Graph

В этой статье описано, как расширить приложение, созданное в разделе Создание приложений .NET, с помощью Microsoft Graph с помощью API почты Microsoft Graph. Вы используете Microsoft Graph для вывода списка папки "Входящие" пользователя и отправки сообщения электронной почты.

Перечисление папки "Входящие" пользователя

Начните с перечисления сообщений в почтовом ящике пользователя.

  1. Откройте ./GraphHelper.cs и добавьте следующую функцию в класс GraphHelper .

    public static Task<MessageCollectionResponse?> GetInboxAsync()
{
    // Ensure client isn't null
    _ = userClient ??
        throw new NullReferenceException("Graph has not been initialized for user auth");

    return userClient.Me
        .MailFolders["Inbox"] // Only messages from Inbox folder
        .Messages
        .GetAsync((config) =>
        {
            /* Only request specific properties */
            config.QueryParameters.Select = ["from", "isRead", "receivedDateTime", "subject"];
            /* Get at most 25 results */
            config.QueryParameters.Top = 25;
            /* Sort by received time, newest first */
            config.QueryParameters.Orderby = ["receivedDateTime DESC"];
        });
}

  2. Замените пустую ListInboxAsync функцию в Program.cs на следующую.

    async Task ListInboxAsync()
{
    try
    {
        var messagePage = await GraphHelper.GetInboxAsync();

        if (messagePage?.Value == null)
        {
            Console.WriteLine("No results returned.");
            return;
        }

        // Output each message's details
        foreach (var message in messagePage.Value)
        {
            Console.WriteLine($"Message: {message.Subject ?? "NO SUBJECT"}");
            Console.WriteLine($"  From: {message.From?.EmailAddress?.Name}");
            Console.WriteLine($"  Status: {(message.IsRead!.Value ? "Read" : "Unread")}");
            Console.WriteLine($"  Received: {message.ReceivedDateTime?.ToLocalTime().ToString()}");
        }

        // If NextPageRequest is not null, there are more messages
        // available on the server
        // Access the next page like:
        // var nextPageRequest = new MessagesRequestBuilder(messagePage.OdataNextLink, _userClient.RequestAdapter);
        // var nextPage = await nextPageRequest.GetAsync();
        var moreAvailable = !string.IsNullOrEmpty(messagePage.OdataNextLink);

        Console.WriteLine($"\nMore messages available? {moreAvailable}");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Error getting user's inbox: {ex.Message}");
    }
}

  3. Запустите приложение, войдите в систему и выберите вариант 2, чтобы получить список папки "Входящие".

    Please choose one of the following options:
0. Exit
1. Display access token
2. List my inbox
3. Send mail
4. Make a Graph call
2
Message: Updates from Ask HR and other communities
  From: Contoso Demo on Yammer
  Status: Read
  Received: 12/30/2021 4:54:54 AM -05:00
Message: Employee Initiative Thoughts
  From: Patti Fernandez
  Status: Read
  Received: 12/28/2021 5:01:10 PM -05:00
Message: Voice Mail (11 seconds)
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021 5:00:46 PM -05:00
Message: Our Spring Blog Update
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021 4:49:46 PM -05:00
Message: Atlanta Flight Reservation
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021 4:35:42 PM -05:00
Message: Atlanta Trip Itinerary - down time
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021 4:22:04 PM -05:00

...

More messages available? True

Описание GetInboxAsync

Рассмотрим код в GetInboxAsync функции.

Доступ к известным почтовым папкам

Функция использует построитель _userClient.Me.MailFolders["Inbox"].Messages запросов, который создает запрос к API списка сообщений . Так как он включает построитель MailFolders["Inbox"] запросов, API возвращает только сообщения в запрошенной папке почты. В этом случае, так как папка "Входящие" является хорошо известной папкой по умолчанию в почтовом ящике пользователя, она доступна по известному имени. Доступ к папкам без изменений можно получить таким же образом, заменив известное имя свойством идентификатора почтовой папки. Дополнительные сведения о доступных известных именах папок см. в разделе Тип ресурса mailFolder.

Доступ к коллекции

GetUserAsync В отличие от функции из предыдущего раздела, которая возвращает один объект, этот метод возвращает коллекцию сообщений. Большинство API в Microsoft Graph, возвращающих коллекцию, не возвращают все доступные результаты в одном ответе. Вместо этого они используют разбиение на страницы для возврата части результатов, предоставляя метод для клиентов, чтобы запросить следующую страницу.

Размеры страниц по умолчанию

API, использующие разбиение на страницы, реализуют размер страницы по умолчанию. Для сообщений значение по умолчанию — 10. Клиенты могут запрашивать больше (или меньше) с помощью параметра запроса $top . В GetInboxAsyncдобавление $top выполняется с помощью .Top(25) метода .

Примечание.

Значение, передаваемое в .Top() , является верхней границей, а не явным числом. API возвращает количество сообщений до указанного значения.

Получение последующих страниц

Если на сервере доступно больше результатов, ответы коллекции содержат @odata.nextLink свойство с URL-адресом API для доступа к следующей странице. Клиентская библиотека .NET предоставляет NextPageRequest свойство объектов страницы коллекции. Если это свойство не равно NULL, доступны дополнительные результаты.

Свойство NextPageRequest предоставляет метод, GetAsync который возвращает следующую страницу.

Сортировка коллекций

Функция использует OrderBy метод в запросе для запроса результатов, отсортированных по времени получения сообщения (ReceivedDateTime свойство). Он включает в себя DESC ключевое слово, чтобы сообщения, полученные в последнее время, были перечислены первыми. Этот метод добавляет параметр запроса $orderby в вызов API.

Отправка почты

Теперь добавьте возможность отправки сообщения электронной почты в качестве пользователя, прошедшего проверку подлинности.

  1. Откройте ./GraphHelper.cs и добавьте следующую функцию в класс GraphHelper .

    public static async Task SendMailAsync(string subject, string body, string recipient)
{
    // Ensure client isn't null
    _ = userClient ??
        throw new NullReferenceException("Graph has not been initialized for user auth");

    // Create a new message
    var message = new Message
    {
        Subject = subject,
        Body = new ItemBody
        {
            Content = body,
            ContentType = BodyType.Text,
        },
        ToRecipients =
        [
            new Recipient
            {
                EmailAddress = new EmailAddress
                {
                    Address = recipient,
                },
            },
        ],
    };

    // Send the message
    await userClient.Me
        .SendMail
        .PostAsync(new SendMailPostRequestBody
        {
            Message = message,
        });
}

  2. Замените пустую SendMailAsync функцию в Program.cs на следующую.

    async Task SendMailAsync()
{
    try
    {
        // Send mail to the signed-in user
        // Get the user for their email address
        var user = await GraphHelper.GetUserAsync();

        var userEmail = user?.Mail ?? user?.UserPrincipalName;

        if (string.IsNullOrEmpty(userEmail))
        {
            Console.WriteLine("Couldn't get your email address, canceling...");
            return;
        }

        await GraphHelper.SendMailAsync(
            "Testing Microsoft Graph",
            "Hello world!",
            userEmail);

        Console.WriteLine("Mail sent.");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Error sending mail: {ex.Message}");
    }
}

  3. Запустите приложение, войдите в систему и выберите вариант 3, чтобы отправить себе сообщение электронной почты.

    Please choose one of the following options:
0. Exit
1. Display access token
2. List my inbox
3. Send mail
4. Make a Graph call
3
Mail sent.

    Примечание.

    Если вы тестируете с помощью клиента разработчика из Программы разработчика Microsoft 365, отправленное сообщение электронной почты может не быть доставлено, и вы можете получить отчет о недоставке. Если вы хотите разблокировать отправку почты из клиента, обратитесь в службу поддержки через Центр администрирования Microsoft 365.

  4. Чтобы убедиться, что сообщение получено, выберите вариант 2, чтобы получить список папки "Входящие".

Описание SendMailAsync

Рассмотрим код в SendMailAsync функции.

Отправка почты

Функция использует построитель _userClient.Me.SendMail запросов, который создает запрос к API отправки почты . Построитель запросов принимает объект, Message представляющий сообщение для отправки.

Создание объектов

В отличие от предыдущих вызовов Microsoft Graph, которые считывают только данные, этот вызов создает данные. Чтобы создать элементы с помощью клиентской библиотеки, создайте экземпляр класса , представляющего данные (в данном случае ) Microsoft.Graph.Messageс помощью new ключевое слово, задайте нужные свойства, а затем отправьте их в вызове API. Так как вызов отправляет данные, PostAsync вместо используется GetAsyncметод .

Следующее действие

Добавление дополнительных API Microsoft Graph

  • Last updated on