Avviare un progetto API Web di Dynamics 365 in Visual Studio (C#)

Articolo
04/18/2017

Data di pubblicazione: gennaio 2017

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

In questo argomento viene illustrato come creare un nuovo progetto in Microsoft Visual Studio che crea un'applicazione console che utilizza l'API Web di Dynamics 365. Illustra riferimenti e risorse di progetto comuni utilizzate dalla maggior parte delle applicazioni, inclusi esempi C# SDK, per implementare le soluzioni basate su API Web.

Prerequisiti

I seguenti prerequisiti sono necessari per creare l'applicazione console descritta in questa sezione.

È necessario che Microsoft Visual Studio 2015 sia installato nel computer di sviluppo. Qualsiasi edizione, incluso Visual Studio Express, dovrebbe essere sufficiente per lavorare con l'API Web di Dynamics 365. Per ulteriori informazioni su quali versioni di Microsoft Visual Studio sono supportate, vedere Visual Studio e .NET Framework.
Un client NuGet deve essere installato: l'utilità della riga di comando oppure l'estensione di Visual Studio. Per ulteriori informazioni, vedere Installing NuGet.
Una connessione Internet è necessaria per scaricare il pacchetto NuGet che contiene la libreria helper API Web di Dynamics 365 e altri pacchetti dipendenti.
Facoltativamente, scaricare Microsoft Dynamics 365 SDKqui. Sebbene Microsoft Dynamics 365 SDK non sia necessario per creare o eseguire tali esempi API Web, la maggior parte degli sviluppatori Dynamics 365 vorrà installarlo perché contiene un set avanzato di risorse aggiuntive e l'SDK è necessario per accedere ad altre interfacce Dynamics 365.

Creare un progetto

La procedura seguente illustra come creare un progetto di applicazione console nel linguaggio C# che utilizza Microsoft .NET Framework. Per ulteriori informazioni sulle versioni supportate di .NET Framework, vedere Estensioni supportate per Microsoft Dynamics 365.

Nuovo progetto

In Microsoft Visual Studio, fare clic su Nuovo progetto. La finestra Nuovo progetto viene visualizzata.
Nel riquadro di spostamento sinistro, in Modelli selezionare Visual C#.
Sopra l'elenco di modelli disponibili, selezionare .NET Framework 4.5.2.
Nell'elenco dei modelli, selezionare Applicazione console. (Alternatamente scegliere il tipo di progetto adatto alla soluzione in uso.) Tutti gli esempi C# API Web sono applicazioni console.
Nelle caselle di testo nella parte inferiore del modulo fornire il nome e il percorso per il progetto e quindi selezionare OK. Per questo argomento, è stato usato il nome di soluzione "StartWebAPI-CS". I file iniziali della soluzione verranno generati e la soluzione caricata in Microsoft Visual Studio.
Nel menu Progetto, aprire il modulo delle proprietà del progetto e verificare che il framework di destinazione sia impostato su .NET Framework 4.5.2.

Aggiungere tutte le risorse necessarie al progetto

Le procedure seguenti illustrano come aggiungere tutti i riferimenti e i pacchetti gestiti necessari al progetto. Ricordare che questo è un set di base di risorse necessarie alla maggior parte delle applicazioni di codice gestito per richiamare operazioni API Web.

Aggiungere il pacchetto NuGet della libreria helper

La libreria helper API Web di Dynamics 365 SDK contiene le classi per supportare operazioni supplementari, ad esempio la configurazione dell'applicazione, l'autenticazione del server Dynamics 365, la gestione delle eccezioni e la comunicazione Web. Per ulteriori informazioni, vedere Utilizzare la libreria helper API Web di Microsoft Dynamics 365 (C#). L'utilizzo delle classi è facoltativo, ma vengono usate in modo considerevole negli esempi API Web. La libreria helper API Web di Dynamics 365 SDK viene distribuita in forma di codice sorgente come pacchetto NuGet. Gli aggiornamenti futuri verranno distribuiti come aggiornamenti del pacchetto NuGet.

Se si è installata l'utilità della riga di comando NuGet o si utilizza la Console di Gestione pacchetti in Visual Studio:

Eseguire il comando seguente per installare il pacchetto della libreria helper.

Install-Package Microsoft.CrmSdk.WebApi.Samples.HelperCode
Diversi messaggi vengono visualizzati riguardo all'elaborazione dei pacchetti di dipendenza. Se viene visualizzata una finestra Accettazione della licenza, leggere le condizioni di licenza e quindi fare clic su Accetto.
Andare direttamente al passaggio 6 seguente per confermare l'installazione del pacchetto della libreria helper.

Se si è installata l'estensione NuGet Package Manager:

Dal menu Progetto, selezionare Gestisci pacchetti NuGet. Viene visualizzata la scheda Gestione pacchetti NuGet.
Nell'angolo superiore destro, impostare l'elenco a discesa Origine pacchetto su Nuget.org.
Nell'angolo superiore sinistro, fare clic su Sfoglia e immettere "Dynamics 365 HelperCode" nella casella di ricerca, quindi premere INVIO.
Fare clic su Installa. Fare clic su OK nella finestra di dialogo Anteprima visualizzata.
La finestra Accettazione della licenza viene visualizzata. Verificare le condizioni di licenza e quindi fare clic su Accetto.
Passare alla finestra Esplora soluzioni. Verificare che una nuova cartella di soluzione denominata Web API Helper Code è stata aggiunta.

Il pacchetto della libreria helper API Web di Dynamics 365 SDK, Microsoft.CrmSdk.WebApi.Samples.HelperCode, dipende dai seguenti altri pacchetti, che vengono automaticamente scaricati e installati insieme al pacchetto della libreria helper:

Newtonsoft.Json: contiene Json.NET, un diffuso framework JSON con licenza MIT per .NET.
Microsoft.IdentityModel.Clients.ActiveDirectory: contiene i file binari per la Active Directory Authentication Library (ADAL), che fornisce funzionalità di autenticazione per i client .NET.

Avviso

Il pacchetto della libreria helper API Web di Dynamics 365 SDK è stato creato in base a versioni specifiche di questi altri due pacchetti di supporto. Per questo motivo, è consigliabile aggiornare direttamente solo il pacchetto NuGet della libreria helper. Questa operazione aggiornerà i pacchetti di supporto adeguati se necessario. Se aggiornate separatamente uno dei pacchetti di supporto, una versione più recente del pacchetto potrebbe essere incompatibile con la libreria helper.

Verificare i riferimenti assembly necessari

In Esplora soluzioni, espandere il nodo Riferimenti.
Verificare che i riferimenti seguenti sono stati aggiunti al progetto.
Se si dispone di funzionalità aggiuntive utilizzate regolarmente nelle applicazioni, è possibile aggiungere a questo punto i riferimenti associati agli assembly necessari. Per ulteriori informazioni, vedere Procedura: aggiungere o rimuovere riferimenti utilizzando la finestra di dialogo Aggiungi riferimento.

Poiché l'API Web di Dynamics 365 è basata sui principi REST, non richiede di accedere agli assembly sul lato client. Tuttavia, altre API supportate da Microsoft Dynamics 365 richiedono tale accesso;pPer ulteriori informazioni, vedere Assembly incluse in SDK di Microsoft Dynamics 365.

Aggiungere istruzioni using tipiche

In Esplora soluzioni, aprire Program.cs per la modifica.
All'inizio del file, aggiungere le istruzioni using seguenti, che fanno riferimento agli spazi dei nomi comunemente utilizzati nelle soluzioni basate su API Web di Dynamics 365.
```
using Microsoft.Crm.Sdk.Samples.HelperCode;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
```
Se sono stati aggiunti assembly o riferimenti regolarmente utilizzati nelle sezioni precedenti, è inoltre possibile aggiungere le istruzioni using corrispondenti per queste risorse.
Salvare il file.

Aggiungere codice di connessione

In questa sezione viene illustrato come aggiungere un set di base di impostazioni e istruzioni per eseguire queste operazioni. Per ulteriori informazioni sul codice comune utilizzato, vedere Utilizzare la libreria helper API Web di Microsoft Dynamics 365 (C#).

Modificare il file di configurazione dell'applicazione

In Esplora soluzioni, aprire il file App.config per la modifica. Aggiungere le seguenti due sezioni, dopo la sezione <startup> esistente, quindi salvare il file.

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

Quando si sviluppa o si distribuisce una soluzione, la connessione e i valori di registrazione dell'applicazione effettivi devono essere sostituiti ai valori segnaposto di esempio. Per ulteriori informazioni, vedere Codice helper API Web: classi di configurazione.

Aggiungere codice per chiamare la libreria helper

Modificare il file Program.cs.
Aggiungere la proprietà seguente alla classe Program. Questa proprietà verrà inizializzata dopo la connessione a un server Dynamics 365.

private HttpClient httpClient;

Nel metodo Main aggiungere le istruzioni seguenti.

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

Dopo aggiungere il metodo ConnectToCRM, che utilizza le classi Configuration e Authentication della libreria helper. Il codice seguente illustra l'assegnazione dei valori alle proprietà HttpClient in modo da poter accedere in modo corretto alla versione finale dell'API Web di Dynamics 365.

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

Aggiungere il codice di gestione degli errori

Le modifiche seguenti aggiungono codice per rilevare e segnalare le eccezioni, inclusi gli errori API Web, alla console. Se l'ambiente di destinazione è differente, modificare il codice di gestione delle eccezioni in modo appropriato per tale ambiente.

In Main, aggiungere l'istruzione seguente al blocco catch.

DisplayException(ex);

Aggiungere il metodo corrispondente alla classe Program.

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

Salvare tutti i file della soluzione.

Passaggi successivi

A questo punto la soluzione può essere compilata senza errori. Se si modifica il file di configurazione dell'applicazione per fornire valori per Server Microsoft Dynamics 365, il programma deve anche connettersi correttamente a tale server. La soluzione rappresenta una struttura di base pronta all'accettazione di codice personalizzato, incluse le chiamate all'API Web di Dynamics 365.

Suggerimento

Prima di uscire da questa argomento, è possibile salvare il progetto come modello di progetto. È possibile riutilizzare il modello per progetti di formazione futuri per risparmiare tempo e lavoro nella configurazione di nuovi progetti. A tale scopo, mentre il progetto è aperto in Microsoft Visual Studio, nel menu File scegliere Esporta modello. Seguire le istruzioni dell'Esportazione guidata modelli per creare il modello.

Vedere anche

Informazioni generali sull'API Web Microsoft Dynamics 365 (C#)
Utilizzare la libreria helper API Web di Microsoft Dynamics 365 (C#)
Eseguire operazioni tramite l'API Web

Microsoft Dynamics 365

Condividi tramite