XRM ツールで接続文字列を使用する

Dynamics 365 Customer Engagement (on-premises) によって、XRM ツールによる接続文字列を使用したインスタンスへの接続が可能になります。 これは SQL Server で使用される接続文字列の概念と似ています。 接続文字列は、最大限のセキュリティを得るために構成セクションを暗号化する機能を含むネイティブ サポートを、構成ファイルに備えています。 これにより、インスタンスに接続する際に、アプリケーションにハード コーディングしない Dynamics 365 Customer Engagement (on-premises) 接続を展開時に構成することができます。

Note

Dataverse ユーザー用の接続文字列に関するドキュメントが、Power Apps ドキュメントで利用できるようになりました: XRM ツールで接続文字列を使用して Dataverse に接続する

接続文字列の作成

以下の例のように、この接続文字列をプロジェクトの App.config または web.config ファイルで指定します。

<connectionStrings>  
    <add name="MyCRMServer" connectionString="AuthType=AD;Url=https://contoso:8080/Test;" />  
</connectionStrings>  

重要

app.config ファイルまたは web.config ファイルにアカウント パスワードなどの機密情報を追加する場合は、適切なセキュリティ対策を講じてその情報を保護してください。

接続文字列を作成したら、それを使用して CrmServiceClient オブジェクトを作成します。

//Use the pre-configured connection string named "MyCRMServer"
CrmServiceClient crmSvc = new CrmServiceClient(ConfigurationManager.ConnectionStrings["MyCRMServer"].ConnectionString);  

Note

コード内の以下の using ディレクティブを使用して、System.Configuration 名前空間を参照し、コード内の接続文字列にアクセスする必要があります: using System.Configuration;

CrmServiceClient オブジェクトを作成したら、そのオブジェクトを使用して Dynamics 365 Customer Engagement (on-premises) でアクションを実行することができます。 詳細: XRM ツールを使用してアクションを実行する

接続文字列パラメーター

接続文字列には、セミコロンで区切られた一連の名前=値の組が含まれまています。 次の表は、任意の受注で入力できる、サポートされるパラメーターを一覧表示しています。

パラメーター名	説明
ServiceUri、Service Uri、Url または Server	Dynamics 365 Server の URL を指定します。 URL は、http または https プロトコルを使用することができ、ポートはオプションです。 http プロトコルの既定ポートは 80 で、https プロトコルの既定ポートは 443 です。 典型的なサーバー URL の形式は、https://crm-server:port/organization-name または Dynamics 365 Customer Engagement (on-premises) です。 組織名は必須です。 接続する組織には、わかりやすい名前または一意の名前を指定できます。 例: https://contoso/test、https://contoso:5555/test、https://contoso/test、https://10.10.10.2/test。
Domain	ユーザーの資格情報を検証するドメインを指定します。
UserName、User Name、UserId または User Id	資格情報に関連付けられたユーザーの ID 名を指定します。
Password	資格情報に関連付けられたユーザー名のパスワードを指定します。
HomeRealmUri または Home Realm Uri	ホーム レルムの Uri を指定します。
AuthenticationType または AuthType	Dynamics 365 Customer Engagement (on-premises) に接続するための認証の種類を指定します。 有効な値は次のとおりです: AD, IFD (AD FS 有効化)、OAuth または Office365。 - AD および IFD は Dynamics 365 Customer Engagement (on-premises) インスタンスにのみ許可されています。 - OAuth は、Dynamics 365 Customer Engagement (on-premises) および Dataverse インスタンスのみ許可されています。 オンプレミスの場合、OAuth タイプには、ADFS 3.x+ と ADFS による App\Client Id 登録が必要です。 - Office365 は、Dataverse インスタンスにのみ許可されています。 - 認証のための証明書またはクライアント シークレットの使用は、Dataverse ではサポートされていますが、Dynamics 365 Customer Engagement (on-premises) ではサポートされていません。
RequireNewInstance	接続がまだアクティブの間に再呼び出しされた場合に、既存の接続を再利用するかどうかを指定します。 既定値は既存の接続が再利用されることを示す false です。 true に設定した場合、これによりシステムは強制的に固有の接続を作成します。
ClientId、AppId、または ApplicationId	Azure Active Directory または Active Directory フェデレーション サービス (AD FS) にアプリケーションを登録したとき割り当てた ClientID を指定します。
RedirectUri または ReplyUrl	Azure Active Directory または Active Directory フェデレーション サービス (AD FS) に登録したときの、アプリケーションのリダイレクト URI を指定します。 このパラメータは認証の種類が OAuth として指定されている場合にのみ適用されます。
TokenCacheStorePath	ユーザー トークンのキャッシュに保存する必要がある場所の完全なパスを指定します。 実行プロセスには指定されたパスへのアクセス権があるべきです。 このパスを設定し構成することが、このプロセスの役割です。 このパラメータは認証の種類が OAuth として指定されている場合にのみ適用されます。
LoginPrompt	資格情報が提供されていない場合に資格情報の入力を促すかどうかを指定します。 有効な値は: - Always: 常に資格情報を指定するようユーザーを促す。 - Auto: プロンプトを表示するかどうかを、ログイン コントロール インターフェイスで選択することをユーザーに許可する。 - Never: 資格情報を指定するようユーザーを促さない。 使用している接続方法にユーザー インターフェースがない場合は、この値を使用してください。 このパラメータは認証の種類が OAuth として指定されている場合にのみ適用されます。
SkipDiscovery	特定のインスタンスの接続 URI を決定するためにインスタンス検出を呼び出すかどうかを指定します。 NuGet リリース Microsoft.CrmSdk.XrmTooling.CoreAssembly バージョン 9.0.2.7 の時点で、規定は true です。 以前のバージョンの既定は false です。 注意: true に設定された場合、ユーザーがターゲット インスタンスの正しい URI を正確に指定することが重要です。
Thumbprint または CertificateThumbprint	S2S 接続時に使用する証明書のサムプリントを指定します。 設定した場合、AppID が必要であり、UserId とパスワード値は無視されます。
StoreName または CertificateStoreName	サムプリントで識別された証明書を見つけることができる店舗名を指定します。 設定した場合、サムプリントが必要です。

注意

開発とプロトタイピングの目的で、OAuth 認証タイプを使用する場合、OAuth フローで使用するために次の AppId または ClientId とリダイレクト URI を提供しています。 これらはすべてのコードサンプルで使用されています。

サンプルの AppId または ClientId = 51f81489-12ee-4a9e-aaae-a2591f45987d
サンプルの RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97

運用環境での使用については、Azure 管理ポータルのテナントに固有の AppId または ClientId を作成する必要があります。

接続文字列の例

次の例は Dynamics 365 Customer Engagement (on-premises) および IFD 展開に接続するための接続文字列の使用方法を示しています。 Dataverse インスタンス用の接続文字列の例が Power Apps ドキュメントで利用できるようになりました: XRM ツールで接続文字列を使用して Dataverse に接続する

統合設置型認証

<add name="MyCRMServer"
connectionString="AuthType=AD;
Url=https://contoso:8080/Test;" />  

設置型認証を使用している取引先企業

<add name="MyCRMServer"
connectionString="AuthType=AD;
Url=https://contoso:8080/Test;
Domain=CONTOSO;
Username=jsmith;
Password=passcode" />  

認証のプロンプトに Dynamics 365 Customer Engagement (on-premises) で UX と一緒に取引先企業を使用している OAuth

oAuth 経由のユーザー ID またはパスワードを使用して、新しい接続を作成します。

Note

OAuth は、対話型フローを使用する場合 Dynamics 365 Customer Engagement (on-premises) に接続するための優先する認証タイプです。 この認証のタイプは Azure Active Directory 条件付きアクセスおよび多要素認証の機能を完全にサポートしています。

<add name="MyCRMServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith;
  Password=passcode;
  Url=https://contoso:8080/Test;
  AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;
  RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
  TokenCacheStorePath=c:\MyTokenCache;
  LoginPrompt=Auto"/>  

フォールバック UX で現在ログインしているユーザーを使用して認証を求める OAuth

oAuth 経由で現在ログインしているユーザーを使用して、新しい接続を作成します。

Note

OAuth は、対話型フローを使用する場合 Dynamics 365 Customer Engagement (on-premises) に接続するための優先する認証タイプです。 この認証のタイプは Azure Active Directory 条件付きアクセスおよび多要素認証の機能を完全にサポートしています。 Integrated Security パラメータの詳細については、トピックを こちら でご覧ください。

<add name="MyCRMServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith;
  Integrated Security=true;
  Url=https://contoso:8080/Test;
  AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;
  RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
  TokenCacheStorePath=c:\MyTokenCache;
  LoginPrompt=Auto"/>  

サブ部門への委任に取引先企業を使用している IFD

<add name="MyCRMServer"
connectionString="AuthType=IFD;Url=https://contoso:8080/Test;
 HomeRealmUri=https://server-1.server.com/adfs/services/trust/mex/;
Domain=CONTOSO; 
Username=jsmith; 
Password=passcode" />  

接続状態を決定する

接続要求が成功したかどうかを決定するには、CrmServiceClientIsReady プロパティの値を確認してください。 true の場合、接続が成功し、実行する準備ができています。 それ以外の場合、接続エラーの原因については CrmServiceClient .LastCrmError および CrmServiceClient.LastCrmExceptionプロパティの値を確認してください。

関連項目

XRM ツールを使用して Windows のクライアント アプリケーションを作成する
CrmServiceClient コンストラクターを使用した Dynamics 365 Customer Engagement (on-premises) および Dataverse への接続
XRM ツールを使用してアクションを実行する
CrmServiceClient