Aufrufen von Microsoft Graph mit GraphServiceClient

Beginnend mit Microsoft.Identity.Web 2.12 können Sie die Microsoft.Identity.Web.GraphServiceClient- und Microsoft.Identity.Web.GraphServiceClientBeta-Bibliotheken basierend auf Microsoft Graph SDK 5 verwenden. Die ältere Microsoft. Identity.Web.MicrosoftGraph und Microsoft. Identity.Web.MicrosoftGraphBeta-Pakete (basierend auf Graph SDK 4.x) bleiben verfügbar, sodass Sie in Ihrem eigenen Tempo migrieren können.

Die neuen Bibliotheken bieten eine vereinfachte Fluent-API und die Möglichkeit, sowohl Microsoft Graph als auch Microsoft Graph Beta-APIs in derselben Anwendung zu verwenden.

Migrieren von Microsoft. Identity.Web.MicrosoftGraph 2.x zum Microsoft. Identity.Web.GraphServiceClient erfordert einige Codeänderungen, wie im migrationshandbuch beschrieben.

Einrichten von GraphServiceClient

Führen Sie die folgenden Schritte aus, um Ihrer Anwendung Microsoft Graph Unterstützung hinzuzufügen.

  1. Verweisen Sie auf Microsoft.Identity.Web.GraphServiceClient in Ihrem Projekt.

    dotnet add package Microsoft.Identity.Web.GraphServiceClient

  2. Fügen Sie in der Startmethode der Dienstkollektion Microsoft Graph-Unterstützung hinzu. Standardmäßig sind die Geltungsbereiche auf "User.Read" festgelegt, und die BaseUrl ist "https://graph.microsoft.com/v1.0"". Sie können diese ändern, indem Sie einen Delegat der Methode AddMicrosoftGraph übergeben (siehe unten).

    Verwenden Sie den folgenden Namespace.

    using Microsoft.Identity.Web;

    Fügen Sie der Dienstauflistung Microsoft Graph hinzu.

    services.AddMicrosoftGraph();

    oder, wenn Sie Microsoft Graph Optionen in Ihrer Konfigurationsdatei beschrieben haben:

    "AzureAd":
{
 // more here
},

"DownstreamApis":
{
  "MicrosoftGraph":
     {
         // Specify BaseUrl if you want to use Microsoft graph in a national cloud.
         // See https://learn.microsoft.com/graph/deployments#microsoft-graph-and-graph-explorer-service-root-endpoints
         // "BaseUrl": "https://graph.microsoft.com/v1.0",

         // Set RequestAppToken this to "true" if you want to request an application token (to call graph on 
         // behalf of the application). The scopes will then automatically
         // be ['https://graph.microsoft.com/.default'].
         // "RequestAppToken": false

         // Set Scopes to request (unless you request an app token).
         "Scopes": ["User.Read", "User.ReadBasic.All"]

         // See https://aka.ms/ms-id-web/downstreamApiOptions for all the properties you can set.
     }
}

    Der Code zum Hinzufügen von Microsoft Graph basierend auf der Konfiguration lautet:

    services.AddMicrosoftGraph();
services.Configure<MicrosoftGraphOptions>(options => 
                                          services.Configuration.GetSection("DownstreamApis:MicrosoftGraph"));

    oder

    services.AddMicrosoftGraph(options => 
                           services.Configuration.GetSection("DownstreamApis:MicrosoftGraph").Bind(options) );

  3. Einfügen des GraphServiceClient aus dem Konstruktor von Controllern.

    using Microsoft.Graph;   

public class HomeController : Controller
{
    private readonly GraphServiceClient _graphServiceClient;
    public HomeController(GraphServiceClient graphServiceClient)
    {
        _graphServiceClient = graphServiceClient;
    }
}

  4. Verwenden Sie Microsoft Graph SDK, um Microsoft Graph aufzurufen. So rufen Sie beispielsweise das Profil des aktuellen Benutzers ab:

    var user = await _graphServiceClient.Me.GetAsync();

  5. Sie können die Standardoptionen in den Methoden GetAsync(), PostAsync() und ähnliche Methoden überschreiben.

    Um beispielsweise die E-Mail-Ordner des aktuellen Benutzers abzurufen, müssen Sie weitere Bereiche anfordern ("Mail.Read"). Wenn Ihre App mehrere Authentifizierungsschemas in ASP.NET Core registriert hat, müssen Sie auch angeben, welches Authentifizierungsschema angewendet werden soll.

     var mailFolders = await _graphServiceClient.Me.MailFolders.GetAsync(r =>
 {
     r.Options.WithScopes("Mail.Read")
              .WithAuthenticationScheme(JwtBearerDefaults.AuthenticationScheme);
 });

    Sie können auch denselben Code wie folgt schreiben. Dieser Ansatz ist ausführlicher, ermöglicht ihnen jedoch das Gleichzeitige Festlegen mehrerer Optionen:

     var mailFolders = await _graphServiceClient.Me.MailFolders.GetAsync(r =>
 {
     r.Options.WithAuthenticationOptions(o =>
     {
         // Specify scopes for the request
         o.Scopes = new string[] { "Mail.Read" };

         // Specify the ASP.NET Core authentication scheme if needed (in the case
         // of multiple authentication schemes)
         o.AcquireTokenOptions.AuthenticationOptionsName = JwtBearerDefaults.AuthenticationScheme;
     });
 });

    Wenn Ihre App die Graph-API im Namen von sich selbst aufruft, müssen Sie ein Anwendungstoken anfordern. Legen Sie WithAppOnly fest, um ein App-Token anzufordern. Der folgende Code ruft beispielsweise die Anzahl der Anwendungen im Mandanten ab:

    int? appsInTenant = await _graphServiceClient.Applications.Count.GetAsync(
                                                                 r => r.Options.WithAppOnly() );

    Der vorherige Code ist eine Kurzversion für die folgende ausführlichere Version:

    int? appsInTenant = await _graphServiceClient.Applications.Count.GetAsync(r =>
{
 r.Options.WithAuthenticationOptions(o =>
 {
     // Applications require app permissions, hence an app token
     o.RequestAppToken = true;
 });
});

Verwenden von Microsoft Graph und Microsoft Graph Beta

Sie können sowohl Microsoft Graph als auch Microsoft Graph Beta in derselben Anwendung verwenden, indem Sie auf beide Pakete verweisen.

  1. Verweisen Sie auf beide Microsoft. Identity.Web.GraphServiceClient und Microsoft. Identity.Web.GraphServiceClientBeta in Ihrem Projekt

    dotnet add package Microsoft.Identity.Web.GraphServiceClient
dotnet add package Microsoft.Identity.Web.GraphServiceClientBeta

  2. Fügen Sie in der Startmethode der Dienstauflistung Microsoft Graph und Graph Beta hinzu:

    services.AddMicrosoftGraph();
services.AddMicrosoftGraphBeta();

  3. Deklarieren Sie im Controller oder überall dort, wo Sie sie verwenden möchten, sowohl GraphServiceClient als auch GraphServiceClientBeta, und fügen Sie sie in den Konstruktor ein:

    using GraphServiceClient = Microsoft.Graph.GraphServiceClient;
using GraphBetaServiceClient = Microsoft.Graph.GraphBetaServiceClient;

    MyController(GraphServiceClient graphServiceClient, GraphBetaServiceClient graphServiceClient)
{
 // more here
}

Migrieren sie von Microsoft. Identity.Web.MicrosoftGraph 2.x zum Microsoft. Identity.Web.GraphServiceClient

Microsoft.Identity.Web.GraphServiceClient basiert auf Microsoft.GraphSDK 5.x, die einschneidende Änderungen einführt. Die Request()-Methode ist verschwunden, und die damit in Microsoft.Identity.Web.MicrosoftGraph aktivierten Erweiterungsmethoden wurden jetzt auf die Methoden GetAsync(), GetPost() usw. verschoben.

Der Microsoft Graph 4.x-Code:

var user = await _graphServiceClient.Me.Request().GetAsync();

wird mit Microsoft Graph 5.x:

var user = await _graphServiceClient.Me.GetAsync();

Die folgenden Absätze helfen Ihnen bei der Migration von Microsoft. Identity.Web.MicrosoftGraph zum Microsoft. Identity.Web.GraphServiceClient.

Ersetzen der NuGet-Pakete

Entfernen Sie das alte Paket, und fügen Sie das neue Paket hinzu.

  1. Verweisen Sie auf Microsoft.Identity.Web.GraphServiceClient in Ihrem Projekt. 
    dotnet remove package Microsoft.Identity.Web.MicrosoftGraph
dotnet add package Microsoft.Identity.Web.GraphServiceClient

Aktualisieren des Codes

Zusätzlich zu den Änderungen aufgrund der Migration von Microsoft. Graph 4.x bis Microsoft. Graph 5.x müssen Sie die Position der Modifizierer .WithScopes(), .WithAppOnly(), WithAuthenticationScheme() und .WithAuthenticationOptions() ändern.

Aktualisierung von WithScopes()-Aufrufen

In Microsoft. Identity.Web.MicrosoftGraph haben Sie .WithScopes() für die Anforderung verwendet, um Bereiche für die Authentifizierung für Microsoft Graph anzugeben:

var messages = await _graphServiceClient.Users
                .Request()
                .WithScopes("User.Read.All")
                .GetAsync();
int NumberOfUsers = messages.Count;

Mit Microsoft.Identity.Web.GraphServiceClient rufen Sie stattdessen .WithScopes() für die Optionen des Builders auf.

var messages = await _graphServiceClient.Users
                .GetAsync(b => b.Options.WithScopes("User.Read.All"));
int NumberOfUsers = messages.Value.Count;

Aktualisieren von WithAppOnly()-Aufrufen

In Microsoft. Identity.Web.MicrosoftGraph 2.x haben Sie App-Berechtigungen angegeben (die ein Nur-App-Token erfordern), indem Sie .WithAppOnly() aufrufen.

var messages = await _graphServiceClient.Users
                .Request()
                .WithAppOnly()
                .GetAsync();
int NumberOfUsers = messages.Count;

Mit Microsoft.Identity.Web.GraphServiceClient, rufen Sie stattdessen .WithAppOnly() für die Optionen des Builders auf.

var messages = await _graphServiceClient.Users
                .GetAsync(b => b.Options.WithAppOnly() ));
int NumberOfUsers = messages.Value.Count;

Dieser Ansatz verwendet die Bereiche ["https://graph.microsoft.com/.default"] unter der Haube, was bedeutet, dass alle vorautorisierte Bereiche. Sie müssen diese Bereiche nicht angeben, da dies die einzige Option ist, wenn Sie eine Microsoft-Graph-API aufrufen, die App-Berechtigungen erfordert.

Aktualisieren von WithAuthenticationScheme()-Aufrufen

Wenn Sie Microsoft verwenden. Identity.Web.MicrosoftGraph in einer ASP.NET Core Anwendung können Sie das Authentifizierungsschema angeben, indem Sie WithAuthenticationScheme() aufrufen.

var messages = await _graphServiceClient.Users
                .Request()
                .WithAuthenticationScheme(JwtBearerDefaults.AuthenticationScheme)
                .GetAsync();
int NumberOfUsers = messages.Count;

Mit Microsoft. Identity.Web.GraphServiceClient, übergeben Sie das Authentifizierungsschema über die Generatoroptionen:

var messages = await _graphServiceClient.Users
                .GetAsync(b => b.Options.WithAuthenticationScheme(JwtBearerDefaults.AuthenticationScheme) ));
int NumberOfUsers = messages.Value.Count;

Weitere Informationen zur Migration von Microsoft Graph SDK 4.x zu 5.x finden Sie in Microsoft Graph .NET SDK v5 Changelog and upgrade guide

Konfigurieren anderer Authentifizierungsoptionen

Sie können für die Generatoroptionen verwenden .WithAuthenticationOptions() , um zusätzliche Authentifizierungsparameter festzulegen.

  • Last updated on