Delen via

Web-API-voorbeelden (C#)

  • Artikel

 

Gepubliceerd: januari 2017

Is van toepassing op: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Dit onderwerp geeft informatie over de web-API-voorbeelden die worden geïmplementeerd met C#. Elk voorbeeld is gericht op een ander aspect van de Microsoft Dynamics 365-web-API, maar zij hebben toch kenmerken en een structuur met elkaar gemeen.

Notitie

Deze implementatiebenadering maakt gebruik van objectcreatie op laag niveau en expliciete HTTP-berichtaanroepen. Met deze benadering kunnen objecteigenschappen op laag niveau worden beheerst en gedemonstreerd, die op hun beurt het gedrag van de web-API aansturen. Zo leert u beter begrijpen wat zich onder water afspeelt, maar dit is niet noodzakelijkerwijs een benadering die de beste productiviteitservaring oplevert voor ontwikkelaars.

Bibliotheken op hoger niveau, zoals de OData Library maken daarentegen veel van deze client-logica op laag niveau onzichtbaar. U kunt eventueel de OData T4-sjabloon in combinatie met de OData Library gebruiken om automatisch klassen van client-entiteiten aan te maken.

In dit onderwerp

Vereisten

Overzicht van web-API-voorbeelden (C#)

De voorbeelden downloaden en uitvoeren

Gemeenschappelijke elementen voor alle voorbeelden

Vereisten

Voor het samenstellen en uitvoeren van de C#-voorbeelden voor de web-API van Dynamics 365 is het volgende vereist:

  • Een versie van Microsoft Visual Studio 2015 of hoger. Een gratis versie, Visual Studio Community, is hier beschikbaar als download.

  • Een internetverbinding om de NuGet-pakketten waarnaar wordt verwezen, te downloaden en bij te werken.

  • Toegang tot Dynamics 365 Online of on-premises (of hoger). Voor alle typen Dynamics 365-installaties is een gebruikersaccount vereist met de machtigingen voor het uitvoeren van CRUD-bewerkingen.

  • Als u de voorbeelden op Dynamics 365 (online) wilt uitvoeren, moet u uw toepassing registreren bij Azure Active Directory om een client-ID en een omleidings-URL te verkrijgen. Zie Overzicht: een Dynamics 365-app registreren bij Azure Active Directory voor meer informatie.

Overzicht van web-API-voorbeelden (C#)

In de volgende tabel vindt u de voorbeelden die in C# zijn geïmplementeerd. Elk voorbeeld wordt op een algemene manier beschreven in een bijbehorend voorbeeldgroeponderwerp dat zich richt op de aanvraag- en responsberichten in HTTP, zoals uiteengezet in het onderwerp Web-API-voorbeelden.

Voorbeeld

Voorbeeldgroep

Beschrijving

Voorbeeld van eenvoudige Web API-bewerkingen (C#)

Voorbeeld van eenvoudige Web API-bewerkingen

Laat zien hoe u entiteitsrecords in Dynamics 365 kunt maken, ophalen, bijwerken, verwijderen, koppelen en ontkoppelen.

Voorbeeld gegevens Web API-query (C#)

Voorbeeld gegevens Web API-query

Laat zien hoe u de querysyntaxis en -functies van OData v4 toepast, evenals de queryfuncties van Microsoft Dynamics 365. Bevat voorbeelden van het werken met vooraf gedefinieerde query's en het gebruik van FetchXML om query's uit te voeren.

Voorbeeld van voorwaardelijke Web API-bewerkingen (C#)

Voorbeeld van voorwaardelijke Web API-bewerkingen

Laat zien hoe u voorwaardelijke bewerkingen uitvoert die u opgeeft met ETag-criteria.

Web API-functies en actievoorbeeld (C#)

Web API-functies en actievoorbeeld

Laat zien hoe u gebonden en ongebonden functies en acties gebruikt, inclusief aangepaste acties.

De voorbeelden downloaden en uitvoeren

De broncode voor elk voorbeeld vindt u in de MSDN Code Gallery. De koppeling voor het downloaden van een voorbeeld vindt u in het artikel waarin het voorbeeld wordt besproken. De download bestaat uit een gecomprimeerd bestand (.zip), dat de Visual Studio 2015-oplossingsbestanden voor het voorbeeld bevat. Voor meer informatie raadpleegt u de sectie Dit voorbeeld uitvoeren in de betreffende onderwerpen.

Gemeenschappelijke elementen voor alle voorbeelden

De meeste voorbeelden hebben een overeenkomstige structuur en bevatten gemeenschappelijke methoden en resources, meestal bedoeld als de basisstructuur voor een web-API-programma in C#.

Veel van deze algemene elementen zijn ook aanwezig als u een nieuwe oplossing maakt die toegang krijgt tot de Dynamics 365-web-API. Zie Start een Dynamics 365 Web API-project in Visual Studio (C#) voor meer informatie.

Gebruikte bibliotheken en raamwerken

Deze C#-implementatie is afhankelijk van de volgende hulpcode voor HTTP-communicatie, toepassingsconfiguratie, verificatie, foutafhandeling en JSON-serialisatie.

Json.NET-bibliotheek

Omdat C# en de meeste andere beheerde talen niet standaard de JSON-gegevensindeling ondersteunen, is de beste benadering op dit moment om voor deze functionaliteit een bibliotheek te gebruiken. Zie voor meer informatie An Introduction to JavaScript Object Notation (JSON) in JavaScript and .NET. Json.NET is een populaire keuze voor .NET-projecten. Het biedt een robuust, krachtig, open-source (MIT-gelicentieerd) framework voor het serialiseren, converteren, parseren, queryen en formatteren van JSON-gegevens. Zie de Json.NET-documentatie voor meer informatie.

In de C#-voorbeelden wordt deze bibliotheek voornamelijk gebruikt om gegevens tussen .NET-objecten en HTTP-berichtteksten te serialiseren. Hoewel de bibliotheek diverse methoden biedt om deze taak uit te voeren, wordt in de voorbeelden gekozen voor een benadering waarbij individuele JObject-exemplaren worden gemaakt om entiteitsexemplaren uit Dynamics 365 (records) te vertegenwoordigen. Met de volgende code wordt bijvoorbeeld de variabele contact1 aangemaakt die een contact EntityType-exemplaar uit Dynamics 365 vertegenwoordigt. Vervolgens worden waarden geleverd voor een geselecteerde reeks eigenschappen voor dit type.

JObject contact1 = new JObject();
contact1.Add("firstname", "Peter");
contact1.Add("lastname", "Cambel");
contact1.Add("annualincome", 80000);
contact1["jobtitle"] = "Junior Developer";

Het gebruik van de notatie met accolades in de laatste instructie staat gelijk aan de methode Add (toevoegen). Deze instantiëring zou ook kunnen worden bereikt door middel van de statische methode Parse:

JObject contact1 = JObject.Parse(@"{firstname: 'Peter', lastname: 'Cambel', "
+ @"annualincome: 80000, jobtitle: 'Junior Developer'}");

Omdat JObject een algemeen JSON-type vertegenwoordigt, voorkomt het gebruik ervan veel controles op type tijdens runtime. De volgende instructie is bijvoorbeeld syntactisch geldig, maar kan mogelijk leiden tot runtime-fouten, omdat de contact EntityType niet een eigenschap age bevat.

contact1.Add("age", 37); //Possible error--no age property exists in contact!

Als de entiteitvariabele is geïnitialiseerd, kan deze vervolgens in een berichttekst worden verzonden, ondersteund door diverse System.Net.Http-klassen, zoals:

HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "contacts");
request.Content = new StringContent(contact1.ToString(), Encoding.UTF8, "application/json");
HttpResponseMessage response = await httpClient.SendAsync(request1);

U kunt ook JObject-exemplaren maken door entiteitsexemplaren te deserialiseren tijdens ophaalbewerkingen, zoals:

//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());

Afhandeling van responssucces en -fouten

In het algemeen wordt in de voorbeelden een rechtstreekse benadering gekozen voor verwerking van HTTP-responsen. Als de aanvraag slaagt, wordt informatie over de bewerking meestal uitgevoerd naar de console. Als de respons ook een JSON-nettolading of nuttige headers bevat, wordt deze informatie alleen verwerkt bij succes. En als tenslotte een Dynamics 365-entiteit werd gemaakt, wordt de entityUris-verzameling bijgewerkt met de URI voor die resource. De methode Methode DeleteRequiredRecords gebruikt deze verzameling om optioneel gegevens die in het voorbeeld zijn gemaakt van uw Dynamics 365-server te verwijderen.

Als de aanvraag mislukt, voert het programma een contextueel bericht uit over de mislukte werking en genereert vervolgens een aangepaste uitzondering van het type CrmHttpResponseException. De uitzonderingshandler voert meer informatie over de uitzondering uit en geeft dan de controle door aan een finally-blok dat de opschoonlogica bevat, eveneens weer met een aanroep van DeleteRequiredRecords. In de volgende code wordt deze benadering van foutafhandeling getoond voor een POST-aanvraag voor het aanmaken van een record.

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 is vergelijkbaar met een HTTP-statuscode 204, "Geen inhoud". Hier geeft deze statuscode aan dat de POST-aanvraag is geslaagd. Zie voor meer informatie Compose HTTP requests and handle errors.

Kenmerken en methoden

De architectuur van de meeste voorbeelden volgt hetzelfde patroon, met de volgende kenmerken:

  • Alle relevante C#-voorbeeldcode bevindt zich in het primaire bronbestand genaamd Program.cs, dat een enkele klasse bevat met dezelfde naam als het voorbeeldproject.

  • De voorbeeldklassen en de De hulpbibliotheek voor de Microsoft Dynamics 365-web-API (C#) gebruiken zijn opgenomen in de naamruimte Microsoft.Crm.Sdk.Samples.

  • De voorbeelden bevatten veel toelichting: samenvattingen worden gegeven op niveau van zowel klasse als methode en de meeste belangrijke individuele instructies zijn gekoppeld aan opmerkingen op dezelfde regel of in één regel. Aanvullende bestanden, zoals het toepassingsconfiguratiebestand App.config, bevatten ook vaak belangrijke opmerkingen.

  • De primaire voorbeeldklasse is meestal gestructureerd om de volgende algemene reeks methoden te bevatten: Hoofdmethode, Methode ConnectToCRM, Methode CreateRequiredRecords, Methode RunAsync, Methode DisplayException en Methode DeleteRequiredRecords.

Hoofdmethode

Per definitie begint deze methode de uitvoering van het voorbeeld. Het bevat alleen logica op hoog niveau voor de controlestroom en afhandeling van uitzonderingen, meestal met exact deze code:

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

Methode ConnectToCRM

Deze methode roept de hulpbibliotheken aan om het toepassingsconfiguratiebestand te lezen en maakt vervolgens verbinding met de opgegeven Dynamics 365-server. Het resultaat van deze stappen is de initialisatie van een klasse-eigenschap HttpClient, die in het gehele programma wordt gebruikt om webaanvragen te verzenden en responsen te ontvangen. Zie hoe de volgende eigenschappen zijn ingesteld voor dit object:

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

Voor meer informatie over op voorbeelden voor toepassingsconfiguratie en verificatie raadpleegt u De hulpbibliotheek voor de Microsoft Dynamics 365-web-API (C#) gebruiken.

Methode CreateRequiredRecords

Deze methode maakt en initialiseert entiteitsrecords die in het voorbeeld vereist zijn, maar alleen wanneer deze bewerkingen niet van primair belang zijn in het voorbeeld. Het Voorbeeld van eenvoudige Web API-bewerkingen (C#) bevat bijvoorbeeld deze methode niet omdat de het maken van records een primaire overweging in het voorbeeld is.

Methode RunAsync

Deze asynchrone methode bevat ofwel de relevante van broncode of, voor langere programma's, aanroepmethoden die de relevante voorbeeldcode groeperen. De code hierin wordt toegelicht via ingesloten opmerkingen en commentaar in de sectie Remarks van het betreffende voorbeeldonderwerp.

Methode DisplayException

Met deze hulpmethode wordt informatie over uitzonderingen, inclusief interne uitzonderingen, uitgevoerd naar de standaardconsole.

Methode DeleteRequiredRecords

Deze aanvullende methode verwijdert optioneel voorbeeldrecords en andere resources op de Dynamics 365-server die in het programma zijn aangemaakt, met name door de methode Methode CreateRequiredRecords. De methode vraagt de gebruiker deze bewerking te bevestigen en loopt vervolgens in herhalingen door de entityUris-verzameling en probeert alle elementen te verwijderen via een HTTP DELETE-bericht.

Zie ook

De web-API van Microsoft Dynamics 365 gebruiken
Web-API-voorbeelden
Web-API-voorbeelden (JavaScript op de client)
Voorbeeld van eenvoudige Web API-bewerkingen (C#)
Voorbeeld gegevens Web API-query (C#)
Voorbeeld van voorwaardelijke Web API-bewerkingen (C#)
Web API-functies en actievoorbeeld (C#)

Microsoft Dynamics 365

© 2017 Microsoft. Alle rechten voorbehouden. Auteursrecht