Schnellstart: Web API-Beispiel (C#)

Artikel
11/16/2023

In diesem Schnellstart erstellen Sie eine einfache Konsolenanwendung, um sich mit Ihrer Microsoft Dataverse-Zielumgebung zu verbinden und die WhoAmI-Funktion der Web-API aufzurufen. Diese Funktion ruft Informationen über den eingeloggten Dataverse-Benutzer ab. Sobald Sie die hier beschriebenen grundlegenden Funktionen verstanden haben, können Sie zu anderen Web-API-Vorgängen wie dem Erstellen, Abrufen, Aktualisieren und Löschen von Dataverse-Tabellenzeilen übergehen.

Dieses Programm authentifiziert und verwendet einen HttpClient, um eine GET-Anforderung an die WhoAmI-Funktion zu senden. Die Antwort ist ein WhoAmIResponse ComplexType. Das Programm zeigt dann den UserId-Eigenschaftswert an, der aus der Antwort stammt.

Hinweis

Dies ist ein sehr einfaches Beispiel, um zu zeigen, wie man mit einem Minimum an Code verbunden wird.

Sie finden die komplette Visual Studio-Lösung für dieses .NET-6-Projekt im PowerApps-Beispiel-Repository unter dataverse/webapi/C#-NETx/QuickStart. Es gibt auch eine .NET Framework-Version des Beispiels unter dataverse/webapi/C#/QuickStart.

Anforderungen

Visual Studio 2022 oder höher
Internetverbindung
Gültiges Benutzerkonto für eine Dataverse-Umgebung
URL zur Dataverse-Umgebung, mit der Sie eine Verbindung herstellen möchten
Grundlegendes Verständnis der C#-Sprache

Hinweis

Zum Authentifizieren müssen Sie eine in Microsoft Entra ID registrierte App haben. Dieses Schnellstartbeispiel bietet einen Wert für die App-Registrierung clientid, den Sie verwenden können, um von Microsoft veröffentlichten Beispielcode auszuführen. Für Ihre eigenen benutzerdefinierten Anwendungen müssen Sie Ihre Apps jedoch bei AD registrieren. Weitere Informationen: Exemplarische Vorgehensweise: Registrieren einer App mit Microsoft Entra ID

Visual Studio-Projekt erstellen

Starten Sie Visual Studio 2022 und wählen Sie Neues Projekt erstellen aus.
Erstellen Sie ein neues Konsolen-App-Projekt.
Konfigurieren Sie das Projekt, indem Sie einen Speicherort und einen Projektnamen festlegen.
Konfigurieren Sie das Projekt, indem Sie .NET 6.0 (langfristiger Support) und Keine Anweisungen der obersten Ebene verwenden auswählen. Gehen Sie dann auf Erstellen.
Klicken Sie im Lösungs-Explorer mit der rechten Maustaste auf das von Ihnen erstellte Projekt und wählen Sie im Kontextmenü NuGet-Pakete verwalten... aus. Mit NuGet können Sie erforderliche Assemblys in Ihr Projekt zu integrieren.
Suchen Sie nach dem Microsoft Authentication Library (MSAL) NuGet-Paket mit dem Namen Microsoft.Identity.Client, wählen Sie es aus, und wählen Sie dann Installieren aus.

Hinweis

Sie werden vor der Installation aufgefordert, die Lizenzbedingungen zu akzeptieren. Gehen Sie auf Ich akzeptiere im Dialog Lizenz annehmen.

Bearbeiten von Program.cs

Befolgen Sie diese nächsten Schritte, um Code für das Hauptprogramm hinzuzufügen.

Ersetzen Sie die gesamten Inhalte von Program.cs durch den folgenden Code.

using Microsoft.Identity.Client;  // Microsoft Authentication Library (MSAL)
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text.Json;
using System.Threading.Tasks;

namespace PowerApps.Samples
{
   /// <summary>
   /// Demonstrates Azure authentication and execution of a Dataverse Web API function.
   /// </summary>
   class Program
   {
      static async Task Main()
      {
            // TODO Specify the Dataverse environment name to connect with.
            // See https://learn.microsoft.com/power-apps/developer/data-platform/webapi/compose-http-requests-handle-errors#web-api-url-and-versions
            string resource = "https://<env-name>.api.<region>.dynamics.com";

            // Microsoft Entra ID app registration shared by all Power App samples.
            var clientId = "51f81489-12ee-4a9e-aaae-a2591f45987d";
            var redirectUri = "http://localhost"; // Loopback for the interactive login.

            // For your custom apps, you will need to register them with Microsoft Entra ID yourself.
            // See https://docs.microsoft.com/powerapps/developer/data-platform/walkthrough-register-app-azure-active-directory

            #region Authentication

            var authBuilder = PublicClientApplicationBuilder.Create(clientId)
                           .WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
                           .WithRedirectUri(redirectUri)
                           .Build();
            var scope = resource + "/user_impersonation";
            string[] scopes = { scope };

            AuthenticationResult token =
               await authBuilder.AcquireTokenInteractive(scopes).ExecuteAsync();
            #endregion Authentication

            #region Client configuration

            var client = new HttpClient
            {
               // See https://docs.microsoft.com/powerapps/developer/data-platform/webapi/compose-http-requests-handle-errors#web-api-url-and-versions
               BaseAddress = new Uri(resource + "/api/data/v9.2/"),
               Timeout = new TimeSpan(0, 2, 0)    // Standard two minute timeout on web service calls.
            };

            // Default headers for each Web API call.
            // See https://docs.microsoft.com/powerapps/developer/data-platform/webapi/compose-http-requests-handle-errors#http-headers
            HttpRequestHeaders headers = client.DefaultRequestHeaders;
            headers.Authorization = new AuthenticationHeaderValue("Bearer", token.AccessToken);
            headers.Add("OData-MaxVersion", "4.0");
            headers.Add("OData-Version", "4.0");
            headers.Accept.Add(
               new MediaTypeWithQualityHeaderValue("application/json"));
            #endregion Client configuration

            #region Web API call

            // Invoke the Web API 'WhoAmI' unbound function.
            // See https://docs.microsoft.com/powerapps/developer/data-platform/webapi/compose-http-requests-handle-errors
            // See https://docs.microsoft.com/powerapps/developer/data-platform/webapi/use-web-api-functions#unbound-functions
            var response = await client.GetAsync("WhoAmI");

            if (response.IsSuccessStatusCode)
            {
               // Parse the JSON formatted service response (WhoAmIResponse) to obtain the user ID value.
               // See https://learn.microsoft.com/power-apps/developer/data-platform/webapi/reference/whoamiresponse
               Guid userId = new();

               string jsonContent = await response.Content.ReadAsStringAsync();

               // Using System.Text.Json
               using (JsonDocument doc = JsonDocument.Parse(jsonContent))
               {
                  JsonElement root = doc.RootElement;
                  JsonElement userIdElement = root.GetProperty("UserId");
                  userId = userIdElement.GetGuid();
               }

               // Alternate code, but requires that the WhoAmIResponse class be defined (see below).
               // WhoAmIResponse whoAmIresponse = JsonSerializer.Deserialize<WhoAmIResponse>(jsonContent);
               // userId = whoAmIresponse.UserId;

               Console.WriteLine($"Your user ID is {userId}");
            }
            else
            {
               Console.WriteLine("Web API call failed");
               Console.WriteLine("Reason: " + response.ReasonPhrase);
            }
            #endregion Web API call
      }
   }

   /// <summary>
   /// WhoAmIResponse class definition 
   /// </summary>
   /// <remarks>To be used for JSON deserialization.</remarks>
   /// <see cref="https://learn.microsoft.com/power-apps/developer/data-platform/webapi/reference/whoamiresponse"/>
   public class WhoAmIResponse
   {
      public Guid BusinessUnitId { get; set; }
      public Guid UserId { get; set; }
      public Guid OrganizationId { get; set; }
   }
}

Ersetzen Sie direkt unter dem TODO-Kommentar im obigen Code den resource-Variablenwert durch die tatsächliche URL Ihrer Dataverse-Testumgebung. Gehen Sie folgendermaßen vor, um den URL-Wert für Ihre Testumgebung zu ermitteln:
1. Navigieren Sie in Ihrem Browser zu Power Apps.
2. Wählen Sie das Umgebungssymbol (rechts neben dem Suchfeld) und dann eine Testumgebung aus.
3. Wählen Sie das Einstellungssymbol und wählen Sie Entwicklerressourcen aus.
4. Kopieren Sie die Web-API-Endpunkt-URL von „https:“ bis „.com“ und lassen Sie das nachstehende /api/data/v9.2 weg.
5. Ersetzen Sie den Wert der Ressourcenzeichenfolge im Programmcode durch den Endpunkt-URL-Wert. Zum Beispiel:
  string resource = "https://contoso.api.crm.dynamics.com";

Ausführen des Programms

Drücken Sie F5, um das Programm zu erstellen und auszuführen.

Ein Browserfenster wird geöffnet und Sie werden aufgefordert, ein Konto auszuwählen. Wählen Sie das Konto aus, das Sie für den Zugriff auf Ihre Dataverse-Umgebung verwenden. Wenn dieses Konto nicht in der Liste angezeigt wird, gehen Sie auf Anderes Konto verwenden.

Sobald Sie das Konto ausgewählt haben, geben Sie Ihr Passwort ein und gehen Sie auf Anmelden.

Sehen Sie sich das Anwendungsfenster der Konsole an. Die Ausgabe sollte in etwa so aussehen:

Your user ID is 4026be43-6b69-e111-8f65-78e7d1620f5e

C:\Projects\webapi-quickstart\bin\Debug\net6.0\webapi-quickstart.exe (process 21524) exited with code 0.
To automatically close the console when debugging stops, enable Tools->Options->Debugging->Automatically close the console when debugging stops.
Press any key to close this window . . .

Herzlichen Glückwunsch!

Sie haben erfolgreich eine Verbindung mit der Web-API hergestellt.

Dieses Schnellstart-Beispiel zeigt einen einfachen Ansatz zum Erstellen eines Visual Studio-Projekts ohne Ausnahme oder eine Methode zum Aktualisieren des Zugriffstokens. Dies reicht aus, um zu überprüfen, ob Sie eine Verbindung herstellen und verschiedene Vorgänge ausprobieren können.

Ein ausführlicheres Beispiel, das empfohlene Entwurfsmuster demonstriert, finden Sie in der WebAPIService-Klassenbibliothek (C#). Dies ist das Projekt, das wir für unsere Beispiele für Web-API-Datenvorgänge (C#) verwenden. Es veranschaulicht:

Verwalten von Dataverse-Serviceschutz API-Grenzwerten mit der .NET-Bibliothek für Resilienz und Behandlung von vorübergehenden Fehlern Polly.
Verwalten eines HttpClient in .NET mit IHttpClientFactory.
Verwenden von Konfigurationsdaten zum Verwalten des Verhaltens des Clients.
Verwalten von Fehlern, die von der Dataverse Web-API zurückgegeben werden.
Ein Muster der Wiederverwendung von Code durch:
- Erstellen von Klassen, die von HttpRequestMessage und HttpResponseMessage erben.
- Methoden, die diese Klassen verwenden.
- Ein modulares Muster zum Hinzufügen neuer Funktionen nach Bedarf.

Nächste Schritte,

Versuchen Sie, eine Webanwendung zu erstellen.

Schnellstart: Blazor Server-Web-API-Beispiel (C #)

Erfahren Sie mehr über Dataverse-Web-API-Funktionen durch Verständnis der Servicedokumente.

Internet API-Typen und -Vorgänge

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).

Schnellstart: Web API-Beispiel (C#)

Anforderungen

Visual Studio-Projekt erstellen

Bearbeiten von Program.cs

Ausführen des Programms

Herzlichen Glückwunsch!

Nächste Schritte,

Feedback

Zusätzliche Ressourcen