Eksempel på hurtig start af enkel Web-API (C#)

Artikel
04/18/2017

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

Dette eksempel viser, hvordan du godkender med en Microsoft Dynamics 365 Server og derefter kalder en grundlæggende Web API-handling, WhoAmI Function. I modsætning til andre Web API-eksempler afhænger dette eksempel ikke af andre ikke-standard hjælpebiblioteker eller flere kildefiler. Al dets kildekode er i en enkelt fil, Program.cs, for at gøre logikflowet og godkendelsesprocessen nemmere at forstå. Eksemplet fungerer med onlineinstallationer, installationer i det lokale miljø og installationer med adgang via internet.

Krav

Dette eksempel har følgende krav:

Til at åbne og bygge løsningen kræves Microsoft Visual Studio 2015 eller nyere. Gratis versioner af dette produkt kan downloades: Visual Studio Express eller Visual Studio EF.
Forbindelse til internettet eller netværksforbindelse til at oprette forbindelse til henholdsvis Microsoft Dynamics 365 Server online eller til det lokale miljø.
En brugerkonto på din Microsoft Dynamics 365 Server (online eller til det lokale miljø).
Hvis Dynamics 365 (online) benyttes, skal eksempelprogrammet være registreret Azure Active Directory, som beskrevet i Gennemgang: Registrere en Dynamics 365-app med Azure Active Directory.
Hvis Dynamics 365 (i det lokale miljø) med Installation med adgang via internet benyttes, skal eksempelprogrammet være registreret hos din Active Directory-lejer, som beskrevet i Gennemgang: Registrere en Dynamics 365-app med Active Directory.

Vigtigt

Som udgangspunkt opbygges løsningen ikke korrekt. Kildekoden skal redigeres i de linjer, der er angivet i //TODO-kommentarer, for at oplys brugerkonto og/eller programregistreringsoplysninger.

Demonstrerer

Dette simple eksempel demonstrerer to grundlæggende begreber, der kræves til udvikling ved hjælp af Web-API: godkendelse mod en Microsoft Dynamics 365 Server og oprettelse af grundlæggende Web API-kald ved hjælp af HTTP-protokollen.

Der kræves godkendelse, før et klientprogram kan få adgang til en Dynamics 365 ressource. Denne proces kan være væsentlig af to årsager: der skal bruges forskellige godkendelsesmekanismer til de forskellige installationstyper, og webbaserede godkendelsesmekanismer omfatter typisk flere programmeringstrin. Windows-integreret godkendelse, som kræves til lokale installationer, er relativt ligetil og kræver kun et brugernavn og en adgangskode. Efterfølgende fungerer programmet som en agent for den godkendte bruger.

I modsætning hertil kræver online og IFD-installationer registrering af klientprogrammet på forhånd og bruger derefter en OAuth-godkendelsesproces med flere trin. Registreringsprocessen for Dynamics 365 (online) er beskrevet i artiklen Gennemgang: Registrere en Dynamics 365-app med Azure Active Directory. Registreringsprocessen for Dynamics 365 (i det lokale miljø) med Installation med adgang via internet er beskrevet i artiklen Gennemgang: Registrere en Dynamics 365-app med Active Directory. Hver efterfølgende Web API-anmodning skal godkendes med OAuth. Heldigvis kan meget af kompleksiteten ved OAuth-godkendelse forenkles ved hjælp af Active Directory-godkendelsesbiblioteker (ADAL) til .NET-klienter, der føjes til eksemplet som NuGet-pakken Microsoft.IdentityModel.Clients.ActiveDirectory. OAuth-godkendelse er yderligere indkapslet i dette eksempel gennem inkludering af OAuthMessageHandler-klassen, som føjer den krævede OAuth-godkendelsesheader til meddelelsesanmodninger. I fremtidige eksempler er understøttelse af godkendelsesfunktioner adskilt i Web API Helper-biblioteket. Du kan finde flere oplysninger under Godkende brugere i Microsoft Dynamics 365.

Dynamics 365 Web-API'en er et REST API, der er baseret på OData-specifikationen, så det understøtter standardiserede HTTP-anmodninger mod objekter og kaldefunktioner og -handlinger. Dette eksempel demonstrerer aktivering af WhoAmI Function-funktionen med en GET-anmodning, og derefter bruges de oplysninger, som denne funktion giver, i det resulterende HTTP-svar. Dette eksempel udnytter flere standardbiblioteker til at hjælpe med denne aktivering:

.NET Framework-klasserne fra System.Net og System.Net.Http-navneområderne bruges til HTTP-kommunikation.
Da C# ikke har indbygget understøttelse af JSON, er open source Json.NET framework inkluderet i dets NuGet-pakke.
Asynkron programmering understøttes af navneområdet System.Threading.Tasks. På grund af mulige forsinkelser bliver der typisk anvendt asynkrone mekanismer ved webadgang. Du kan finde flere oplysninger under Asynkron programmering med Async og Await.

Køre dette eksempel

Gå først til Eksempel på hurtig start af enkel Web-API (C#), download eksempelarkivfilen, Simple Web API quick-start sample (CS.zip), og pak indholdet ud i en lokal mappe. Denne mappe skal indeholde følgende filer:

Filer	Formål/beskrivelse
Program.cs	Indeholder kildekoden til dette eksempel.
SimpleWebApi.sln SimpleWebApi.csproj packages.config AssemblyInfo.cs App.config	Microsoft Visual Studio 2015-standardløsningen, -projektet, konfiguration af NuGet-pakken og filer med assemblyoplysninger og programkonfigurationsfiler til dette eksempel.

Brug dernæst følgende procedure til at køre dette eksempel.

Find og dobbeltklik på løsningsfilen, SimpleWebApi.sln, for at indlæse løsningen i Visual Studio.
I Solution Explorer skal du dobbeltklikke på filen Program.cs for at åbne den i editoren.
Find //TODO-kommentarerne i Main-metoden, tilføj de krævede strengværdier for forbindelsen, og fjern kommentarmærkerne i de tilhørende linjer.
Byg SimpleWebApi-løsningen. Dette bør automatisk hente og installere alle krævede NuGet-pakker, som mangler eller skal opdateres.
Kør projektet SimpleWebApi fra Visual Studio. Alle eksempelløsninger er konfigureret til at køre i fejlfindingstilstand som standard.
Funktionsmåden afhænger af installationstypen.
- Ved online og IFD-installationer åbner konsolprogrammet et nyt vindue, hvor du kan angive dine logonoplysninger og adgangskode.
- Ved lokale installationer beder konsolprogrammet dig om en adgangskode for den angivne Dynamics 365-konto.
Angiv disse oplysninger, og tryk på Enter.

Kodeoversigt

Den mest aktuelle kilde til denne fil findes i eksempeloverførselspakken.

Program.cs

namespace Microsoft.Crm.Sdk.Samples
{
    /// <summary>
    /// A basic Web API client application for Dynamics 365 (CRM). This sample authenticates 
    /// the user and then calls the WhoAmI Web API function. 
    /// </summary>
    /// <remarks> 
    /// Prerequisites: 
    ///   -  To run this application, you must have a CRM Online or on-premise account. 
    ///   -  For CRM Online or Internet-facing deployments (IFD), the application must be registered  
    ///      with Azure Active Directory as described in this article: 
    ///      https://msdn.microsoft.com/en-us/library/dn531010.aspx
    ///   
    /// The WhoAmI Web API function is documented here: 
    ///    https://msdn.microsoft.com/en-us/library/mt607925.aspx
    /// </remarks>
    static class SimpleWebApi
    {
        //TODO: Uncomment then substitute your correct Dynamics 365 organization service 
        // address for either CRM Online or on-premise (end with a forward-slash).
        //private static string serviceUrl = "https://mydomain.crm.dynamics.com/myorg/";   // CRM Online
        //private static string serviceUrl = "https://<organization name>.<domain name>/";   // CRM IFD
        //private statics string serviceUrl = "http://myserver/myorg/";        // CRM on-premises

        //TODO: For an on-premises deployment, set your organization credentials here. (If
        // online or IFD, you can you can disregard or set to null.)
        private static string userAccount = "<user-account>";  //CRM user account
        private static string domain = "<server-domain>";  //CRM server domain

        //TODO: For CRM Online or IFD deployments, substitute your app registration values  
        // here. (If on-premise, you can disregard or set to null.)
        private static string clientId = "<app-reg-guid>";     //e.g. "e5cf0024-a66a-4f16-85ce-99ba97a24bb2"
        private static string redirectUrl = "<redirect-URL>";  //e.g. "https://localhost/SdkSample"

        static public void Main(string[] args)
        {
            //One message handler for OAuth authentication, and the other for Windows integrated 
            // authentication.  (Assumes that HTTPS protocol only used for CRM Online.)
            HttpMessageHandler messageHandler;
            if (serviceUrl.StartsWith("https://"))
            {
                messageHandler = new OAuthMessageHandler(serviceUrl, clientId, redirectUrl,
                         new HttpClientHandler());
            }
            else
            {
                //Prompt for user account password required for on-premise credentials.  (Better
                // approach is to use the SecureString class here.)
                Console.Write("Please enter the password for account {0}: ", userAccount);
                string password = Console.ReadLine().Trim();
                NetworkCredential credentials = new NetworkCredential(userAccount, password, domain);
                messageHandler = new HttpClientHandler() { Credentials = credentials };
            }
            try
            {
                //Create an HTTP client to send a request message to the CRM Web service.
                using (HttpClient httpClient = new HttpClient(messageHandler))
                {
                    //Specify the Web API address of the service and the period of time each request 
                    // has to execute.
                    httpClient.BaseAddress = new Uri(serviceUrl);
                    httpClient.Timeout = new TimeSpan(0, 2, 0);  //2 minutes

                    //Send the WhoAmI request to the Web API using a GET request. 
                    var response = httpClient.GetAsync("api/data/v8.1/WhoAmI",
                            HttpCompletionOption.ResponseHeadersRead).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 system user ID is: {0}", userId);
                    }
                    else
                    {
                        Console.WriteLine("The request failed with a status of '{0}'",
                               response.ReasonPhrase);
                    }
                }
            }
            catch (Exception ex)
            {
                DisplayException(ex);
                throw;
            }
            finally
            {
                Console.WriteLine("Press <Enter> to exit the program.");
                Console.ReadLine();
            }
        }

        /// <summary> Displays exception information to the console. </summary>
        /// <param name="ex">The exception to output</param>
        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;
            }
        }
    }

    /// <summary>
    ///Custom HTTP message handler that uses OAuth authentication thru ADAL.
    /// </summary>
    class OAuthMessageHandler : DelegatingHandler
    {
        private AuthenticationHeaderValue authHeader;

        public OAuthMessageHandler(string serviceUrl, string clientId, string redirectUrl,
                HttpMessageHandler innerHandler)
            : base(innerHandler)
        {
            // Obtain the Azure Active Directory Authentication Library (ADAL) authentication context.
            AuthenticationParameters ap = AuthenticationParameters.CreateFromResourceUrlAsync(
                    new Uri(serviceUrl + "api/data/")).Result;
            AuthenticationContext authContext = new AuthenticationContext(ap.Authority, false);
            //Note that an Azure AD access token has finite lifetime, default expiration is 60 minutes.
            AuthenticationResult authResult = authContext.AcquireToken(serviceUrl, clientId, new Uri(redirectUrl));
            authHeader = new AuthenticationHeaderValue("Bearer", authResult.AccessToken);
        }

        protected override Task<HttpResponseMessage> SendAsync(
                 HttpRequestMessage request, System.Threading.CancellationToken cancellationToken)
        {
            request.Headers.Authorization = authHeader;
            return base.SendAsync(request, cancellationToken);
        }
    }
}

Se også

Web API Reference
Web API-eksempler
Brug af Microsoft Dynamics 365 Web API Helper-bibliotek (C#)
Godkende brugere i Microsoft Dynamics 365

Microsoft Dynamics 365

Del via