Schnellstart: Dataverse-Web-API-Beispiel (C#)

In dieser Schnellstartanleitung erstellen Sie eine C#-Konsolenanwendung, die eine Verbindung mit Ihrer Microsoft Dataverse Umgebung herstellt und die Dataverse-Web-API verwendet, um eine einfache Funktion aufzurufen. Sobald Sie die hier beschriebenen grundlegenden Funktionen verstanden haben, können Sie andere Web-API-Vorgänge untersuchen, z. B. Erstellen, Abrufen, Aktualisieren und Löschen von Dataverse-Tabellenzeilen.

Dieses Programm authentifiziert sich und verwendet einen HttpClient, um eine GET-Anforderung an die WhoAmI-Funktion zu senden. Diese Funktion ruft Informationen zum angemeldeten Dataverse-Benutzer ab. Die Antwort ist ein WhoAmIResponse ComplexType. Das Programm zeigt den aus der Antwort abgerufenen Eigenschaftswert UserId an.

Sie finden die vollständige Visual Studio-Projektmappe für dieses .NET 10-Projekt im PowerApps-Samples-Repository unter dataverse/webapi/C#-NETx/QuickStart.

Voraussetzungen

  • Visual Studio 2026 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. In diesem Schnellstartbeispiel wird ein App-Registrierungswert clientid bereitgestellt, den Sie zum Ausführen von Beispielcode verwenden können, der von Microsoft veröffentlicht wird. Für Ihre eigenen benutzerdefinierten Anwendungen müssen Sie Ihre Apps jedoch bei AD registrieren. Weitere Informationen finden Sie unter Exemplarische Vorgehensweise: Registrieren einer App mit Microsoft Entra ID.

Visual Studio-Projekt erstellen

  1. Starten Sie Visual Studio 2026, und wählen Sie "Neues Projekt erstellen" aus.

    Screenshot des Visual Studio Startfensters mit der Option

  2. Erstellen Sie ein neues Konsolen-App-Projekt.

    Screenshot der Auswahl der Konsolen-App-Projektvorlage in Visual Studio.

  3. Konfigurieren Sie das Projekt, indem Sie einen Speicherort und einen Projektnamen festlegen.

    Screenshot des Festlegens des Projektspeicherorts und des Namens für die .NET 10-Konsolen-App.

  4. Konfigurieren Sie das Projekt, indem Sie .NET 10.0 (Long Term Support) auswählen und keine Anweisungen der obersten Ebene verwenden. Wählen Sie dann Erstellen aus.

    Screenshot des Dialogfelds

  5. 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.

  6. Suchen Sie nach dem Microsoft Authentication Library (MSAL) (MSAL) NuGet-Paket mit dem Namen Microsoft.Identity.Client, wählen Sie es aus, und wählen Sie dann Installieren aus.

    Screenshot der Installation des Microsoft. Identity.Client MSAL NuGet-Paket in Visual Studio.

    Hinweis

    Sie werden aufgefordert, die Lizenzbedingungen vor der Installation zu akzeptieren. Wählen Sie Ich stimme zu im Dialogfeld Lizenz annehmen aus.

Bearbeiten von Program.cs

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

  1. 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; }
   }
}

  2. Ersetzen Sie direkt nach dem // TODO Specify the Dataverse environment name to connect with. Kommentar im vorherigen 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. Wechseln Sie zu Power Apps.
    2. Wählen Sie das Umgebungssymbol (rechts neben dem Suchfeld) und dann eine Testumgebung aus.
    3. Wählen Sie das Einstellungssymbol Schaltfläche „Einstellungen“. und dann Entwicklerressourcen.
    4. Kopieren Sie die Url des Web-API-Endpunkts von https: bis .com durch, ohne die nachfolgende /api/data/v9.2.
    5. Ersetzen Sie den Wert der Ressourcen-Zeichenfolge im Programmcode durch die Endpunkt-URL. Beispiel:

      string resource = "https://contoso.api.crm.dynamics.com";

Programm ausführen

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

    Es öffnet sich ein Browserfenster, in dem Sie aufgefordert werden, 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, wählen Sie Anderes Konto verwenden aus.

    Wenn Sie das Konto auswählen, geben Sie Ihr Kennwort ein, und wählen Sie "Anmelden" aus.

  2. Sehen Sie sich das Anwendungsfenster der Konsole an. Die Ausgabe sollte ungefähr wie folgt aussehen:

    Your user ID is 22cc22cc-dd33-ee44-ff55-66aa66aa66aa

C:\projects\webapi-quickstart\bin\Debug\net10.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 eine Verbindung mit der Web-API hergestellt.

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

.NET-Beispielcode

Ein vollständiges Beispiel, das empfohlene Entwurfsmuster veranschaulicht, finden Sie in der WebAPIService-Klassenbibliothek (C#). 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 mithilfe von 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. The [Web API Data operations Samples (C#)](web-api-samples-csharp.md) use theWebAPIService'-Klassenbibliothek.

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.

Web-API-Typen und -Vorgänge

Erfahren Sie mehr über dataverse Web-API-Funktionen, indem Sie Beispielcode ausführen und untersuchen.

Beispiele für Web-API-Datenvorgänge (C#)

  • Zuletzt aktualisiert um