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 Web API を使用するコンソールアプリケーションを構築する Microsoft Visual Studio で新しいプロジェクトを作成する方法を説明します。 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 のインストールを参照してください。
Dynamics 365 Web API Helper Library が含まれている NuGet パッケージおよびその他の依存パッケージをダウンロードするのにインターネット接続が必要です。
オプションで、Microsoft Dynamics 365 SDKをここでダウンロードできます。Microsoft Dynamics 365 SDK は、これらの Web API サンプルの作成または実行に必要とはされませんが、Dynamics 365 開発者の多数は、補足リソースが豊富であるため、それのインストールを希望しており、また、その他の Dynamics 365 インターフェイスへのアクセスには SDK が必要とされます。

プロジェクトの作成

以下の手順では、Microsoft .NET Framework を使用する C# でコンソールアプリケーションプロジェクトを作成する方法を説明します。サポートされる .NET Framework のバージョンの詳細については、「サポートされる Microsoft Dynamics 365 の拡張機能」を参照してください。

新しいプロジェクト

Microsoft Visual Studio では、[新しいプロジェクト] をクリックします。 [新しいプロジェクト] ダイアログが表示されます。
[テンプレート] の下の左側のナビゲーションウィンドウで、[Visual C#] を選択します。
[使用可能なテンプレートの一覧の上側で、[.NET Framework 4.5.2] を選択します。
テンプレートの一覧で、[コンソールアプリケーション] を選択します。 (代わりに、ソリューションに適するプロジェクトの種類を選択してください。) Web API C# サンプルのすべてがコンソールアプリケーションです。
フォームの下部近くのテキストボックスに、プロジェクトの名前と場所を入力し、[OK] を選択します。 (このトピックでは、ソリューション名「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 Helper Library (C#) の使用」を参照してください。これらのクラスを使用することは任意ですが、Web API サンプルでは幅広く使用されています。 Dynamics 365 SDK Web API ヘルパーライブラリは、NuGet パッケージとしてソース・コード形式で頒布されます。今後の更新は、NuGet パッケージの更新として頒布されます。

NuGet コマンドラインユーティリティをインストールし、Visual Studio でパッケージマネージャーコンソールを使用している場合:

次のコマンドを発行し、ヘルパーライブラリーパッケージをインストールします。

Install-Package Microsoft.CrmSdk.WebApi.Samples.HelperCode
依存パッケージの処理における複数のメッセージが表示されています。 [ライセンスの同意] ダイアログが表示されている場合、ライセンス条項を読み、[同意] をクリックします。
ヘルパーライブラリパッケージのインストールを確認するには、下の手順 6 に進みます。

NuGet パッケージマネージャー拡張機能がインストールされている場合:

[プロジェクト] メニューから、[NuGet Packages の管理] を選択します。 [NuGet Package Manager] タブが表示されます。
右上隅では、[パッケージ] ソースドロップダウンを [Nuget.org] に設定します。
左上隅では、[参照] をクリックし、検索ボックスでは「Dynamics 365 HelperCode」と入力して、Enter を押します。
[インストール] をクリックします。 [プレビュー] ダイアログが表示されたら、[OK] をクリックします。
[ライセンスの同意] ダイアログが表示されます。ライセンス条項を検討し、[同意する] をクリックします。
[ソリューションエクスプローラー] ウィンドウに移動します。 [Web API Helper Code] という名前の新しいソリューションのフォルダが追加されていることを確認します。

Dynamics 365 SDK Web API Helper Library パッケージ、Microsoft.CrmSdk.WebApi.Samples.HelperCode はヘルパーライブラリパッケージと共に自動的にダウンロードされ、インストールされる以下の他のパッケージに依存しています。

Newtonsoft.Json – には Json.NET、一般的に使用されている .NET の MIT ライセンス JSON フレームワークが含まれています。
Microsoft.IdentityModel.Clients.ActiveDirectory – には .NET クライアントの認証機能を提供する Active Directory Authentication Library (ADAL) のバイナリが含まれています。

警告

Dynamics 365 SDK Web API Helper Library パッケージは、他の 2 つのサポートパッケージの特定バージョンに対して作成されました。このため、ヘルパーライブラリの NuGet パッケージのみを直接更新する必要があります。この操作を実行すると、必要に応じて適切なサポートパッケージが更新されます。これらのサポートパッケージ 1 つを別に更新する場合は、そのパッケージのより新しいバージョンの方が新しいヘルパーライブラリと互換性がある可能性があります。

必要なアセンブリ参照を確認します。

[ソリューションエクスプローラー] では、[参照] ノードを展開します。
次の参照がプロジェクトに追加されていることを確認します。
アプリケーション内で定期的に使用する追加機能がある場合は、必要なアセンブリへ関連する参照を追加することができます。詳細については、「[参照の追加] ダイアログボックスを使用して参照の追加または削除する方法」を参照してください。

Dynamics 365 Web API は REST の原則をベースとしているので、クライアント側アセンブリがアクセスする必要はありません。ただし、Microsoft Dynamics 365 によりサポートされているその他の API はこれらを必要とします。詳細については、「Microsoft Dynamics 365 SDK に含まれるアセンブリ」を参照してください。

一般的な using ステートメントの追加

[ソリューションエクスプローラー] で、編集に対して [Program.cs] を開きます。
ファイルの先頭に、Dynamics 365 Web API ベースのソリューションで一般的に使用されている名前空間を参照する、次の using ステートメントを追加します。
```
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 Library (C#) の使用を参照してください。

アプリケーション構成ファイルの編集

[ソリューションエクスプローラー] で、編集に対して [App.config] ファイルを開きます。既存の <startup> セクションの後に、次の 2 つのセクションをそれに追加し、ファイルを保存します。

<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 code: 構成クラス」を参照してください。

ヘルパーライブラリを呼び出すコードの追加

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

ヘルパーライブラリの Configuration および Authentication クラスを使用する ConnectToCRM メソッドを追加します。次のコードは、Dynamics 365 Web API のリリースバージョンに正常にアクセスできるよう、HttpClient プロパティに割り当てる値を示しています。

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 Web 365 API への呼び出しを含め、カスタムコードを承諾する準備が整っている骨格フレームを表します。

ヒント

このトピックを閉じる前に、プロジェクトテンプレートとしてプロジェクトを保存することを検討します。次に、今後の学習プロジェクトのためにそのテンプレートを再利用すると、新しいプロジェクトの設定の時間と労力を節約できます。これを行うには、プロジェクトを Microsoft Visual Studio で開いている間に、[ファイル] メニューで、[テンプレートのエクスポート] を選択します。テンプレートウィザードのエクスポートの指示に従い、テンプレートを作成します。

次の方法で共有

Visual Studio (C#) で Dynamics 365 Web API プロジェクトを起動する

前提条件

プロジェクトの作成

新しいプロジェクト

必要なすべてのリソースをプロジェクトに追加する

ヘルパーライブラリの NuGet パッケージの追加

必要なアセンブリ参照を確認します。

一般的な using ステートメントの追加

つながりコードの追加

アプリケーション構成ファイルの編集

ヘルパーライブラリを呼び出すコードの追加

エラー処理コードの追加

次のステップ

関連項目

その他のリソース

次の方法で共有

Visual Studio (C#) で Dynamics 365 Web API プロジェクトを起動する

前提条件

プロジェクトの作成

新しいプロジェクト

必要なすべてのリソースをプロジェクトに追加する

ヘルパー ライブラリの NuGet パッケージの追加

必要なアセンブリ参照を確認します。

一般的な using ステートメントの追加

つながりコードの追加

アプリケーション構成ファイルの編集

ヘルパー ライブラリを呼び出すコードの追加

エラー処理コードの追加

次のステップ

関連項目

その他のリソース

ヘルパーライブラリの NuGet パッケージの追加

ヘルパーライブラリを呼び出すコードの追加