Freigeben über

Schnellstart: Web-API-Beispiel (C#)

In diesem Schnellstart erstellen Sie eine Konsolenanwendung, die eine Verbindung mit Ihrer Microsoft Dataverse-Umgebung herstellt und eine einfache Funktion aufruft. 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 dann den UserId-Eigenschaftswert an, der aus der Antwort stammt.

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

Anforderungen

  • 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

Anmerkung

Zum Authentifizieren müssen Sie eine in Microsoft Entra ID registrierte App haben. Dieses Schnellstartbeispiel bietet einen Wert für die App-Registrierung clientid, die Sie verwenden, 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

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

    Neues Projekt erstellen

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

    Neues Konsolen-App-Projekt

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

    Projekt konfigurieren

  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.

    Dialog „Zusätzliche Informationen“

  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) NuGet-Paket mit dem Namen Microsoft.Identity.Client, wählen Sie es aus, und wählen Sie dann Installieren aus.

    MSAL-Authentifizierungspaket installieren

    Anmerkung

    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 unterhalb des TODO-Kommentars 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";

Ausführen des Programms

  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.

    Nachdem Sie das Konto ausgewählt haben, geben Sie Ihr Kennwort ein, und wählen Sie " Anmelden" aus.

  2. Sehen Sie sich das Anwendungsfenster der Konsole an. Die Ausgabe sollte in etwa so 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.

Internet 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#)

  • Last updated on