共用方式為

Web API 範例 (C#)

 

發行︰ 2017年1月

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

此主題提供以 C# 實作的 Web API 範例的資訊。 雖然每個範例著重於不同的 Microsoft Dynamics 365 Web API 層面，但是有類似的共同特性和結構。

注意

此實作方法使用低階物件建立和明確的 HTTP 訊息呼叫。 此方法可控制和示範低階物件屬性，用來控制 Web API 的行為。 其目的在於幫助您了解內部運作，但不一定代表能提供最佳開發人員生產力體驗。

相反地，較高階的程式庫如 OData 程式庫多所採用此低階用戶端邏輯。OData T4 範本可選擇性地搭配 OData 程式庫用來自動產生用戶端實體類別。

本主題內容

先決條件

Web API 範例清單 (C#)

如何下載和執行範例

每個範例中通用的元素

先決條件

下列是建立和執行 Dynamics 365 Web API C# 範例所需：

  • Microsoft Visual Studio 2015 或更新版本。 免費的 Visual Studio 版本可供下載，在此處。

  • 網際網路連線，用於下載和更新參考的 NuGet 套件。

  • 存取 Dynamics Dynamics 365 線上或內部部署 (或更新版本) 的權限。 對於所有 Dynamics 365 安裝類型，需要具有執行 CRUD 作業的權限的使用者帳戶。

  • 若要對 Dynamics 365 (線上) 執行範例，您必須在 Azure Active Directory 註冊您的應用程式，以取得用戶端識別碼及重新導向 URL。 如需詳細資訊，請參閱逐步解說：向 Azure Active Directory 註冊 Dynamics 365 應用程式。

Web API 範例清單 (C#)

下表列出以 C# 實作的範例。 每個範例都會在對應的範例群組主題中更廣泛說明，著重於 HTTP 要求和回應訊息，如主題 Web API 範例中所詳述。

範例

範例群組

描述

Web API 基本作業範例 (C#)

Web API 基本作業範例

示範如何建立、擷取、更新、刪除、建立關聯以及取消關聯 Dynamics 365 實體記錄。

Web API 查詢資料範例 (C#)

Web API 查詢資料範例

示範如何使用 OData v4 查詢語法和函數，以及 Microsoft Dynamics 365 查詢函數。 包含使用預先定義的查詢和使用 FetchXML 執行查詢的範例。

Web API 條件式作業範例 (C#)

Web API 條件式作業範例

示範如何執行您使用 ETag 準則指定的條件式作業。

Web API 函數和動作範例 (C#)

Web API 函數和動作範例

示範如何使用已繫結和未繫結的函數及動作，包括自訂動作。

如何下載和執行範例

每個範例的原始程式碼都可在 MSDN Code Gallery 取得。 下載每個範例的連結包含在範例主題中。 範例下載是壓縮的 .zip 檔，其中包含範例的 Visual Studio 2015 解決方案檔案。 如需詳細資訊，請參閱每個範例主題中的＜執行此範例＞區段。

每個範例中通用的元素

大部分範例具有類似的結構，且包含通用的方法和資源，通常是提供 Web API C# 程式的基本基礎結構。

這些通用的元素中，有許多也會在建立將存取 Dynamics 365 Web API 的新解決方案時出現。 如需詳細資訊，請參閱在 Visual Studio (C#) 中啟動 Dynamics 365 Web API 專案。

使用的程式庫和架構

此 C# 實作取決於下列 Helper 程式碼進行 HTTP 通訊、應用程式設定、驗證、錯誤處理及 JSON 序列化。

Json.NET 程式庫

因為 C# 和大部分其他受管理語言原本不支援 JSON 資料格式，所以目前最好的方法是使用程式庫提供此功能。 如需詳細資訊，請參閱 JavaScript 和 .NET 中的 JavaScript 物件標記法 (JSON) 簡介。 Json.NET 是普遍選擇的 .NET 專案。 它提供強大、高效、開放原始碼 (經 MIT 授權) 架構，用於序列化、轉換、剖析、查詢及格式化 JSON 資料。 如需詳細資訊，請參閱 Json.NET 文件。

在 C# 範例中，此程式庫主要用來在 .NET 物件和 HTTP 訊息本文之間序列化資料。 雖然程式庫提供數種方法來完成此工作，但是範例所使用的方法是建立個別 JObject 執行個體，來代表 Dynamics 365 實體執行個體 (記錄)。 例如，下列程式碼建立變數 contact1，代表 Dynamics 365 contact EntityType 執行個體，然後對這類型的一組選出的屬性提供值。

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

最後陳述式中使用方括號標記法相當於 Add 方法。 此具現化也可以透過使用 Parse 靜態方法達成：

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

因為 JObject 代表一般 JSON 類型，使用它可防止過多執行階段類型檢查。 例如，下列陳述式語法上有效，但可能會導致執行階段錯誤，因為 contact EntityType 未包含 age 屬性。

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

初始化實體變數後，它就可以在訊息本文中傳送，透過數個 System.Net.Http 類別的協助，例如：

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

您也可以藉由還原序列化執行個體來建立 JObject 執行個體，在擷取作業期間，例如：

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

回應成功和錯誤處理

一般來說，範例會採取直接的方法來處理 HTTP 回應。 如果要求成功，有關作業的資訊通常會輸出到主控台。 如果回應也帶有 JSON 承載或有用的標頭，此資訊只會在成功時處理。 最後，如果 Dynamics 365 實體已建立，entityUris 集合就會透過該資源的 URI 更新。DeleteRequiredRecords 方法 方法會使用此集合選擇性地刪除範例建立的資料，從您的 Dynamics 365 伺服器。

若要求失敗，程式會輸出有關作業失敗的關聯訊息，然後擲回類型 CrmHttpResponseException 的自訂例外狀況。 例外狀況處理常式會輸出更多關於例外狀況的資訊，然後控制項會傳遞至 finally 區塊，當中包括清除邏輯，且同樣包含 DeleteRequiredRecords 的呼叫。 下列程式碼示範此錯誤處理方法，針對建立記錄的 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 相當於 HTTP 狀態碼 204「無內容」。 在這裡，此狀態碼表示 POST 要求成功。 如需詳細資訊，請參閱編寫 HTTP 要求和處理錯誤。

特性和方法

大部分範例都有相同的一般架構模式，且包含下列特性：

  • 所有相關的 C# 範例程式碼都包含在名為 Program.cs 的主要來源檔案中，當中包含單一類別，其名稱與範例專案相同。

  • 範例類別，以及 使用 Microsoft Dynamics 365 Web API Helper 程式庫 (C#)都包含在命名空間 Microsoft.Crm.Sdk.Samples 中。

  • 範例可自由加上註解：摘要會在類別和方法層級提供，大部分重要的個別陳述式都有關聯的同行或單行註解。 補充檔案，例如應用程式設定檔 App.config，也經常包含重要的註解。

  • 主要範例類別通常會建構為包含下列常用的一組方法：主要方法、ConnectToCRM 方法、CreateRequiredRecords 方法、RunAsync 方法、DisplayException 方法 和 DeleteRequiredRecords 方法。

主要方法

根據定義，此方法會開始執行範例。 它只包含高接控制流程和例外狀況處理邏輯，經常就是下列程式碼：

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

此方法會呼叫 Helper 程式庫讀取應用程式設定檔，然後建立與指定的 Dynamics 365 伺服器的連線。 這些步驟的結果是初始化 HttpClient 類別屬性，在整個程式中用來傳送 Web 要求和接收回應。 請注意，下列屬性會在此物件上設定：

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

如需範例應用程式設定和驗證的詳細資訊，請參閱使用 Microsoft Dynamics 365 Web API Helper 程式庫 (C#)。

CreateRequiredRecords 方法

此方法會建立和初始化範例所需的實體記錄，只有在這些作業不屬於範例中的重點時。 例如，Web API 基本作業範例 (C#) 不包含此方法，因為建立記錄是範例的主要考量。

RunAsync 方法

此非同步方式不是包含相關原始程式碼 (用於較長的程式)，就是呼叫方法將相關範例程式碼設為群組。 包含的程式碼會以內嵌的註解和評論說明，位於每一個對應範例主題的＜備註＞區段。

DisplayException 方法

此 Helper 方法會在標準主控台顯示例外狀況資訊，包括內部例外狀況。

DeleteRequiredRecords 方法

此伴隨方法會選擇性地刪除程式中建立的範例記錄和其他 Dynamics 365 伺服器資源，特別是由 CreateRequiredRecords 方法 方法所建立。 它會查詢使用者以驗證此作業，然後逐一查看 entityUris 集合，並嘗試刪除每一個元素，使用 HTTP DELETE 訊息。

另請參閱

使用 Microsoft Dynamics 365 Web API
Web API 範例
Web API 範例 (用戶端 JavaScript)
Web API 基本作業範例 (C#)
Web API 查詢資料範例 (C#)
Web API 條件式作業範例 (C#)
Web API 函數和動作範例 (C#)

Microsoft Dynamics 365

© 2017 Microsoft. 著作權所有，並保留一切權利。 著作權

  • Last updated on