Esempi di API Web (C#)

  • Articolo

 

Data di pubblicazione: gennaio 2017

Si applica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Questo argomento include informazioni sugli esempi API Web implementati con C#. Anche se ogni esempio si incentra su un aspetto diverso dell'API Web di Microsoft Dynamics 365, tutti condividono caratteristiche e struttura simili.

Nota

Questo approccio di implementazione utilizza la creazione di oggetti di basso livello e chiamate esplicite di messaggi HTTP. Questo approccio consente il controllo e la dimostrazione delle proprietà degli oggetti di basso livello che controllano il comportamento dell'API Web. L'approccio favorisce la comprensione dei meccanismi interni ma non rappresenta necessariamente il modo per ottenere la migliore esperienza di produttività di sviluppo.

Invece, le librerie di livello superiore, ad esempio la libreria OData, sottraggono tramite astrazione molta della logica client di basso livello. Il modello OData T4 può facoltativamente essere utilizzato insieme alla libreria OData per generare automaticamente le classi entità client.

In questo argomento

Prerequisiti

Elenco di esempi API Web (C#)

Come scaricare ed eseguire gli esempi

Elementi comuni in ogni esempio

Prerequisiti

Quanto segue viene richiesto per creare ed eseguire gli esempi in C# dell'API Web di Dynamics 365:

  • Una versione di Microsoft Visual Studio 2015 o successiva. Una versione gratuita, Visual Studio Community, è disponibile per il download qui.

  • Una connessione Internet per scaricare e aggiornare i pacchetti NuGet di riferimento.

  • Accesso a Dynamics a Dynamics 365 Online o locale (o versione successiva). Per tutti i tipi di installazione di Dynamics 365, è richiesto un account utente con privilegi per eseguire operazioni CRUD.

  • Per eseguire gli esempi con Dynamics 365 (online), è necessario registrare la tua applicazione con Azure Active Directory per ottenere un ID client e un URL di reindirizzamento. Per ulteriori informazioni, vedere Procedura dettagliata: registrare un'app Dynamics 365 con Azure Active Directory.

Elenco di esempi API Web (C#)

Nella tabella seguente sono elencati gli esempi implementati in C#. Ogni esempio viene descritto in modo più generale in un argomento corrispondente relativo al gruppo di esempi incentrato sui messaggi di richiesta e di risposta HTTP, come descritto minutamente nell'argomento Esempi di API Web.

Esempio

Gruppo di esempi

Descrizione

Esempio di operazioni di base dell'API Web (C#)

Esempio di operazioni di base dell'API Web

Dimostra come creare, recuperare, aggiornare, eliminare, associare e annullare l'associazione di record di entità Dynamics 365.

Esempio di dati di query API Web (C#)

Esempio di dati di query API Web

Dimostra come utilizzare la sintassi e funzioni di query OData v4 nonché le funzioni di query di Microsoft Dynamics 365. Include gli esempi di utilizzo con query predefinite e di uso di FetchXML per eseguire query.

Esempio operazioni condizionali dell'API Web (C#)

Esempio operazioni condizionali dell'API Web

Dimostra come eseguire operazioni condizionali specificate con i criteri ETag.

Esempio di azioni e funzioni API Web (C#)

Esempio di azioni e funzioni API Web

Dimostra come utilizzare le funzioni e le azioni associate e non associate, incluse le azioni personalizzate.

Come scaricare ed eseguire gli esempi

Il codice sorgente per ogni esempio è disponibile in MSDN Code Gallery. Il collegamento per scaricare ogni esempio è incluso nell'argomento dell'esempio. Il download dell'esempio è un file zip compresso, che contiene i file della soluzione di Visual Studio 2015 per l'esempio. Per ulteriori informazioni, vedere la sezione Eseguire l'esempio nell'argomento di ciascun esempio.

Elementi comuni in ogni esempio

La maggior parte degli esempi ha una struttura simile e contiene metodi e risorse comuni, in genere per fornire l'infrastruttura di base per un programma C# API Web.

Molti di questi elementi comuni sono inoltre presenti quando si crea una nuova soluzione che dovrà accedere all'API Web di Dynamics 365. Per ulteriori informazioni, vedere Avviare un progetto API Web di Dynamics 365 in Visual Studio (C#).

Librerie e framework utilizzati

Questa implementazione C# dipende dal codice helper seguente per la comunicazione HTTP, la configurazione dell'applicazione, l'autenticazione, la gestione degli errori e la serializzazione JSON.

Libreria Json.NET

Poiché C# e la maggior parte degli altri linguaggi gestiti non supportano in modo nativo il formato dati JSON, l'approccio migliore corrente è utilizzare una libreria per questa funzionalità. Per ulteriori informazioni, vedere An Introduction to JavaScript Object Notation (JSON) in JavaScript and .NET. Json.NET è una scelta comune per i progetti .NET. Fornisce un framework efficace, affidabile, open-source (con licenza MIT) per serializzare, convertire, analizzare, effettuare query e formattare dati JSON. Per ulteriori informazioni, vedere la documentazione di Json.NET.

Negli esempi C#, questa libreria principalmente viene utilizzata per serializzare i dati tra gli oggetti .NET e i corpi di messaggio HTTP. Sebbene la libreria fornisca diversi metodi per svolgere questa attività, l'approccio utilizzato dagli esempi è creare le singole istanze JObject per rappresentare le istanze (i record) di entità di Dynamics 365. Ad esempio, il codice seguente crea la variabile contact1 che rappresenta un'istanza contact EntityType di Dynamics 365, quindi fornisce i valori per un determinato set di proprietà di questo tipo.

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

L'uso della notazione in parentesi nell'ultima istruzione equivale al metodo Add. Questa creazione di istanza potrebbe essere ottenuta anche tramite l'uso del metodo statico Parse:

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

Poiché JObject rappresenta un tipo JSON generale, il relativo utilizzo preclude molto controllo dei tipi al runtime. Ad esempio, mentre la seguente istruzione sintatticamente è valida, potrà potenzialmente condurre a errori di runtime perché contact EntityType non contiene una proprietà age.

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

Al termine dell'inizializzazione della variabile dell'entità, potrà quindi essere inviata nel corpo di un messaggio, con l'aiuto di diverse classi System.Net.Http, ad esempio:

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

È inoltre possibile creare istanze JObject deserializzando le istanze di entità durante le operazioni di recupero, ad esempio:

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

Esito positivo della risposta e gestione degli errori

In generale gli esempi adottano un approccio diretto all'elaborazione delle risposte HTTP. Se la richiesta ha esito positivo, le informazioni sull'operazione vengono riportate in output sulla console. Se la risposta include anche un payload JSON o intestazioni utili, tali informazioni vengono elaborate solo in caso di esito positivo. Infine, se un'entità di Dynamics 365 è stata creata, la raccolta entityUris viene aggiornata con l'URI di tale risorsa. Il metodo Metodo DeleteRequiredRecords utilizza la raccolta per eliminare facoltativamente i dati creati dall'esempio dal server Dynamics 365.

Se la richiesta non è riuscita, il programma produce un messaggio contestuale sull'operazione non riuscita e quindi genera un'eccezione personalizzata di tipo CrmHttpResponseException. Il gestore eccezioni produce ulteriori informazioni sull'eccezione e quindi il controllo passa a un blocco finally che include una logica di cleanup, di nuovo includendo una chiamata a DeleteRequiredRecords. Il codice seguente illustra questo approccio di gestione degli errori in una richiesta POST per creare un 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 è equivalente a un codice di stato HTTP 204, "Nessun contenuto". Qui, il codice di stato indica che la richiesta POST è riuscita. Per ulteriori informazioni, vedere Comporre richieste HTTP e gestire gli errori.

Caratteristiche e metodi

La maggior parte degli esempi hanno lo stesso schema architetturale generale, con le caratteristiche seguenti:

  • Tutto il codice di codice C# pertinente è contenuto nel file di origine principale denominato Program.cs, contenente una singola classe con lo stesso nome del progetto di esempio.

  • Le classi di esempio, nonché Utilizzare la libreria helper API Web di Microsoft Dynamics 365 (C#), sono contenute nello spazio dei nomi Microsoft.Crm.Sdk.Samples.

  • Gli esempi sono ben commentati: riepiloghi sono disponibili a livello di metodo e di classe e alla maggior parte delle singole istruzioni chiave sono associati commenti sulla stessa o su una sola riga. Anche i file supplementari, come il file di configurazione dell'applicazione App.config, contengono commenti importanti.

  • La classe di esempio primaria è strutturata in genere per includere il seguente set di metodi comuni: Metodo Main, Metodo ConnectToCRM, Metodo CreateRequiredRecords, Metodo RunAsync, Metodo DisplayException e Metodo DeleteRequiredRecords.

Metodo Main

Per definizione, questo metodo inizia l'esecuzione dell'esempio. Contiene solo flusso di controllo di alto livello e logica di gestione delle eccezioni, spesso esattamente il codice seguente:

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

Metodo ConnectToCRM

Questo metodo chiama le librerie helper per leggere il file di configurazione dell'applicazione e quindi stabilisce una connessione al server specificato di Dynamics 365. Il risultato della procedura è l'inizializzazione di una proprietà della classe HttpClient utilizzata in tutto il programma per inviare richieste Web e ricevere le risposte. Le proprietà seguenti vengono impostate su questo oggetto:

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

Per ulteriori informazioni sulla configurazione e l'autenticazione dell'applicazione di esempio, vedere Utilizzare la libreria helper API Web di Microsoft Dynamics 365 (C#).

Metodo CreateRequiredRecords

Questo metodo crea e inizializza i record di entità richiesti dall'esempio, solo quando queste operazioni non siano di interesse primario nell'esempio. Ad esempio, Esempio di operazioni di base dell'API Web (C#) non contiene questo metodo perché la creazione di record è una considerazione principale dell'esempio.

Metodo RunAsync

Questo metodo asincrono contiene il codice sorgente pertinente oppure, per i programmi più lunghi, chiama i metodi che raggruppano il codice di esempio pertinente. Il codice contenuto è spiegato da commenti incorporati e commenti situati nella sezione Note di ogni argomento dell'esempio corrispondente.

Metodo DisplayException

Questo metodo helper visualizza le informazioni delle eccezioni, incluse le eccezioni interne, sulla console standard.

Metodo DeleteRequiredRecords

Questo metodo di confronto elimina facoltativamente i record dell'esempio e altre risorse del server Dynamics 365 create nel programma e particolarmente tramite il metodo Metodo CreateRequiredRecords. Chiede all'utente di verificare questa operazione, quindi esegue l'iterazione nella raccolta entityUris e tenta di eliminare ogni elemento con un messaggio HTTP DELETE.

Vedere anche

Utilizzare l'API Web di Microsoft Dynamics 365
Esempi di API Web
Esempi di API Web (JavaScript lato client)
Esempio di operazioni di base dell'API Web (C#)
Esempio di dati di query API Web (C#)
Esempio operazioni condizionali dell'API Web (C#)
Esempio di azioni e funzioni API Web (C#)

Microsoft Dynamics 365

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright