|
| 1 | +### PosInformatique.Foundations.Emailing.Graph |
| 2 | + |
| 3 | +[](https://www.nuget.org/packages/PosInformatique.Foundations.Emailing.Graph/) |
| 4 | +[](https://www.nuget.org/packages/PosInformatique.Foundations.Emailing.Graph/) |
| 5 | + |
| 6 | +## Introduction |
| 7 | + |
| 8 | +[PosInformatique.Foundations.Emailing.Graph](https://www.nuget.org/packages/PosInformatique.Foundations.Emailing.Graph/) |
| 9 | +provides an `IEmailProvider` |
| 10 | +implementation for [PosInformatique.Foundations.Emailing](../Emailing/README.md) based on the **Microsoft Graph** API. |
| 11 | + |
| 12 | +It uses [Microsoft.Graph.GraphServiceClient](https://learn.microsoft.com/en-us/graph/sdks/create-client?tabs=csharp) |
| 13 | +to send templated emails (created via `IEmailManager`) |
| 14 | +through a Microsoft 365 mailbox, using Azure AD authentication. |
| 15 | + |
| 16 | +Authentication is fully driven by an |
| 17 | +[Azure.Core.TokenCredential](https://learn.microsoft.com/en-us/dotnet/api/azure.core.tokencredential?view=azure-dotnet) |
| 18 | +instance, allowing you to use: |
| 19 | + |
| 20 | +- Managed identity |
| 21 | +- Client credentials (client id/secret or certificate) |
| 22 | +- Interactive login, device code, etc. |
| 23 | + |
| 24 | +## Install |
| 25 | + |
| 26 | +You can install the package from [NuGet](https://www.nuget.org/packages/PosInformatique.Foundations.Emailing.Graph/): |
| 27 | + |
| 28 | +```powershell |
| 29 | +dotnet add package PosInformatique.Foundations.Emailing.Graph |
| 30 | +``` |
| 31 | + |
| 32 | +## Features |
| 33 | + |
| 34 | +- `IEmailProvider` implementation using `Microsoft.Graph.GraphServiceClient`. |
| 35 | +- Simple configuration through `AddEmailing().UseGraph(...)`. |
| 36 | +- Authentication configured via `TokenCredential`: |
| 37 | + - `DefaultAzureCredential` (managed identity, VS, CLI, etc.) |
| 38 | + - `ClientSecretCredential`, `ClientCertificateCredential`, etc. |
| 39 | +- Optional `baseUrl` parameter to customize the Graph endpoint (defaults to `https://graph.microsoft.com/v1.0`). |
| 40 | +- Sends HTML emails using the `EmailMessage` produced by [PosInformatique.Foundations.Emailing](../Emailing/README.md). |
| 41 | + |
| 42 | +## Basic configuration |
| 43 | + |
| 44 | +### Using DefaultAzureCredential (managed identity or local dev) |
| 45 | + |
| 46 | +```csharp |
| 47 | +using Azure.Identity; |
| 48 | +using Microsoft.Extensions.DependencyInjection; |
| 49 | +using PosInformatique.Foundations.EmailAddresses; |
| 50 | +using PosInformatique.Foundations.Emailing; |
| 51 | +using PosInformatique.Foundations.Emailing.Graph; |
| 52 | + |
| 53 | +var services = new ServiceCollection(); |
| 54 | + |
| 55 | +// TokenCredential for Microsoft Graph (for example: managed identity or local dev) |
| 56 | +var credential = new DefaultAzureCredential(); |
| 57 | + |
| 58 | +services |
| 59 | + .AddEmailing(options => |
| 60 | + { |
| 61 | + options.SenderEmailAddress = EmailAddress.Parse("sender@yourtenant.onmicrosoft.com"); |
| 62 | + |
| 63 | + // Register your templates here... |
| 64 | + // options.RegisterTemplate(EmailTemplateIdentifiers.Invitation, invitationTemplate); |
| 65 | + }) |
| 66 | + .UseGraph(credential); |
| 67 | +``` |
| 68 | + |
| 69 | +### Using client credentials (app registration) |
| 70 | + |
| 71 | +If you want to authenticate with a client id / tenant id / client secret: |
| 72 | + |
| 73 | +```csharp |
| 74 | +using Azure.Identity; |
| 75 | +using PosInformatique.Foundations.Emailing.Graph; |
| 76 | + |
| 77 | +var tenantId = configuration["AzureAd:TenantId"]; |
| 78 | +var clientId = configuration["AzureAd:ClientId"]; |
| 79 | +var clientSecret = configuration["AzureAd:ClientSecret"]; |
| 80 | + |
| 81 | +var credential = new ClientSecretCredential(tenantId, clientId, clientSecret); |
| 82 | + |
| 83 | +services |
| 84 | + .AddEmailing(options => |
| 85 | + { |
| 86 | + options.SenderEmailAddress = EmailAddress.Parse("sender@yourtenant.onmicrosoft.com"); |
| 87 | + }) |
| 88 | + .UseGraph(credential); |
| 89 | +``` |
| 90 | + |
| 91 | +The `TokenCredential` you provide is responsible for acquiring tokens for the Microsoft Graph API. The provider does not manage scopes or credentials itself; this is entirely delegated to the credential implementation. |
| 92 | + |
| 93 | +### Custom Graph endpoint |
| 94 | + |
| 95 | +You can optionally customize the Graph base URL (for example, for national clouds): |
| 96 | + |
| 97 | +```csharp |
| 98 | +var baseUrl = "https://graph.microsoft.com/v1.0/beta"; |
| 99 | + |
| 100 | +services |
| 101 | + .AddEmailing(options => |
| 102 | + { |
| 103 | + options.SenderEmailAddress = EmailAddress.Parse("sender@yourtenant.onmicrosoft.com"); |
| 104 | + }) |
| 105 | + .UseGraph(credential, baseUrl); |
| 106 | +``` |
| 107 | + |
| 108 | +If `baseUrl` is `null`, `https://graph.microsoft.com/v1.0` is used by default. |
| 109 | + |
| 110 | +## Typical end-to-end usage |
| 111 | + |
| 112 | +1. Configure emailing (sender address, templates) with `AddEmailing(...)`. |
| 113 | +2. Configure the Graph provider with `UseGraph(TokenCredential, baseUrl?)`. |
| 114 | +3. Inject `IEmailManager` and create emails from template identifiers. |
| 115 | +4. Add recipients and models. |
| 116 | +5. Call `SendAsync(...)` to send emails via Microsoft Graph. |
| 117 | + |
| 118 | +## Links |
| 119 | + |
| 120 | +- [NuGet package: Emailing](https://www.nuget.org/packages/PosInformatique.Foundations.Emailing/) |
| 121 | +s- [Microsoft Graph .NET SDK](https://learn.microsoft.com/graph/sdks/sdks-overview) |
| 122 | +- [Azure Identity (TokenCredential)](https://learn.microsoft.com/dotnet/azure/sdk/authentication/) |
| 123 | +- [Source code](https://github.com/PosInformatique/PosInformatique.Foundations) |
0 commit comments