在 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

本主题演示如何在 Microsoft Visual Studio 中创建新项目，用于生成使用 Dynamics 365 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。
需要 Internet 连接才能下载包含 Dynamics 365 Web API 帮助程序库和依赖包的 NuGet 包。
也可以单击此处下载 Microsoft Dynamics 365 SDK。尽管不需要 Microsoft Dynamics 365 SDK 就可以构建或运行这些 Web API 示例，大多数 Dynamics 365 开发人员还是希望安装，因为其中包含一组丰富的补充资源，并且需要该 SDK 才能访问其他 Dynamics 365 界面。

创建项目

以下程序演示了如何以 C# 创建使用 Microsoft .NET Framework 的控制台应用程序项目。有关 .NET Framework 的受支持版本的详细信息，请参阅Microsoft Dynamics 365 的受支持扩展。

新建项目

在 Microsoft Visual Studio 中，单击“新建项目”。将显示“新建项目”对话框。
在“模板”下的左导航窗格中，选择“Visual C#”。
在可用模板列表上方，选择“.NET Framework 4.5.2”。
在模板列表中，选择“控制台应用程序”。（也可以选择适合您的解决方案的项目类型。）所有 Web API C# 示例均为控制台应用程序。
在窗体底部附近的文本框中，提供项目的名称和位置，然后选择“确定”。（对于本主题，使用的解决方案名称是“StartWebAPI-CS”。）将生成初始解决方案文件并将解决方案加载到 Microsoft Visual Studio 中。
在“项目”菜单下，打开项目的属性表单并验证目标框架是否被设置为“.NET Framework 4.5.2”。

将所有所需的资源添加到项目中

以下程序说明了如何将所有所需的托管引用和包添加到您的项目中。将其视为大多数托管代码应用程序调用 Web API 应用程序时所需的一组基本资源。

添加帮助程序库 NuGet 包

Dynamics 365 SDK Web API 帮助程序库中包含用于协助执行补充性操作（如应用程序配置、Dynamics 365 服务器身份验证、异常处理和 Web 通信）的类。有关详细信息，请参阅使用 Microsoft Dynamics 365 Web API 帮助程序库 (C# 库)。尽管 Web API 示例中广泛使用了这些类，但是是否使用是可选的。 Dynamics 365 SDK Web API 帮助程序库以 NuGet 包的形式通过源代码格式分发。以后的更新将以 NuGet 包更新的形式分发。

如果已安装 NuGet 命令行实用工具或正在使用 Visual Studio 中的程序包管理器控制台：

发出以下命令安装帮助程序库包。

Install-Package Microsoft.CrmSdk.WebApi.Samples.HelperCode
将显示有关处理依赖项包的几条消息。如果显示“许可证接受”对话框，请阅读许可证条款，然后单击“接受”。
跳到下面的步骤 6，确认安装帮助程序库包。

如果已安装了 NuGet Package Manager 扩展：

从“项目”菜单选择“管理 NuGet 包”。将显示“NuGet Package Manager”选项卡。
在右上角，将“包”源下拉列表设置为“Nuget.org”。
在左上角，单击“浏览”，在搜索框中输入“Dynamics 365 HelperCode”，然后按 Enter 键。
单击“安装”。如果显示“预览”对话框，请单击“确定”。
将显示“许可证接受”对话框。查看许可证条款，然后单击“接受”。
导航到“解决方案资源管理器”窗口。确认已添加了名称为“Web API 帮助程序代码”的新解决方案文件夹。

Dynamics 365 SDK Web API 帮助程序库包 Microsoft.CrmSdk.WebApi.Samples.HelperCode 依赖下面的其他包，这些包随帮助程序库包一起下载和安装：

Newtonsoft.Json – 其中包含 Json.NET，这是一款面向 .NET 且已经 MIT 许可的 JSON 框架。
Microsoft.IdentityModel.Clients.ActiveDirectory – 包含 Active Directory 身份验证库的二进制文件 (ADAL)，用于为 .NET 客户端提供身份验证功能。

警告

Dynamics 365 SDK Web API 帮助程序库包针对这两个其他支持包的具体版本生成。因此，您仅应更新帮助程序库 NuGet 包。如果需要，此操作将更新正确的支持包。如果单独更新这些支持包其中之一，该包的较高版本可能与帮助程序库不兼容。

添加所需的程序集引用

在“解决方案资源管理器”中，展开“引用”节点。
确认已向项目添加了以下引用。
如果您还有其他功能在应用程序中日常使用，可立即添加所需程序集的关联引用。有关详细信息，请参阅实施方法：通过使用“添加引用”对话框添加或删除引用。

由于 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 帮助程序库 (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 帮助程序代码：配置类。

添加代码以调用帮助程序库

编辑 Program.cs 文件。
将下面的属性添加到 Program 类：成功连接到 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 方法，该方法使用帮助程序库 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 服务器提供值，程序也应该成功连接到该服务器。此解决方案提供一个已准备好接受自定义代码（包括对 Dynamics 365 Web API 的调用）的骨干框架。

提示

离开此主题之前，考虑将项目另存为项目模板。这样便可以在将来的学习项目中重用该模板，节省您设置新项目的时间和精力。方法是，当您的项目在 Microsoft Visual Studio 中打开时，请在“文件”菜单中，选择“导出模板”。按照导出模板向导说明创建模板。

另请参阅

Microsoft Dynamics 365 Web API (C#) 入门
 使用 Microsoft Dynamics 365 Web API 帮助程序库 (C# 库)
使用 Web API 执行操作

Microsoft Dynamics 365

通过