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 Community 免费版本。
Internet 连接，用于下载和更新提到的 NuGet 包。
可访问 Dynamics Dynamics 365 Online 或本地部署（或更高版本）。 对于所有 Dynamics 365 安装类型，都需要有权执行 CRUD 操作的用户帐户。
若要针对 Dynamics 365（在线） 运行示例，必须在 Azure Active Directory 中注册您的示例以获取客户端 ID 和重定向 URL。 有关详细信息，请参阅演练：使用 Azure Active Directory 注册 Dynamics 365 应用程序。
Web API 示例清单 (C#)
下表列出了使用 C# 实现的示例。 相应示例组主题中以更通俗易懂的方式介绍了每个示例，这些主题侧重介绍 HTTP 请求和相应消息，如主题 Web API 示例 中的详细介绍。
示例 |
示例组 |
说明 |
|---|---|---|
演示如何创建、检索、更新、删除、关联和解除关联 Dynamics 365 实体记录。 |
||
演示如何使用查询语法 v4 OData 和函数以及 Microsoft Dynamics 365 和函数。 包含处理预定义的查询和使用 FetchXml 执行查询的示例。 |
||
演示如何执行使用 ETag 条件指定的条件操作。 |
||
演示如何使用绑定和取消绑定功能和操作，包括自定义操作。 |
如何下载和运行示例
MSDN 代码库中提供各示例的源代码。 示例主题中包含各示例的下载链接。 示例下载是 .zip 压缩文件，其中包含示例的 Visual Studio 2015 解决方案文件。 有关详细信息，请参阅各示例主题的运行此示例章节。
各示例的公共元素
大多数示例都有类似的结构并且包含公共方法和资源，通常用于为 Web API C# 程序提供基本体系结构。
新建用于访问 Dynamics 365 Web API 的解决方案时，也会提供这些公共元素中的许多。 有关详细信息，请参阅在 Visual Studio (C#) 中启动 Dynamics 365 Web API 项目。
使用的库和框架
此 C#实施依赖以下帮助程序代码执行 HTTP 通信、应用程序配置、身份验证、错误处理和 JSON 串行化。
System.Net.Http 命名空间中的标准 .NET Framework HTTP 消息传递类（特别是 HttpClient、HttpRequestMessage 和 HttpResponseMessage）用于 HTTP 消息传递。
Dynamics 365 Web API 帮助程序库用于读取应用程序配置文件，使用 Dynamics 365 服务器执行身份验证，以及帮助处理运行错误。 有关详细信息，请参阅使用 Microsoft Dynamics 365 Web API 帮助程序库 (C# 库)。
Newtonsoft Json.NET 库支持 JSON 数据格式。
Json.NET 库
由于 C# 和其他大多数托管语言本机不支持 JSON 数据格式，所以现在最好的方法是对此功能使用库。 有关详细信息，请参阅 JavaScript 和 .NET 中的 JavaScript 对象表示法 (JSON) 简介。 Json.NET 是 .NET 对象的热门选择。 它提供（MIT 许可）的强大、开源的框架，用于对 JSON 数据执行串行化、转换、解析、查询和格式化操作。 有关详细信息，请参阅 Json.NET 文档。
在 C# 示例中，此库主要用于对 .NET 对象与 HTTP 消息正文之间的数据执行串行化。 尽管该库提供了多种方法来完成此任务，示例使用的方法却是创建单个 JObject实例来表示 Dynamics 365 实体实例（记录）。 例如，以下代码创建用于表示 Dynamics 365 contact EntityType 实例的变量 contact1，然后为此类型的一组精选属性提供支持。
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 实体，将使用该资源的 URI 更新 entityUris 集合。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 帮助程序库 (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 方法
此方法调用帮助程序库以读取应用程序配置文件，然后建立与指定的 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 帮助程序库 (C# 库)。
CreateRequiredRecords 方法
仅当这些操作不是示例的主要兴趣时，此方法创建和初始化示例所需的实体记录。 例如，Web API 基本操作示例 (C#) 中不包含此方法，因为创建记录是示例的主要考虑事项。
RunAsync 方法
此异步方法中包含相关源代码，或者对于更长的程序，则包含用于对相关示例代码分组的调用方法。 嵌入的注释和每个响应示例主题的备注部分介绍了包含的代码。
DisplayException 方法
此帮助程序方法将异常信息，包括内部异常，显示到标准控制台。
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。 保留所有权利。 版权