Starte et Dynamics 365 Web API-projekt i Visual Studio (C#)

Artikel
04/18/2017

Udgivet: januar 2017

Gælder for: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

I dette emne beskrives det, hvordan du opretter et nyt projekt i Microsoft Visual Studio, der opbygger et konsolprogram, der bruger Dynamics 365 Web API. Det illustrerer de fælles referencer og projektressourcer, som de fleste programmer, herunder SDK C#-eksemplerne, kan bruge til at implementere Web API-baserede løsninger.

Forudsætninger

Følgende forudsætninger er obligatoriske for at bygge konsolprogrammet, der er beskrevet i dette afsnit.

Microsoft Visual Studio 2015 installeret på din udviklercomputer. Alle udgaver, herunder Visual Studio Express, bør være tilstrækkelige til at arbejde med Dynamics 365 Web API. Du kan finde flere oplysninger om, hvilke versioner af Microsoft Visual Studio der understøttes, under Visual Studio og .NET Framework.
En NuGet-klient skal installeres: enten kommandolinjefunktionen eller udvidelsen Visual Studio. Du kan finde flere oplysninger under Installation af NuGet.
Der kræves en internetforbindelse for at hente den NuGet-pakke, der indeholder Dynamics 365 Web API Helper-biblioteket og andre afhængige pakker.
Du kan også downloade Microsoft Dynamics 365-SDKher. Selv om Microsoft Dynamics 365-SDK ikke er påkrævet for at oprette eller køre Web API-eksemplerne, vil de fleste Dynamics 365-udviklere installere den, fordi den indeholder et omfattende udvalg af supplerende ressourcer, og der kræves adgang til andre Dynamics 365-grænseflader.

Opret et projekt

Den følgende procedure demonstrerer, hvordan du opretter et konsolprogramprojekt i C#, som bruger Microsoft .NET Framework. Du kan få flere oplysninger om understøttede versioner af .NET Framework under Understøttede udvidelser til Microsoft Dynamics 365.

Nyt projekt

Klik på Nyt projekt i Microsoft Visual Studio. Dialogboksen Nyt projekt vises.
I venstre navigationsrude under Skabeloner skal du vælge Visual C#.
Over listen over tilgængelige skabeloner skal du vælge .NET Framework 4.5.2.
På listen med skabeloner skal du vælge Konsolprogram. (Du kan også vælge den projekttype, der passer til din løsning). Alle eksempler på Web API C# er konsolprogrammer.
Angiv projektnavnet og -placeringen i tekstfelterne nederst på formularen, og vælg derefter OK. (For dette emne er løsningsnavnet "StartWebAPI-CS" brugt). De første løsningsfiler genereres, og løsningen indlæses i Microsoft Visual Studio.
Under menuen Projekt skal du åbne formularen med projektegenskaber og kontrollere at, målstrukturen er angivet til .NET Framework 4.5.2.

Tilføje alle krævede ressourcer til dit projekt

De følgende procedurer forklarer, hvordan du kan tilføje alle krævede administrerede referencer og pakker til projektet. Betragt dette som et grundlæggende sæt af referencer, som de fleste administrerede kodeprogrammer behøver for at aktivere Web API-handlinger.

Tilføje hjælperbiblioteket for NuGet-pakken

Dynamics 365 SDK Web API Helper-biblioteket indeholder klasser, som hjælper med supplerende handlinger som f.eks. programkonfiguration, 365 Dynamics server-godkendelse, undtagelseshåndtering og webkommunikation. Du kan finde flere oplysninger under Brug af Microsoft Dynamics 365 Web API Helper-bibliotek (C#). Brugen af disse klasser er valgfri, men de er anvendes bredt i Web API-eksemplerne. Dynamics 365 SDK Web API Helper-biblioteket distribueres i kildekodeformularen som en NuGet-pakke. Fremtidige opdateringer vil blive distribueret som NuGet-pakkeopdateringer.

Hvis du har installeret NuGet-kommandolinefunktionen eller bruger pakkestyringskonsollen i Visual Studio:

Udstede følgende kommando for at installere hjælperbibliotekspakken.

Install-Package Microsoft.CrmSdk.WebApi.Samples.HelperCode
Der vises flere meddelelser om behandling af afhængighedspakker. Hvis dialogboksen Licensaftale vises, skal du læse licensbetingelserne og klikke på Accepter.
Gå til trin 6 nedenfor for at bekræfte installationen af hjælperbibliotekspakken.

Hvis du har installeret NuGet Pakkestyring-udvidelsen:

Fra menuen Projekt skal du vælge Administrer NuGet-pakker. Fanen NuGet Pakkestyring vises.
I øverste højre hjørne, skal du angive rullelisten for Pakke-kilden til Nuget.org.
I det øverste venstre hjørne skal du klikke på Gennemse og derefter indtaste "Dynamics 365 HelperCode" i søgefeltet og trykke på Enter.
Klik på Installer. Hvis dialogboksen Eksempel er vist, skal du klikke på OK.
Dialogboksen Licensaftale vises. Gennemse licensbetingelserne, og klik på Jeg accepterer.
Naviger til vinduet Løsningsoversigt. Bekræft, at en ny løsningsmappe med navnet Web API-hjælperkode blev tilføjet.

Pakken med Dynamics 365 SDK Web API Helper-biblioteket, Microsoft.CrmSdk.WebApi.Samples.HelperCode, afhænger af følgende andre pakker, som hentes og installeres automatisk sammen med hjælperbibliotekspakken:

Newtonsoft.Json – indeholder Json.NET, et populært, MIT licenseret JSON-framework til .NET.
Microsoft.IdentityModel.Clients.ActiveDirectory – indeholder de binære filer til Active Directory-godkendelsesbiblioteket (ADAL), som indeholder funktioner til godkendelse til .NET-klienter.

Advarsel!

Pakken med Dynamics 365 SDK Web API Helper-biblioteket blev bygget i forhold til bestemte versioner af de andre to understøttende pakker. Af denne grund bør du kun opdatere hjælperbiblioteket i NuGet-pakken direkte. Denne handling opdaterer de rette understøttende pakker, hvis det er nødvendigt. Hvis du kun opdaterer en af disse understøttende pakker ad gangen, kan en nyere version af den pågældende pakke være inkompatibel med hjæperbiblioteket.

Kontrollere de krævede assemblyreferencer

I Løsningsoversigt skal du udvide noden Referencer.
Kontrollér, at følgende referencer er blevet føjet til projektet.
Hvis du har supplerende funktioner, som du regelmæssigt bruger i dine programmer, kan du nu føje de tilknyttede referencer til de nødvendige assemblier. Yderligere oplysninger finder du i Sådan: Tilføje eller fjerne referencer ved hjælp af dialogboksen Tilføj reference.

Da Dynamics 365 Web API'en er baseret på REST-principperne, kræves der ikke adgang til klient-assemblies. Andre API'er, som understøttes af Microsoft Dynamics 365, kræver dog disse. Yderligere oplysninger finder du i Assemblies, der er medtaget i Microsoft Dynamics 365 SDK'en.

Tilføje typisk ved hjælp af sætninger

I Løsningsoversigt skal du åbne Program.cs med henblik på redigering.
I toppen af filen skal du tilføje følgende using-sætninger, som refererer til navneområder, der normalt bruges i Dynamics 365 Web API-baserede løsninger.
```
using Microsoft.Crm.Sdk.Samples.HelperCode;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
```
Hvis du har tilføjet hyppigt anvendte assemblier eller referencer i de foregående afsnit, vil du måske også tilføje tilsvarende using-sætninger for disse ressourcer.
Gem filen.

Tilføje forbindelseskode

I dette afsnit forklares det, hvordan du føjer et grundlæggende sæt indstillinger og instruktioner i at udføre disse handlinger. Du kan finde flere oplysninger om den fælles kode under Brug af Microsoft Dynamics 365 Web API Helper-bibliotek (C#).

Redigere programkonfigurationsfilen

I Løsningsoversigt skal du åbne filen App.config for at redigere den. Tilføj følgende to afsnit til den, efter det eksisterende <startup>-afsnit, og gem derefter filen.

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

Under udvikling eller implementering af en løsning skal de aktuelle værdier for forbindelse og programregistrering indsættes i stedet for eksempelværdierne, der fungerer som pladsholdere. Du kan finde flere oplysninger under Web-API-hjælpekode: konfiguration af klasser.

Tilføje kode for at hente hjælperbiblioteket

Rediger filen Program.cs.
Tilføj den følgende egenskab til programklassen. Denne egenskab initialiseres, når der er oprettet forbindelse til en Dynamics 365-server.

private HttpClient httpClient;

I metoden Main skal du tilføje følgende sætninger.

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

Dernæst skal du tilføje metoden ConnectToCRM, som bruger hjælperbibliotekets Configuration- og Authentication-klasser. Følgende kode demonstrerer tildelingen af værdier til HttpClient-egenskaberne, så du kan få adgang til release-versionen af Dynamics 365 Web API.

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"));
}

Tilføje fejlhåndteringskode

Følgende ændringer tilføjer kode for at fange og rapportere undtagelser til konsollen, herunder Web-API-fejl. Hvis du målretter til et andet miljø, skal du redigere koden for undtagelseshåndtering korrekt for det pågældende miljø.

I Main skal du tilføje følgende sætning til catch-blokken.

DisplayException(ex);

Tilføj den tilsvarende metode til Program-klassen.

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

Gem alle filer i løsningen.

Næste trin

På dette tidspunkt kan løsningen bygges uden fejl. Hvis du redigerer programkonfigurationsfilen for at angive værdier for Microsoft Dynamics 365 Server, bør programmet også kunne oprette forbindelse til serveren. Løsningen repræsenterer en skeletstruktur, der er klar til at modtage brugerdefineret kode, herunder opkald til Dynamics 365 Web API.

Tip

Før du forlader dette emne, kan du overveje at gemme dit projekt som en projektskabelon. Du kan derefter genbruge skabelonen til fremtidige læringsprojekter og spare tid og besvær med at oprette nye projekter. Til dette formål skal projektet være åbent i Microsoft Visual Studio, og du skal vælge menuen Filer og Eksportér skabelon. Følg instruktionerne i Guiden Eksportskabelon for at oprette skabelonen.

Se også

Introduktion til Microsoft Dynamics 365 Web API (C#)
Brug af Microsoft Dynamics 365 Web API Helper-bibliotek (C#)
Udføre operationer ved hjælp af web-API

Microsoft Dynamics 365

Share via