本記事では Dynamics CRM SDK 4.0.12 から 含まれるようになった Advanced Developer Extensions for Microsoft Dynamics CRM SDK を使ってみます。今回は、SDKに付属する CrmSvcUtil.exe ツールを使用してエンティティ クラスと DataContext クラスなどの自動生成の方法まで記載します。

SDK のダウンロードは次のリンクからダウンロードします。

Microsoft Dynamics CRM 4.0 Software Development Kit (SDK)
http://www.microsoft.com/downloads/details.aspx?FamilyID=82E632A7-FAF9-41E0-8EC1-A2662AAE9DFB&displaylang=en

Advanced Developer Extensions for Microsoft Dynamics CRM SDK のドキュメントは SDKを展開したフォルダsdk\microsoft.xrm に格納されています。今回はSDKドキュメント advanced_developer_extensions_-_developers_guide.docx の翻訳(俺式ですが)みたいなもんですが。

プログラムに関しては[Dynamics CRM] Dynamics CRM 4.0 Advanced Developer Extensions を使ってみる コンソールプログラム編 , [Dynamics CRM] Dynamics CRM 4.0 Advanced Developer Extensions を使ってみる Webアプリ編  を参照。

1. Advanced Developer Extensions for Microsoft Dynamics CRM SDKについて

Advanced Developer Extensions for Microsoft Dynamics CRM は Microsoft Dynamics CRM SDK に付属する新しいツールセットです。SDK によって Dynamics CRM 4.0 を使用するアプリケーションの開発を簡単かつ迅速に行えるようになります。

Advaced Developer Extensions for Microsoft Dynamics CRM は次の機能を提供します。

• Microsoft Dynamics CRM サーバーへの接続の簡易化(Microsoft.Xrm.Client)
• 静的に型付けされたエンティティコードの生成(CrmSvcUtil.exe, Microsoft.Xrm.Client)
• Microsoft Dynamics CRMデータの修正の簡易化(Microsoft.Xrm.Client)
• LINQクエリを使用した Microsoft Dynamics CRM データ取得のサポート(Microsoft.Xrm.Client)

Portal Developer's Toolkit は Microsoft Dynamisc CRMと強固に統合されたWebポータルの構築を可能にします。Portal Developer's Toolkitの詳細はSDK付属の Advanced_Developer_Extensions-_Porta_Developer_Guide.docx を参照して下さい。ポータルツールキットは次の機能を提供します。

• セキュリティマネージメント(Microsoft.Xrm.Portal)
• キャッシュマネージメント(Microsoft.Xrm.Portal)
• コンテンツマネージメント(Microsoft.Xrm.Portal, Microsoft.Xrm.Poratl.Files, WebSiteCopy.exe)

Advanced Developer Extensions for Microsoft Dynamics CRM はMicrosoft Dynamics CRMの全ての配置モデル(On-Premise, Internet-facing Deployment(IFD), CRM Online) をサポートしています。

1.1 簡易化されたMicrosoft Dynamics CRM への接続

Advanced Developer Extensions for Microsoft Dynamics CRM は Dynamics CRM サーバーに接続するのに接続文字列を使用します。これは SQL Server への接続時に使用する接続文字列と類似しています。接続文字列は ADO.NET フレームワークで使用され、構成ファイルでネイティブサポートされます。接続文字列はまた、セキュリティーを高めるために暗号化することができます。

接続文字列を使用することで、デプロイ時にMicrosoft Dynamics CRM への接続文字列をアプリケーション構成ファイルに設定し、プログラム内へのハードコードを行わないようにする、堅牢なモデルを使用できます。

Advanced Developer Extensions for Microsoft Dynamics CRM の API は CrmConnection オブジェクトと連携して機能します。CrmConnection は XrmDataContext クラスによって内部的に使用され、Dynamics CRM サーバーに接続するために接続文字列を使用します。

接続文字列は以下の例のようにアプリケーション構成ファイル(app.config or web.config)に設定します。

<connectionStrings>
  <add name="Crm" connectionString="Authentication Type=Passport;
    Server=https://your-org-name.crm.dynamics.com/your-orgid;
    User ID=your-windowslive-id; Password=your-wlid-password;
    Device ID=your-device-id; Device Password=your-device-password"/>
</connectionStrings>

構成ファイルで設定した接続文字列は、 XrmDataContext のインスタンスを作成するときに使用します。

//Use the Microsoft Dynamics CRM Online connection string from the app.config file.
var crm = new Xrm.XrmDataContext("Crm");

接続文字列の基本書式は OLEDB 接続文字列と同じです。名前と値のペアをセミコロン;で区切って記述します。以下の表の各項目を任意の順番に指定します。

1.2 接続文字列のサンプル

次の文字列は、統合認証の接続文字列例です。

AuthenticationType=Integrated; Server=http://crm-server-name/crm-organization-name

次の文字列は、Active Directory 認証の接続文字列例です。

Authentication Type=AD; Server=http://crm-server-name:port/crm-organization-name; User ID=user-domain\user-name; Password=user-password

次の文字列は、SPLA(IFD)認証の接続文字列例です。

Authentication Type=SPLA; Server=http://crm-server-name/crm-organization-name; User ID=user-domain\user-name; Password=user-password

次の文字列は、Windows Live IDを使用する CRM Online への接続文字列例です。

Authentication Type=Passport; Server=https://crm-organization-name.crm.dynamics.com/crm-organization-name; User ID=user-windows-live-id; Password=user-password; Device ID=user-defined-device-id; Device Password=user-defined-device-password

2. CrmSvcUtil ツールを使用したコード生成

Advanced Developer Extensions for Microsoft Dynamics CRM は CrmSvcUtil.exe というコマンドラインのコード生成ツールが付属しています。ツールはデータコンテキストクラスと、 Microsoft Dynamics CRMエンティティのデータ転送オブジェクト(Data Transfer Objets, DTOs) を生成するために使われます。ツールのメカニズムは、エンティティフレームワーク(LINQ to SQLでは?)のSqlMetalの実装と同じデザインパターンに従っています。データコンテキストクラスは、全てのデータ操作に対して責任を持ち、Microsoft Dynamics CRMのすべてのエンティティに対して IQueryable インタフェースを提供します。開発者はIQueryable を実装したエンティティのプロパティに対してLINQクエリを実行してデータを取得することができます。開発者はAddObject, DeleteObject, UpdateObject そして SaveChanges メソッドを使用して、データを変更することができます。 CrmSvcutil ツールは \sdk\microsoft.xrm\tools フォルダに格納されています。

CrmSvcUtil.exe は次の機能を提供します

• 静的に型付けされたエンティティの生成
• 多対多(N対N)関連クラスの生成
• Picklist 属性に対応する 列挙型の生成(検証時点では、表示名をもとに生成した場合)
• Microsoft Dynamics CRM エンティティのスキーマ名ではなく、表示名を使用したプロパティ名やクラス名の生成
• エンティティを管理するための、WCF Data Services (Astoria/oData) 互換のデータコンテキストクラスの生成

2.1 Entity Classes

コード生成ツールによって作成されたデータ転送オブジェクト(Data Transofer Objects) エンティティクラスは次の機能を提供します

• WCF Data Services (Astoria/oData) アノテーション属性のサポート
• 型付けされたエンティティ属性のアクセッサ.アクセッサによって次の機能が提供されます
  • Dynamics CRM データタイプとCLRデータタイプへのマッピング
  • 多対1(N対1)関連のアクセッサ
    • 関連エンティティの遅延ロード
    • 関連エンティティIDアクセッサ
    • 型付けされたポリモーフィックな外部キー関連(Lookup, Customer, Owner)属性のサポート
  • 多対多属性のアクセッサ.アクセッサは次の機能が提供します
    • 関連エンティティ集合の遅延ロード
    • 属性のチェンジトラッキングサポート
      • 更新操作は修正された属性のみサーバに更新を行います
      • ピックリスト属性に対する文字列ラベルアクセッサの提供
      • パフォーマンスのためのメタデータキャッシュ

2.2 Data Context Classes

CrmSvcUtil コード生成ツールによって生成されるデータコンテキストクラスは ADO.NE TData Services の IUpdatable と IExpandProvider インタフェースを使用します。詳細な情報は、以下の .NET documentation IUpdatable Interface と IExpandProvider Interface を参照.これらのインタフェースは次の機能を含んでいます。

• エンティティに対する参照、更新、削除操作
• 1対N, N対1, N対N 関連に対する set-link, add-link, remove-link 操作
• Webサービス,REST サービスを公開するための DataServiceHostFactoryのサポート
• 静的または動的に型付けされたクエリ用のLINQクエリプロバイダ
• バックグラウンドでのキャッシュ処理

2.3 CrmSvcUtil Command-line Parameters

Microsoft Dynamics CRM 組織用の データコンテキストクラスとデータ転送オブジェクトクラス(Data Transfer Objects, DTOs)をCrmSvcUtil コマンドラインツールを使用して生成することができます。
コマンドラインで使用できるパラメタが以下の表に記載されています。

2.4 CrmSvcUtil Example

CrmSvcUtil を使用してコードを生成する方法を示します。以降の例は、Microsoft Dynamics CRMデモンストレーション用のVirtual PC を対象としたものです。サーバ名は crm, 組織名は Contosoです。データコンテキストクラスのプリフィックスは ContosoとしContosoDataContext, ContosoDataServiceという名前のデータコンテキストクラスをContoso.Xrm名前空間に生成します。各クラスは組織Contoso のエンティティのスキーマ名を使用して作成されます。

crmsvcutil /server:"http://crm/Contoso" /namespace:Contoso.Xrm /dataContextPrefix:Contoso /out:Xrm.cs

次の例は、Microsoft Dynamics CRM Online 配置の組織Contoso に対して CrmSvcUtil を使用してクラスを生成する方法を示します。データコンテキストクラスの名前は Contoso とし、ContosoDataContext, contosoDataService クラスを名前空間 Contoso.Xrmに作成します。クラス名はContoso組織のエンティティのスキーマ名から作成されます。

crmsvcutil /connectionString:"Authentication Type=Passport; Server=https://contoso.crm.dynamics.com/contoso; User ID=user-windows-live-id; Password=user-password; Device ID=user-defined-device-id; Device Password=user-defined-device-password" /namespace:Contoso.Xrm /dataContextPrefix:Contoso /out:Xrm.cs

次の例では、Internet Facing Deployment 配置の組織Contoso に対して CrmSvcUtilツールを使用してクラスを生成する方法を示します。データコンテキストクラスの名前は Contoso とし、ContosoDataContext, contosoDataService クラスを名前空間 Contoso.Xrmに作成します。クラス名はContoso組織のエンティティのスキーマ名から作成されます。

crmsvcutil /connectionString:"Authentication Type=SPLA; Server= http://crm-server-name/Contoso; User ID=user-name; Password=user-password" /namespace:Contoso.Xrm /dataContextPrefix:Contoso /out:Xrm.cs

3. まとめ

今回の説明は以上です。ここまでで、Dynamics CRM の 組織のスキーマ情報からデータコンテキストクラスとエンティティクラスを生成できるようになったと思います。