XRM ツールの接続文字列を使用して Microsoft Dataverse に接続する

  • [アーティクル]

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

接続文字列の作成

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

<connectionStrings>  
    <add name="MyCDSServer" connectionString="AuthType=OAuth;Username=jsmith@contoso.onmicrosoft.com;Password=passcode;Url=https://contosotest.crm.dynamics.com;AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;TokenCacheStorePath=c:\MyTokenCache;LoginPrompt=Auto"/>
</connectionStrings>

重要

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

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

//Use the connection string named "MyCDSServer"  
//from the configuration file  
CrmServiceClient svc = new CrmServiceClient(ConnectionString);

あるいは、ServiceClient クラスを使用することもできます。

ServiceClient svc = new ServiceClient(ConnectionString);

注意

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

サービス クライアント オブジェクトを作成した後、そのオブジェクトを使用して Dataverse でアクションを実行することができます。 詳細: XRM ツールを使用して Dataverse のアクションを実行する

接続文字列パラメーター

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

パラメーター名 内容
ServiceUri、Service Uri、UrlまたはServer Dataverse 環境用にURLを指定します。 URL は、http または https プロトコルを使用することができ、ポートはオプションです。 http プロトコルの既定ポートは 80 で、https プロトコルの既定ポートは 443 です。 サーバー URL の形式は通常 https://<organization-name>.crm.dynamics.comです。

組織名は必須です。
UserName、User Name、UserIdまたはUser Id 資格情報に関連付けられたユーザーの ID 名を指定します。
Password 資格情報に関連付けられたユーザー名のパスワードを指定します。
HomeRealmUri または Home Realm Uri ホーム レルムの Uri を指定します。
AuthenticationType または AuthType Dataverse 環境に接続するために認証の種類を指定します。 有効な値は次のとおりです: AD、IFD(AD FS 有効化)、OAuth、Certificate、ClientSecret、 または Office365。 ただし、OAuth、Certificate、ClientSecret、Office365 は、Dataverse 環境で許可される値です。

メモ: Office365 認証の種類は非推奨であり、OAuth …を優先的な認証の種類として使用することをお勧めします。 詳細: 影響を受けた場合にアプリケーション コードを修正するにはどうすればよいか
RequireNewInstance 接続がまだアクティブの間に再呼び出しされた場合に、既存の接続を再利用するかどうかを指定します。 true に設定した場合、これによりシステムは強制的に固有の接続を作成します。 false に設定されている場合、既存の接続を再利用できます。
ClientId、AppId または ApplicationId Microsoft Entra ID または Active Directory フェデレーション サービス (AD FS) にアプリケーションを登録したとき割り当てた ClientID を指定します。
ClientSecret または Secret 認証タイプが ClientSecret に設定されている場合は必須。 認証に使用するクライアント シークレット文字列。
RedirectUri または ReplyUrl Microsoft Entra ID または Active Directory フェデレーション サービス (AD FS) に登録したときの、アプリケーションのリダイレクト URI を指定します。

このパラメータは認証の種類が OAuth として指定されている場合にのみ適用されます。
TokenCacheStorePath ユーザー トークンのキャッシュに保存する必要がある場所の完全なパスを指定します。 実行プロセスには指定されたパスへのアクセス権があるべきです。 このパスを設定し構成することが、このプロセスの役割です。

このパラメータは認証の種類が OAuth として指定されている場合にのみ適用されます。
LoginPrompt 資格情報が提供されていない場合に資格情報の入力を促すかどうかを指定します。 有効な値は:

- Always: 常に資格情報を指定するようユーザーを促す。
- Auto: プロンプトを表示するかどうかを、ログイン コントロール インターフェイスで選択することをユーザーに許可する。
- Never: 資格情報を指定するようユーザーを促さない。 使用している接続方法にユーザー インターフェースがない場合は、この値を使用してください。

このパラメータは認証の種類が OAuth として指定されている場合にのみ適用されます。
StoreName または CertificateStoreName サムプリントで識別された証明書を見つけることができる店舗名を指定します。 設定した場合、サムプリントが必要です。
Thumbprint または CertThumbprint S2S 接続時に使用する証明書のサムプリントを指定します。 設定した場合、AppID が必要であり、UserId とパスワード値は無視されます。
Integrated Security 現在の Windows 資格情報を使用して、インスタンスのトークンの作成を試行することを指定します。 NuGet リリース Microsoft.CrmSdk.XrmTooling.CoreAssembly バージョン 9.1.0.21 の時点

注意

OAuth AuthType\AuthenticationType を使用する場合
開発とプロトタイピングの目的で、OAuth フローで使用するために、次の AppId または ClientId とリダイレクト URI を提供しています。
運用環境での使用については、Azure 管理ポータルのテナントに固有の AppId または ClientId を作成する必要があります。
サンプルの AppId または ClientId = 51f81489-12ee-4a9e-aaae-a2591f45987d
サンプルの RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97

接続文字列の例

次の例は、online の展開および認証シナリオに接続するための接続文字列の使用方法を示しています。 設置型および IFD 展開インスタンスの接続文字列の例は、次に示す Dynamics 365 Customer Engagement (on-premises) ドキュメントで入手可能になりました: XRM ツールで接続文字列を使用して Customer Engagement に接続する

Office365 を使用した名前付き取引先企業

Office365 でユーザー名またはパスワードを使用して Dataverse への新しい接続を作成します。

注意

この AuthType は非推奨であり、優先認証の種類として OAuth を使用することをお勧めします。 詳細: Office365 を使用した認証

<add name="MyCDSServer" 
 connectionString="
  AuthType=Office365;
  Username=jsmith@contoso.onmicrosoft.com; 
  Password=passcode;
  Url=https://contoso.crm.dynamics.com"/>

認証のプロンプトに Microsoft 365 で UX と一緒に取引先企業を使用している OAuth

OAuth 経由で UserId またはパスワードを使用する Dataverse に新規に接続します。

注意

OAuth は、インタラクティブ フローを使用するときに Dataverse に接続するための推奨される認証タイプです。 この認証のタイプは Microsoft Entra ID の条件付きアクセスおよび多要素認証の機能を完全にサポートしています。

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

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

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

注意

OAuth は、インタラクティブ フローを使用するときに Dataverse に接続するための推奨される認証タイプです。 この認証のタイプは Microsoft Entra ID の条件付きアクセスおよび多要素認証の機能を完全にサポートしています。

<add name="MyCDSServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith@contoso.onmicrosoft.com;
  Integrated Security=true;
  Url=https://contosotest.crm.dynamics.com;
  AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;
  RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
  TokenCacheStorePath=c:\MyTokenCache\msal_cache.data;
  LoginPrompt=Auto"/>

クレームベース認証

アプリケーションまたはクライアント ID と証明書を使用して、Dataverse への新しい接続を作成します。

<add name="MyCDSServer" 
  connectionString="
  AuthType=Certificate;
  url=https://contosotest.crm.dynamics.com;
  thumbprint={CertThumbPrintId};
  ClientId={AppId};"
  />

ClientId またはクライアント シークレット ベースの認証

アプリケーションまたはクライアント ID とクライアント シークレットを使用して、Dataverse への新しい接続を作成します。

<add name="MyCDSServer" 
  connectionString="
  AuthType=ClientSecret;
  url=https://contosotest.crm.dynamics.com;
  ClientId={AppId};
  ClientSecret={ClientSecret}"
  />

接続状態を決定する

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

関連項目

XRM ツールを使用して Windows のクライアント アプリケーションを作成する
CrmServiceClient コンストラクターを使用して Dataverse に接続
XRM ツールを使用して Dataverse でアクションを実行
CrmServiceClient

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。