【Dynamics CRM】【C#】【7.1新機能】代替キーの使い方

Dynamics CRM 2015 Update1で結構SDK周りの拡張が行われました。

その中でも地味ながら、うれしい拡張が代替キーと思われます。

代替キー概要

Dynamics CRMのSDKを用いてレコードのUpdateを行う場合は、Guidを指定する必要がありました。

たとえば、取引先担当者のメールアドレスを一意の情報としてUpdateを行いたい場合、メールアドレスを抽出条件としたRetreaveMlutipleリクエストを実施。取得したEntityCollectionの中から対象となるレコードのGUIDを取得して、Updateを行うという流れになっていました。

しかし、今回導入された代替キーを利用することで、Updateリクエストを行う際にGuidの指定が必要なくなりました。（もちろん状況によっては必要となるでしょうけど。）

これにより、1回分のリクエスト処理を省略できるので、Updateを頻繁に行うプログラムですとかなりありがたいものと思われます。

というわけで、代替キーの作成方法から、利用方法までを簡単に記載していきたいと思います。

代替キーの設定方法

代替キーはエンティティごとに設定します。

Dynamics CRM 2015 Update1からエンティティのカスタマイズの項目に【キー】が増えていると思います。

f:id:sugimomoto:20150531160330p:plain

ここで新規を押すと、代替キーを設定するための画面が出てきます。

代替キーは一つのエンティティで5つまで作成可能です。

また、一つの代替キーで指定可能なフィールドは16個までとなっていました。（そこまで指定しないでしょうけど）

代替キーとして設定可能なフィールドは下記3種類。日付と時間や検索フィールドは代替キーとして指定できませんので、ご注意ください。

Decimal Number
Whole Number
Single Line of Text

今回は取引先担当者エンティティへ電子メールアドレス1だけを指定した代替キーを作成してみました。

f:id:sugimomoto:20150531160521p:plain

代替キーの使い方

代替キーは［KeyAttributeCollection］クラスを利用して指定します。

KeyAttributeCollectionをインスタンス化した後、Addで対象となるフィールドと一意の値を指定します。

            // Keyの設定
            var keys = new KeyAttributeCollection();
            keys.Add("emailaddress1", "someone_a@example.com");

ここなんですが、意外（？）なことに、代替キーの物理名を指定するわけではありません。あくまで代替キーの対象として設定したフィールドの物理名です。（はじめ思い込みで引っかかりました）

KeyAttributeCollectionインスタンスは、EntityもしくはEntityReferenceの第2引数に対して指定できるようになっています。

Entityクラスのコンストラクタが以下のようになっていますね。

f:id:sugimomoto:20150531161406p:plain

使う箇所としては、［UpdateのEntityに対して］［CreateやUpdate時のEntityReference］［新しく追加されたUpSert］になるかと思います。

なお、Deleteでは指定できませんでした。

実行環境

最新のDynamics CRM環境も必要ですが、SDKと.NETも最新版が必要ですので、ご注意ください。

・Dynamics CRM SDK 7.1

・.NET Frameworks 4.5.2

コード

というわけで、実際のコードです。今回はContactの更新です。

using System;
using Microsoft.Xrm.Client;
using Microsoft.Xrm.Client.Services;
using Microsoft.Xrm.Sdk;


namespace MyProject.AlternateKey
{
    class Program
    {
        static void Main(string[] args)
        {
            var connection = CrmConnection.Parse("Url=https://***.crm7.dynamics.com; Username=***@***.onmicrosoft.com; Password=****;");
            var service = new OrganizationService(connection);

            // Keyの設定
            var keys = new KeyAttributeCollection();
            keys.Add("emailaddress1", "someone_a@example.com");

            // Update用Entityの作成
            var Contact = new Entity("contact", keys);

            Contact["fax"] = "代替キーによりUpdateされました";

            service.Update(Contact);

            Console.WriteLine("代替キーでのUpdate完了");

            Console.ReadKey();
        }
    }
}