Web API-eksempler (C#)
Udgivet: januar 2017
Gælder for: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
Dette emne indeholder oplysninger om de Web API-eksempler, der er implementeret med C#. Mens hvert eksempel fokuserer på forskellige aspekter af Microsoft Dynamics 365 Web API, har de samme egenskaber og struktur.
Bemærk
Denne implementeringstilgang bruger objektoprettelse på laveste niveau og eksplicitte HTTP-meddelelsesopkald. Denne metode giver mulighed for kontrol og demonstration af objektegenskaber på lavt niveau, som styrer funktionsmåden for Web-API. Dette har til formål at hjælpe dig med at forstå de bagvedliggende funktioner, men repræsenterer ikke nødvendigvis en tilgang, som giver den bedste oplevelse af udviklerens produktivitet.
Derimod fjerner biblioteker på et højere niveau, som f.eks. OData-bibliotek, en stor del af af denne klientlogik på lavt niveau.OData T4-skabelonen kan også bruges sammen med OData-biblioteket til at oprette klientobjektklasser automatisk.
Dette emne indeholder
Forudsætninger
Liste over Web API-eksempler (C#)
Sådan hentes og køres prøverne
Fælles elementer, der findes i hvert eksempel
Forudsætninger
Følgende er påkrævet for at opbygge og køre Dynamics 365 Web API C#-eksempler:
En version af Microsoft Visual Studio 2015 eller nyere. En gratis version, Visual Studio Community, kan hentes her.
En internetforbindelse til at hente og opdatere de refererede NuGet-pakker.
Adgang til Dynamics Dynamics 365 Online eller til det lokale miljø (eller nyere). For alle typer af Dynamics 365-installationer kræves en konto med rettigheder til at udføre CRUD-handlinger.
For at kunne køre eksempler i forhold til Dynamics 365 (online), skal du registrere dit program med Azure Active Directory for at få et klient-id og en URL-adresse for omdirigering. Du kan finde flere oplysninger under Gennemgang: Registrere en Dynamics 365-app med Azure Active Directory.
Liste over Web API-eksempler (C#)
I følgende tabel vises de eksempler, der er implementeret i C#. Hvert eksempel er beskrevet i mere generel form i et tilsvarende emne for eksempelgruppen, som fokuserer på HTTP-anmodningen og svarmeddelelser, som beskrevet i emnet Web API-eksempler.
Eksempel |
Eksempelgruppe |
Beskrivelse |
|---|---|---|
Demonstrerer, hvordan du opretter, henter, opdaterer, sletter, knytter og tilknytter Dynamics 365-objektposter. |
||
Demonstrerer, hvordan du bruger OData v4-forespørgselssyntaks og -funktioner foruden Microsoft Dynamics 365-forespørgselsfunktioner. Indeholder eksempler på arbejde med foruddefinerede forespørgsler og brug af FetchXML til at udføre forespørgsler. |
||
Demonstrerer, hvordan du udfører betingede handlinger, som du angiver med ETag-kriterier. |
||
Demonstrerer, hvordan du bruger bundne og ikke-bundne funktioner og handlinger, herunder brugerdefinerede handlinger. |
Sådan hentes og køres prøverne
Kildekoden for hvert eksempel er tilgængelig på MSDN Code Gallery. Linket til at hente hvert eksempel er inkluderet i eksempelemnet. Eksempeloverførslen er en komprimeret .zip-fil, der indeholder Visual Studio-2015-løsningsfiler for eksemplet. Du kan finde flere oplysninger i afsnittet Kør dette eksempel i hvert eksempelemne.
Fælles elementer, der findes i hvert eksempel
De fleste eksempler har en lignende struktur og indeholder fælles metoder og ressourcer, som normalt anvendes til at etablere den grundlæggende infrastruktur for et Web-API'EN C#-program.
Mange af disse fælles elementer er også til stede, når du opretter en ny løsning, der får adgang til Dynamics 365 Web API. Du kan finde flere oplysninger under Starte et Dynamics 365 Web API-projekt i Visual Studio (C#).
Udnyttede biblioteker og strukturer
Denne C#-implementering afhænger af følgende hjælperkode for HTTP-kommunikation, programkonfiguration, godkendelse, fejlhåndtering og JSON-serialisering.
Standardklasser for .NET Framework HTTP-meddelelser, der er indeholdt i System.Net.Http-navneområdet, især HttpClient, HttpRequestMessage og HttpResponseMessage, der bruges til HTTP-meddelelser.
Dynamics 365 Web API Helper-biblioteket bruges til at læse programkonfigurationsfilen, godkende med Dynamics 365-serveren og hjælpe med håndtering af fejl i handlingen. Du kan finde flere oplysninger under Brug af Microsoft Dynamics 365 Web API Helper-bibliotek (C#).
Newtonsoft Json.NET-biblioteket understøtter JSON-dataformatet.
Json.NET-bibliotek
Eftersom C# og de fleste andre administrerede sprog ikke oprindeligt understøtter JSON-dataformatet, er den bedste aktuelle metode at bruge et bibliotek til denne funktionalitet. Yderligere oplysninger finder du i En introduktion til JavaScript Object Notation (JSON) i JavaScript og .NET. Json.NET er et populært valg for .NET-projekter. Det giver en robust, effektiv (MIT-licenseret) struktur for åben kildekode til serialisering, konvertering, analyse, forespørgsler og formatering af JSON-data. Du kan finde flere oplysninger i Json.NET-dokumentationen .
I C#-eksempler bruges dette bibliotek primært til at serialisere data mellem .NET-objekter og i HTTP-meddelelsestekster. Selvom biblioteket indeholder flere metoder til at udføre denne opgave, er den metode, der bruges af eksemplerne, at oprette individuelle JObject-forekomster til at repræsentere Dynamics 365-objektforekomster (poster). For eksempel opretter følgende kode variablen contact1, der repræsenterer en Dynamics 365contact EntityType-forekomst, og derefter leverer værdier for bestemte egenskaber for denne type.
JObject contact1 = new JObject();
contact1.Add("firstname", "Peter");
contact1.Add("lastname", "Cambel");
contact1.Add("annualincome", 80000);
contact1["jobtitle"] = "Junior Developer";
Brug af parentesnotationen i den sidste sætning svarer til metodden Tilføj. Denne instantiering kunne også opnås gennem anvendelsen af den statiske metode Opdel tekst:
JObject contact1 = JObject.Parse(@"{firstname: 'Peter', lastname: 'Cambel', "
+ @"annualincome: 80000, jobtitle: 'Junior Developer'}");
Da JObject repræsenterer en generel JSON-type, udelukker anvendelsen heraf meget kontrol af runtime-typen. Mens følgende sætning eksempelvis er syntaktisk gyldig, vil den potentielt medføre kørselsfejl, fordi contact EntityType ikke indeholder ikke en age-egenskab.
contact1.Add("age", 37); //Possible error--no age property exists in contact!
Når objektvariablen er blevet initialiseret, kan den derefter sendes i en meddelelsestekst med hjælp fra flere System.Net.Http-klasser, for eksempel:
HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "contacts");
request.Content = new StringContent(contact1.ToString(), Encoding.UTF8, "application/json");
HttpResponseMessage response = await httpClient.SendAsync(request1);
Du kan også oprette JObject-forekomster ved deserialisering af objektforekomster under hentning af handlinger, for eksempel:
//contact2Uri contains a reference to an existing CRM contact instance.
string queryOptions = "?$select=fullname,annualincome,jobtitle,description";
HttpResponseMessage response = await httpClient.GetAsync(contact2Uri + queryOptions);
JObject contact2 = JsonConvert.DeserializeObject<JObject>(await response.Content.ReadAsStringAsync());
Svarsucces og fejlhåndtering
Generelt benytter eksempler en ligetil tilgang til behandling af HTTP-svar. Hvis anmodningen lykkes, er oplysninger om handlingen typisk output til konsollen. Hvis svaret også indeholder JSON-nyttedata eller nyttige hoveder, behandles disse oplysninger kun efter succes. Og endelig, hvis et Dynamics 365-objekt blev oprettet, opdateres entityUris-samlingen med URI'en for den pågældende ressource.DeleteRequiredRecords-metode-metoden bruger denne samling eventuelt at slette data, der er oprettet af eksemplet fra Dynamics 365-serveren.
Hvis anmodningen mislykkedes, viser programmet en kontekstafhængig meddelelse om den handling, der mislykkedes, og derefter viser den en brugerdefineret undtagelse af typen CrmHttpResponseException. Undtagelseshandleren leverer flere oplysninger om undtagelsen, og derefter overføres styringen til en finally-blok, der omfatter oprydningslogik, herunder igen et kald til DeleteRequiredRecords. Følgende kode demonstrerer denne fejlhåndteringsmetode for en POST-anmodning med henblik på at oprette en post.
if (response.StatusCode == HttpStatusCode.NoContent) //204
{
Console.WriteLine("POST succeeded, entity created!”);
//optionally process response message headers or body here, for example:
entityUri = response.Headers.GetValues("OData-EntityId").FirstOrDefault();
entityUris.Add(entityUri);
}
else
{
Console.WriteLine("Operation failed: {0}", response.ReasonPhrase);
throw new CrmHttpResponseException(response.Content);
}
HttpStatusCode.NoContent svarer til en HTTP-statuskode 204 "Intet indhold". Her angiver denne statuskode, at POST-anmodningen lykkedes. Yderligere oplysninger finder du i Skrive HTTP-anmodninger og håndtere fejl.
Egenskaber og metoder
De fleste af eksemplerne har samme generelle arkitektoniske mønster, med følgende egenskaber:
Hele den relevante C#-eksempelkode er indeholdt i den primære kildefil med navnet Program.cs, som indeholder en enkelt klasse med samme navn som eksempelprojektet.
Eksempelklasserne, samt Brug af Microsoft Dynamics 365 Web API Helper-bibliotek (C#), er indeholdt i navneområdet Microsoft.Crm.Sdk.Samples.
Eksemplerne er bredt kommenterede: oversigter leveres på klasse- og metodeniveau, og de fleste vigtige enkeltsætninger har tilknyttede kommentarer på samme eller enkelt linje. Supplerende filer, f.eks programkonfigurationsfilen App.config, indeholder også ofte vigtige kommentarer.
Den primære eksempelklasse er typisk struktureret til at indeholde følgende fælles sæt af metoder: Hovedmetode, ConnectToCRM-metode, CreateRequiredRecords-metode, RunAsync-metode, DisplayException-metode og DeleteRequiredRecords-metode.
Hovedmetode
Denne metode starter pr. definition udførelsen af eksemplet. Den indeholder kun logik for styringsforløb på højt niveau og undtagelseshåndtering ofte præcis følgende kode:
static void Main(string[] args)
{
FunctionsAndActions app = new FunctionsAndActions();
try
{
//Read configuration file and connect to specified CRM server.
app.ConnectToCRM(args);
app.CreateRequiredRecords();
Task.WaitAll(Task.Run(async () => await app.RunAsync()));
}
catch (System.Exception ex) { DisplayException(ex);
}
finally
{
if (app.httpClient != null)
{
app.DeleteRequiredRecords(true);
app.httpClient.Dispose();
}
Console.WriteLine("Press <Enter> to exit the program.");
Console.ReadLine();
}
}
ConnectToCRM-metode
Denne metode kalder på hjælperbibliotekerne for at læse programmets konfigurationsfil og opretter derefter forbindelse til den angivne Dynamics 365-server. Resultatet af disse trin er initialiseringen af en HttpClient-klasseegenskab, der bruges i hele programmet til at sende webanmodninger og modtage svar. Bemærk, at følgende egenskaber er angivet for dette objekt:
//Define the Web API address, the max period of execute time, the Odata
// version, and the expected response payload format.
httpClient.BaseAddress = new Uri(config.ServiceUrl + "api/data/v8.1/");
httpClient.Timeout = new TimeSpan(0, 2, 0); // 2 minute timeout
httpClient.DefaultRequestHeaders.Add("OData-MaxVersion", "4.0");
httpClient.DefaultRequestHeaders.Add("OData-Version", "4.0");
httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
Du kan finde flere oplysninger om eksemplets programkonfiguration og godkendelse under Brug af Microsoft Dynamics 365 Web API Helper-bibliotek (C#).
CreateRequiredRecords-metode
Denne metode opretter og starter objektposter, der kræves af eksemplet, når disse handlinger ikke er af primær interesse i eksemplet. For eksempel indeholder Eksempel på Web API Basic-operationer (C#) ikke denne metode, fordi oprettelsen af posten er en primær faktor i eksemplet.
RunAsync-metode
Følgende asynkrone metode indeholder den relevante kildekode eller kalder for længere programmer, de metoder, der grupperer de relevante eksempelkode. Den indeholdte kode er forklaret af integrerede bemærkninger og kommentarer, der er placeret i afsnittet Kommentarer i hvert tilsvarende emne i eksemplet.
DisplayException-metode
Denne hjælpermetode viser undtagelsesoplysninger, herunder indre undtagelser, til standardkonsollen.
DeleteRequiredRecords-metode
Denne supplerende metode sletter også eksempelposter og andre Dynamics 365-serverressourcer, der er oprettet i programmet og særligt ved hjælp af CreateRequiredRecords-metode-metoden. Den anmoder brugeren om bekræftelse af denne handling, gennemløber derefter entityUris-samlingen og forsøger at slette hvert element med en HTTP DELETE-meddelelse.
Se også
Brug Microsoft Dynamics 365 Web API
Web API-eksempler
Web API-eksempler (JavaScript på klientsiden)
Eksempel på Web API Basic-operationer (C#)
Eksempel på Web API-forespørgselsdata (C#)
Eksempel på Web API Conditional operationer (C#)
Web API-funktioner og handlingseksempel (C#)
Microsoft Dynamics 365
© 2017 Microsoft. Alle rettigheder forbeholdes. Ophavsret