在 Visual Studio (C#) 中啟動 Dynamics 365 Web API 專案

文章
04/18/2017

發佈日期： 2017年1月

適用對象： Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

本主題示範如何在 Dynamics 365 中建立新專案，使用Microsoft Visual Studio Web API 建置主控台應用程式。當中說明大部分應用程式常用的參考和專案資源，包括 SDK C# 範例，用來實作 Web API 解決方案。

先決條件

下列先決條件必須滿足，才能建立本節中所述的主控台應用程式。

安裝在您的開發電腦上的 Microsoft Visual Studio 2015。包括 Visual Studio Express 在內的所有版本都應足以搭配 Dynamics 365 Web API 使用。如需支援的 Microsoft Visual Studio 版本的詳細資訊，請參閱 Visual Studio 和 .NET Framework。
必須安裝 NuGet 用戶端：命令列公用程式或 Visual Studio 擴充功能。如需詳細資訊，請參閱安裝 NuGet。
需要有網際網路連線才能下載 NuGet 套件，當中包含 Dynamics 365 Web API Helper 程式庫和其他相依套件。
或者，您也可以下載 Microsoft Dynamics 365 SDK在這裡。雖然不需要 Microsoft Dynamics 365 SDK 也能建置或執行這些 Web API 範例，但是大部分 Dynamics 365 開發人員會希望安裝它，因為它包含豐富的補充資源，而且需要有 SDK 才能存取其他 Dynamics 365 介面。

建立專案

下列程序將示範如何在使用 Microsoft .NET Framework 的 C# 中建立主控台應用程式專案。如需關於支援的 .NET Framework 版本的詳細資訊，請參閱Microsoft Dynamics 365 支援的擴充功能。

新專案

在 Microsoft Visual Studio 中按一下 [新增專案]。 [新增專案] 對話方塊會顯示。
在左側導覽窗格中，於 [範本] 下選取 [Visual C#]。
在可用範本清單上方，選取 [.NET Framework 4.5.2]。
在範本清單中，選取 [主控台應用程式]。 (或者，選擇適合您解決方案的專案類型。) 所有 Web API C# 範例都是主控台應用程式。
在接近表單底部的文字方塊中，提供專案名稱和位置，然後選取 [確定]。 (本主題會使用解決方案名稱 "StartWebAPI-CS"。) 初始解決方案檔案將會產生，且解決方案會載入 Microsoft Visual Studio 中。
在 [專案] 功能表底下開啟專案的屬性表單，並確認目標 Framework 設定為 [.NET Framework 4.5.2]。

新增所有必要的資源至您的專案

下列程序將說明如何新增所有必要的受管理參考和套件至您的專案。請將此視為一組基本資源，大部分受管理的程式碼應用程式都會需要這組資源來叫用 Web API 作業。

新增 Helper 程式庫 NuGet 套件

Dynamics 365 SDK Web API Helper 程式庫包含可協助補充作業的類別，例如應用程式設定、Dynamics 365 伺服器驗證、例外狀況處理，以及 Web 通訊。如需詳細資訊，請參閱使用 Microsoft Dynamics 365 Web API Helper 程式庫 (C#)。使用這些類別是選擇性的，雖然它們在 Web API 範例中大量使用。 Dynamics 365 SDK Web API Helper 程式庫會在原始程式碼表單中發佈為 NuGet 套件。未來更新將會發佈為 NuGet 套件更新。

如果您已安裝 NuGet 命令列公用程式，或使用 Visual Studio 中的 Package Manager Console：

發出下列命令來安裝 Helper 程式庫套件。

Install-Package Microsoft.CrmSdk.WebApi.Samples.HelperCode
會顯示數個有關處理相依性套件的訊息。如果顯示 [接受授權] 對話方塊，請閱讀授權條款，然後按一下 [接受]。
跳到以下步驟 6，確認安裝 Helper 程式庫套件。

如果您已安裝 NuGet 套件管理員擴充功能：

從 [專案] 功能表選取 [管理 NuGet 套件]。 [NuGet 套件管理員] 索引標籤會顯示。
在右上角將 [套件] 來源下拉式清單設定為 [Nuget.org]。
在左上角按一下 [瀏覽]，然後在搜尋方塊中輸入 "Dynamics 365 HelperCode"，再按 Enter。
按一下 [安裝]。如果 [預覽] 對話方塊顯示，按一下 [確定]。
[接受授權] 對話方塊會顯示。檢閱授權條款，然後按一下 [我接受]。
瀏覽至 [方案總管] 視窗。確認已新增名為 [Web API Helper Code] 的新解決方案資料夾。

Dynamics 365 SDK Web API Helper 程式庫套件 Microsoft.CrmSdk.WebApi.Samples.HelperCode 會根據下列其他套件，這些會隨 Helper 程式庫套件自動下載和安裝：

Newtonsoft.Json – 包含 Json.NET，適用於 .NET 的常用 MIT 授權 JSON Framework。
Microsoft.IdentityModel.Clients.ActiveDirectory – 包含 Active Directory Authentication Library (ADAL) 的二進位檔，會為 .NET 用戶端提供驗證功能。

警告

Dynamics 365 SDK Web API Helper 程式庫套件是依據其他兩個支援的特定版本套件建立。因此，您應該僅直接更新 Helper 程式庫 NuGet 套件。此作業將會在需要時更新適當的支援套件。如果您另外更新其中一個支援的套件，該套件的較新版本可能與 Helper 程式庫不相容。

驗證必要的組件參考

在 [方案總管] 中展開 [參考] 節點。
確認以下參考已新增至專案。
如果您的應用程式中有日常使用的其他功能，您現在可以新增必要組件的相關參考。如需詳細資訊，請參閱如何：使用 [加入參考] 對話方塊新增或移除參考。

因為 Dynamics 365 Web API 是以 REST 原則為基礎，所以不需要用戶端組件也能存取。不過，Microsoft Dynamics 365 支援的其他 API 仍需要這些組件，如需詳細資訊，請參閱 Microsoft Dynamics 365 SDK 中包含的組件。

新增一般 using 陳述式

在 [方案總管] 中，開啟 [Program.cs] 進行編輯。

在檔案頂端，新增下列 using 陳述式，其參考 Dynamics 365 Web API 解決方案中常用的命名空間。

using Microsoft.Crm.Sdk.Samples.HelperCode;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System.Net.Http;
using System.Net.Http.Headers;

如果您已在前面各節中新增常用的組件或參考，您可能也會想新增這些資源的對應 using 陳述式。
儲存檔案。

新增連接程式碼

本節說明如何新增一組基本設定和指示來執行這些作業。如需常用程式碼的詳細資訊，請參閱使用 Microsoft Dynamics 365 Web API Helper 程式庫 (C#)。

編輯應用程式設定檔

在 [方案總管] 中，開啟 [App.config] 檔案進行編輯。新增下列兩個區段到其中，在現有的 <startup> 區段後面，然後儲存檔案。

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

開發或部署解決方案時，必須使用實際連接和應用程式註冊值替換掉範例預留位置值。如需詳細資訊，請參閱Web API Helper 程式碼︰組態類別。

新增程式碼來呼叫 Helper 程式庫

編輯 Program.cs 檔案。
將下列屬性新增至 [程式] 類別。此屬性會在成功連線至 Dynamics 365 伺服器之後初始化。

private HttpClient httpClient;

在 Main 方法中，新增下列陳述式。

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

接著新增 ConnectToCRM 方法，它會使用 Helper 程式庫 Configuration 和 Authentication 類別。下列程式碼示範將值指派至 HttpClient 屬性，如此您就能成功存取發行的 Dynamics 365 Web API 版本。

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

新增錯誤處理程式碼

下列變更會新增程式碼來攔截和報告例外狀況至主控台，包括 Web API 錯誤。如果您是以不同的環境為目標，可適當修改例外狀況處理程式碼以用於該環境。

在 Main 中，新增下列陳述式至 catch 區塊。

DisplayException(ex);

新增對應的方法至 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;
    }
}

儲存解決方案中的所有檔案。

後續步驟

此時，解決方案可以正確建置無誤。若您編輯應用程式設定檔來為 Microsoft Dynamics 365 Server 提供值，程式應該也能成功連線至該伺服器。解決方案代表基礎架構，準備好接受自訂程式碼，包括呼叫 Dynamics 365 Web API。

提示

結束本主題之前，請考慮將您的專案儲存為專案範本。之後您就可以重複使用該範本學習專案，並且能夠在設定新專案時節省一些時間和精力。若要執行這項操作，請在專案開啟時，於 Microsoft Visual Studio 的 [檔案] 功能表中選取 [匯出範本]。按照匯出範本精靈的指示建立範本。

另請參閱

開始使用 Microsoft Dynamics 365 Web API (C#)
使用 Microsoft Dynamics 365 Web API Helper 程式庫 (C#)
使用 Web API 執行作業

Microsoft Dynamics 365

分享方式：