Schnellstart: Web API-Beispiel (C#)

In diesem Schnellstart erstellen Sie eine einfache Konsolenanwendung, um eine Verbindung mit Ihrer Common Data Service-Umgebung mithilfe der Web-API herzustellen.

Sie authentifizieren sich und verwenden eine HttpClient, um eine GET-Anfrage an die WhoAmI Function zu senden, die Antwort ist eine WhoAmIResponse ComplexType. Sie zeigen den Wert der Eigenschaft UserId an.

Hinweis

Dies ist ein sehr einfaches Beispiel, um zu zeigen, wie man mit einem Minimum an Code verbunden wird. Der folgende Erweiterte Schnellstart baut auf diesem Beispiel auf, um bessere Konstruktionsmuster anzuwenden.

Voraussetzungen

  • Visual Studio (2017 empfohlen)
  • Internetverbindung
  • Gültiges Benutzerkonto für eine Common Data Service-Instanz
    • Ihr Benutzername
    • Ihr Kennwort
  • URL zur Common Data Service-Umgebung, mit der Sie eine Verbindung herstellen möchten
  • Grundlegendes Verständnis der Visual C#-Sprache

Hinweis

Um sich zu authentifizieren, müssen Sie eine App im Azure Active Directory registriert 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 Anwendungen müssen Sie Ihre Apps registrieren. Weitere Informationen: Exemplarische Vorgehensweise: Registrieren einer App bei Azure Active Directory

Erstellen eines Visual Studio-Projekts

  1. Erstellen Sie ein neues Konsolen-App (.NET Framework) Projekt mit .NET Framework 4.6.2.

    Starten eines Konsolen-App-Projekts

    Hinweis

    Dieser Screenshot zeigt den Namen WebAPIQuickStartan, aber Sie können für das Projekt und die Lösung einen beliebigen Namen auswählen.

    Wichtig

    Bekannte Probleme mit Visual Studio 2015

    Wenn Sie Ihr Projekt/Lösung in VS 2015 im Debug-Modus ausführen, können Sie möglicherweise keine Verbindung herstellen. Dies geschieht unabhängig davon, ob Sie ein Zielframework von 4.6.2 oder höher verwenden. Dies kann auftreten, weil der Visual Studio-Hostingprozess gegen .NET 4.5 kompiliert ist, was bedeutet, dass er standardmäßig TLS 1.2 nicht unterstützt. Sie können den Visual Studio-Hostingprozess als Umgehung deaktivieren.

    Klicken Sie mit der rechten Maustaste auf den Namen Ihres Projekts in Visual Studio und dann auf Eigenschaften. Auf der Registerkarte Debuggen können Sie die Option Visual Studio Hostingprozess aktivieren deaktivieren.

    Dies wirkt sich nur auf das Debugging-Umgebung in VS 2015 aus. Es hat keinen Einfluss auf die erstellten Binärdateien bzw. ausführbaren Datei. Das gleiche Problem tritt nicht in Visual Studio 2017 auf.

  2. Klicken Sie in Lösungs-Explorer mit der rechten Maustaste auf das von Ihnen erstellte Projekt und wählen Sie im Kontextmenü NuGet-Pakete verwalten... aus.

    NuGet-Pakete hinzufügen

  3. Navigieren Sie zum Microsoft.IdentityModel.Clients.ActiveDirectory NuGet-Paket.

  4. Wählen Sie Version 2.29.0 und installieren Sie sie.

    Installieren des Microsoft.IdentityModel.Clients.ActiveDirectory NuGet-Pakets

    Wichtig

    Installieren Sie nicht die neueste Version dieses NuGet-Pakets.

    Dieses Beispiel ist von der Fähigkeit zur Übergabe von Benutzeranmeldeinformationen ohne ein separates Azure-Anmeldungsdialogfeld abhängig, das in der Version 3.x dieser Bibliothek nicht verfügbar ist.

    Hinweis

    Sie müssen Ich stimme zu im Dialogfeld Lizenz-Abnahme auswählen.

  5. Navigieren Sie zum Newtonsoft.Json NuGet-Paket und installieren Sie die aktuelle Version.

    Installieren des Microsoft.IdentityModel.Clients.ActiveDirectory NuGet-Pakets

Bearbeiten von Program.cs

  1. Fügen Sie diese Using-Anweisungen am Anfang von Program.cs hinzu

    using Microsoft.IdentityModel.Clients.ActiveDirectory;
    using System.Net.Http.Headers;
    using System.Net.Http;
    using Newtonsoft.Json.Linq;
    
  2. Ersetzen Sie die Main-Methode durch den folgenden Code:

    static void Main(string[] args)
    {
       // Set these values:
        // e.g. https://yourorg.crm.dynamics.com
        string url = "<your environment url>";
        // e.g. you@yourorg.onmicrosoft.com
        string userName = "<your user name>";
        // e.g. y0urp455w0rd
        string password = "<your password>";
    
        // Azure Active Directory registered app clientid for Microsoft samples
        string clientId = "51f81489-12ee-4a9e-aaae-a2591f45987d";
    
        var userCredential = new UserCredential(userName, password);
        string apiVersion = "9.0";
        string webApiUrl = $"{url}/api/data/v{apiVersion}/";
    
        //Authenticate using IdentityModel.Clients.ActiveDirectory
        var authParameters = AuthenticationParameters.CreateFromResourceUrlAsync(new Uri(webApiUrl)).Result;
        var authContext = new AuthenticationContext(authParameters.Authority, false);
        var authResult = authContext.AcquireToken(url, clientId, userCredential);
        var authHeader = new AuthenticationHeaderValue("Bearer", authResult.AccessToken);
    
        using (var client = new HttpClient())
        {
            client.BaseAddress = new Uri(webApiUrl);
            client.DefaultRequestHeaders.Authorization = authHeader;
    
            // Use the WhoAmI function
            var response = client.GetAsync("WhoAmI").Result;
    
            if (response.IsSuccessStatusCode)
            {
                //Get the response content and parse it.  
                JObject body = JObject.Parse(response.Content.ReadAsStringAsync().Result);
                Guid userId = (Guid)body["UserId"];
                Console.WriteLine("Your UserId is {0}", userId);
            }
            else
            {
                Console.WriteLine("The request failed with a status of '{0}'",
                            response.ReasonPhrase);
            }
    
            Console.WriteLine("Press any key to exit.");
            Console.ReadLine();
        }       
    }
    
  3. Bearbeiten Sie die folgenden Werte, um Informationen für die Umgebung hinzuzufügen:

    // e.g. https://yourorg.crm.dynamics.com
    string url = "<your environment url>";
    // e.g. you@yourorg.onmicrosoft.com
    string userName = "<your user name>";
    // e.g. y0urp455w0rd
    string password = "<your password>";
    

    Um den Wert url zu erhalten:

    1. Wählen Sie auf der https://web.powerapps.com-Seite mit der entsprechenden Umgebung Einstellungen Schaltfläche Einstellungen und wählen Sie Erweiterte Anpassungen. Wählen Sie dann Entwicklerressourcen.

    2. Suchen Sie auf der Seite Entwicklerressourcen nach dem Wert der Instanzen-Web-API und kopieren Sie ihn.

      Es sollte in etwa so aussehen wie https://yourorgname.api.crm.dynamics.com/api/data/v9.1/. Aber für dieses Beispiel müssen Sie das letzte Teil (/api/data/v9.1/) so abschneiden, dass es nur https://yourorgname.api.crm.dynamics.com ist.

    Verwenden Sie für die Variablen userName und password die gleichen Anmeldeinformationen, die Sie auch für die Anmeldung bei der Website https://web.powerapps.com verwendet haben.

Ausführen des Programms

  1. Drücken Sie F5, um das Programm auszuführen. Die Ausgabe sollte wie folgt aussehen:

    Your UserId is 969effb0-98ae-478c-b547-53a2968c2e75
    Press any key to exit.
    

Herzlichen Glückwunsch!

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

Das 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 können, aber es stellt kein gutes Muster für den Aufbau einer App dar.

Das Thema Erweiterte Schnellstart zeigt, wie man Methoden zur Behandlung von Ausnahmen implementiert, die Methode der grundlegenden Authentifizierung mit Hilfe von Verbindungszeichenketten, eine wiederverwendbare Methode zur Aktualisierung des Zugriffstokens und führt in die Erstellung von wiederverwendbaren Methoden zur Durchführung von Datenoperationen ein.

Nächste Schritte

Erfahren Sie, wie Sie Ihren Code für ein besseres Design strukturieren können.