Starten eines Dynamics 365-Web-API-Projekts in Visual Studio (C#)

Artikel
04/18/2017

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Dieses Thema zeigt, wie Sie ein neues Projekt in Microsoft Visual Studio erstellt, das eine Konsolenanwendung erstellt, die die Dynamics 365-Web-API verwendet. Es zeigt die allgemeinen Verweise werden Projektressourcen, die die meisten Anwendungen, einschließlich den SDK-C#-Beispielen, verwenden, um Web-API-basierte Lösungen zu implementieren.

Voraussetzungen

Die folgenden Voraussetzungen sind zur Erstellung der Konsolenanwendung in diesem Abschnitt erforderlich.

Microsoft Visual Studio 2015, das auf dem Entwicklungscomputer installiert ist. Jede Edition, inkl. Visual Studio Express, sollten ausreichend sein, um mit der Microsoft Dynamics 365-Web-API zu arbeiten. Weitere Informationen zu den unterstützten Versionen von Microsoft Visual Studio finden Sie unter Visual Studio und .NET Framework.
Ein NuGet-Client muss installiert sein. Entweder mit dem Befehlszeilenprogramm oder der Visual Studio-Erweiterung. Weitere Informationen finden Sie unter Installieren von NuGet.
Eine Internetverbindung ist erforderlich, damit das NuGet-Paket, die Dynamics 365-Web-API Hilfebibliothek und weitere abhängige Pakete heruntergeladen werden können.
Optional können Sie das Microsoft Dynamics 365 SDKhier herunterladen. Obwohl das Microsoft Dynamics 365 SDK nicht zum Erstellen oder Ausführen dieser Web-API-Beispiele erforderlich ist, werden die meisten Dynamics 365-Entwickler es installieren, da es umfangreiche ergänzende Ressourcen enthält, und das SDK für den Zugriff auf andere Dynamics 365-Schnittstellen erforderlich ist.

Erstellen eines Projekts

Im folgenden Verfahren wird veranschaulicht, wie ein Konsolenanwendungsprojekt in der Sprache C# erstellt wird, das Microsoft .NET Framework nutzt. Weitere Information zu den unterstützten Versionen von .NET Framework finden Sie unter Unterstützte Erweiterungen für Microsoft Dynamics 365.

Neues Projekt

Klicken Sie in Microsoft Visual Studio auf Neues Projekt. Das Dialogfeld Neues Projekt wird angezeigt.
Wählen Sie im linken Navigationsbereich unter Vorlagen die Option Visual C# aus.
Über der Liste verfügbarer Vorlagen, wählen Sie .NET Framework 4.5.2.
Wählen Sie in der Vorlagenliste die Option Konsolenanwendung aus. (Wählen Sie alternativ den Projekttyp aus, der für Ihrer Lösung geeignet ist). Alle der Web-API-Beispiele sind Konsolenanwendungen.
Geben Sie für das Projekt in den Feldern in der Nähe des unteren Bereichs des Formulars einen Speicherort und einen Namen an, und wählen Sie dann OK aus. (In diesem Thema wurde der Lösungsname "StartWebAPI-CS" verwendet.) Die Ausgangslösungsdateien werden generiert und die Lösung wird in Microsoft Visual Studio geladen.
Öffnen Sie im Menü Projekt das Eigenschaftenformular des Projekts und überprüfen Sie, ob das Zielframework auf .NET Framework 4.5.2 festgelegt ist.

Fügen Sie dem Projekt alle benötigten Ressourcen hinzu

Die folgenden Schritte zeigen Ihnen, wie dem Projekt alle erforderlichen verwalteten Verweise und Pakete hinzugefügt werden. Betrachten Sie das als einen Basissatz von Ressourcen, der von den meisten Code-Anwendungen mit verwaltetem Code zum Aufrufen von Web-API-Vorgängen benötigt wird.

Hinzufügen des Hilfebibliothek-NuGet-Pakets

Die Dynamics 365-SDK Web-API-Hilfebibliothek enthält Klassen, zur Unterstützung über ergänzende Vorgänge, wie z. b. der Anwendungskonfigurations-, Dynamics 365-Serverauthentifizierung, Ausnahmebehandlung und die Web-Kommunikation. Weitere Informationen finden Sie unter Verwenden Sie die Microsoft Dynamics 365 WEB API Hilfe-Bibliothek (C#). Die Verwendung dieser Klassen ist optional, obwohl sie in den Web-API-Beispielen extensiv verwendet werden. Die Dynamics 365-SDK Web-APi-Hilfebibliothek wird in Quellcodeform als NuGet-Paket verteilt. Zukünftige Updates werden als NuGet-Paketupdates verteilt.

Wenn Sie das NuGet-Befehlszeilenprogramm installiert haben oder die Paket-Manager-Konsole in Visual Studio verwenden:

Nutzen Sie den folgenden Befehl, um das Hilfebibliothekspaket zu installieren.

Install-Package Microsoft.CrmSdk.WebApi.Samples.HelperCode
Es werden einige Meldungen zur Verarbeitung von Abhängigkeitspaketen angezeigt. Wenn ein Lizenz-Abnahme-Dialogfeld angezeigt wird, lesen Sie die Lizenzbedingungen, und klicken Sie auf Akzeptieren.
Springen Sie zu Schritt 6 unten, um die Installation des Hilfebibliothekspakets zu bestätigen.

Wenn Sie die NuGet-Paket-Manager-Erweiterung installiert haben:

Im Menü Projekt wählen Sie die Option NuGet-Pakete verwalten aus. Die Registerkarte NuGet-Paket-Manager wird angezeigt.
Klicken Sie in der oberen rechten Ecke legen Sie das Feld Paket auf Nuget.org fest.
Klicken Sie in der oberen linken Ecke klicken Sie auf Durchsuchen, geben Sie dann "Dynamics 365 HelperCode" im Feld "Suche" ein und drücken Sie die EINGABETASTE.
Klicken Sie auf Installieren. Wenn das Dialogfeld Vorschau angezeigt wird, klicken Sie auf OK.
Das Dialogfeld Lizenz-Abnahme wird angezeigt. Lesen und akzeptieren Sie die Lizenzbedingungen, und klicken Sie auf Ich akzeptiere.
Navigieren Sie zum Fenster Lösungs-Explorer. Stellen Sie sicher, dass ein neuer Lösungsordner namens Web API Helper Code hinzugefügt wurde.

Das Dynamics 365 SDK Web API Helper Library-Paket, Microsoft.CrmSdk.WebApi.Samples.HelperCode, hängt von den folgenden weiteren Paketen ab (werden automatisch heruntergeladen und installiert):

Newtonsoft.Json – enthält Json.NET, ein beliebtes JSON-Framework für .NET mit MIT-Lizenz.
Microsoft.IdentityModel.Clients.ActiveDirectory – enthält die Binärdateien für Active Directory Authentication Library (ADAL) für Authentifizierungsfunktion für .NET-Clients.

Warnung

Das Dynamics 365 SDK Web API Helper Library-Paket wurde für bestimmte Versionen dieser beiden unterstützenden Pakete erstellt. Aus diesem Grund sollten Sie nur das Hilfebibliothek.NuGet-Paket direkt aktualisieren. Dieser Vorgang aktualisiert nach Bedarf die richtigen unterstützenden Pakete. Wenn Sie eines dieser unterstützenden Pakete separat aktualisieren, ist unter Umständen eine aktuellere Version dieses Pakets mit der Hilfebibliothek nicht kompatibel.

Prüfen der erforderlichen Assembly-Verweise

Erweitern Sie im Lösungs-Explorer den Knoten Referenzen.
Bestätigen Sie, das die folgenden Verweise zum Projekt hinzugefügt wurden.
Wenn Sie zusätzliche Funktionalitäten nutzen, die Sie routinemäßig in den Anwendungen verwenden, können Sie die zugeordneten Verweise auf die erforderlichen Assemblys jetzt hinzufügen. Weitere Informationen finden Sie unter Anleitung: Hinzufügen oder Entfernen von Verweisen über das 'Verweise Hinzufügen-Dialogfeld'.

Da die Dynamics 365-Web-API auf REST-Prinzipien basiert, benötigt sie keine clientseitigen Assemblys für den Zugriff. Allerdings benötigen diese andere von Microsoft Dynamics 365 unterstützte APIs. Weitere Informationen finden Sie unter Im Microsoft Dynamics 365-SDK enthaltene Assemblies.

Hinzufügen typische Using-Anweisungen

Öffnen Sie im Lösungs-Explorer die Datei Program.cs zum Bearbeiten.
Fügen Sie oben in der Datei können die folgenden using-Anweisungen hinzu. Diese Namespaces werden im Allgemeinen in Dynamics 365-Web-API-basierten Lösungen verwendet.
```
using Microsoft.Crm.Sdk.Samples.HelperCode;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
```
Wenn Sie routinemäßig verwendete Assemblys oder Verweise in den vorherigen Abschnitten hinzugefügt haben, sollten Sie die Entsprechenden using-Anweisungen für diese Ressourcen hinzufügen.
Speichern Sie die Datei.

Verbindungscode hinzufügen

In diesem Abschnitt wird beschrieben, wie eine grundlegende Einstellungen und Anweisungen für diese Vorgänge hinzufügen. Weitere Informationen zur häufig verwendetem Code finden Sie unter Verwenden Sie die Microsoft Dynamics 365 WEB API Hilfe-Bibliothek (C#).

Bearbeiten der Anwendungskonfigurationsdatei

Öffnen Sie im Lösungs-Explorer die Datei App.config zum Bearbeiten. Fügen Sie die folgenden zwei Abschnitte nach dem vorhandenen <startup>-Abschnitt hinzu, und speichern Sie die Datei.

<connectionStrings>
    <clear />

    <!-- When providing a password, make sure to set the app.config file's security so that only you can read it. -->
    <add name="default"   connectionString="Url=http://myserver/myorg/; Username=name; Password=password; Domain=domain" />
    <add name="CrmOnline" connectionString="Url=https://mydomain.crm.dynamics.com/; Username=someone@mydomain.onmicrosoft.com; Password=password" />
  </connectionStrings>

  <appSettings>
    <!--For information on how to register an app and obtain the ClientId and RedirectUrl
        values see https://msdn.microsoft.com/dynamics/crm/mt149065 -->
    <!--Active Directory application registration. -->
    <!--These are dummy values and should be replaced with your actual app registration values.-->
    <add key="ClientId" value="e5cf0024-a66a-4f16-85ce-99ba97a24bb2" />
    <add key="RedirectUrl" value="https://localhost/SdkSample" />

    <!-- Use an alternate configuration file for connection string and setting values. This optional setting
    enables use of an app.config file shared among multiple applications. If the specified file does
    not exist, this setting is ignored.-->
    <add key="AlternateConfig" value="C:\Temp\crmsample.exe.config"/>
  </appSettings>

Wenn Sie eine Lösung entwickeln oder bereitstellen, müssen die tatsächlichen und Anwendungsregistrierungswerte statt der Beispielsplatzhalterwerte verwendet werden. Weitere Informationen finden Sie unter Web API-Hilfecode: Konfigurationsklassen.

Hinzufügen von Code zum Aufrufen der Hilfebibliothek

Bearbeiten Sie die Program.cs-Datei.
Fügen Sie die Folgende Eigenschaft zur Program-Klasse hinzu. Diese Eigenschaft wird nach einer erfolgreichen Verbindung mit einem Dynamics 365-Server initialisiert.

private HttpClient httpClient;

Fügen Sie in der Main-Methode die folgenden Anweisungen hinzu.

Program app = new Program();
try
{
    String[] arguments = Environment.GetCommandLineArgs();
    app.ConnectToCRM(arguments);
}
catch (System.Exception ex)
{ ; }
finally
{
    if (app.httpClient != null)
    { app.httpClient.Dispose(); }
}

Fügen Sie als Nächstes die ConnectToCRM-Methode hinzu, die die Hilfebibliothek-Klassen Configuration und Authentication verwendet. Der folgende Code zweigt das Zuweisen von Werten zu den HttpClient-Eigenschaften, damit Sie auf die veröffentlichte Version der Dynamics 365-Web-API zugreifen können.

private void ConnectToCRM(String[] cmdargs)
{
    Configuration config = null;
    if (cmdargs.Length > 0)
        config = new FileConfiguration(cmdargs[0]);
    else
        config = new FileConfiguration(null);
    Authentication auth = new Authentication(config);
    httpClient = new HttpClient(auth.ClientHandler, true);
    httpClient.BaseAddress = new Uri(config.ServiceUrl + "api/data/v8.1/");
    httpClient.Timeout = new TimeSpan(0, 2, 0);
    httpClient.DefaultRequestHeaders.Add("OData-MaxVersion", "4.0");
    httpClient.DefaultRequestHeaders.Add("OData-Version", "4.0");
    httpClient.DefaultRequestHeaders.Accept.Add(
        new MediaTypeWithQualityHeaderValue("application/json"));
}

Fehlerbehandlungscode hinzufügen

Die folgenden Änderungen fügen Code hinzu, über den Ausnahmen abgefangen und in der Konsole angezeigt werden (inkl. Web-API-Fehler). Wenn Sie eine andere Umgebung entwickeln, ändern Sie den Ausnahmebehandlungscode entsprechend.

Fügen Sie in Main die folgende Anweisung zum catch-Block hinzu.

DisplayException(ex);

Fügen Sie die entsprechende Methode zur Program-Klasse hinzu.

private static void DisplayException(Exception ex)
{
    Console.WriteLine("The application terminated with an error.");
    Console.WriteLine(ex.Message);
    while (ex.InnerException != null)
    {
        Console.WriteLine("\t* {0}", ex.InnerException.Message);
        ex = ex.InnerException;
    }
}

Speichern Sie alle Dateien der Lösung.

Nächste Schritte

An dieser Stelle kann die Lösung ohne Fehler erstellt werden. Wenn Sie die Anwendungskonfigurationsdatei bearbeiten, um Werte für Microsoft Dynamics 365 Server bereitzustellen, sollten sich das Programm mit diesem Server verbinden. Die Lösung stellt einen grundlegenden Rahmen dar, der für benutzerdefinierten Code verwendet werden kann (inkl. Aufrufe der Dynamics 365-Web-API).

Tipp

Bevor Sie das Thema verlassen, sollten Sie darüber nachdenken, das Projekt als Projektvorlage zu speichern. Sie können die Vorlage dann wieder für zukünftige Lernprojekte verwenden und sich etwas Zeit und Aufwand bei der Erstellung neue Projekte ersparen. Wählen Sie dazu im Menü Datei die Option Exportvorlage, aus, während das Projekt in Microsoft Visual Studio geöffnet ist. Befolgen Sie Anweisungen des Vorlagenexportassistenten zum Erstellen der Vorlage.

Siehe auch

Erste Schritte mit dem Microsoft Dynamics 365 Web API (C#)
Verwenden Sie die Microsoft Dynamics 365 WEB API Hilfe-Bibliothek (C#)
Vorgänge mithilfe der Web-API ausführen

Microsoft Dynamics 365