仮想エンティティの API に関する考慮事項
Dynamics 365 for Customer Engagement バージョン 9.0 の仮想エンティティの導入に関連付けられるメタデータ システムに対する変更には 2 つの大きなカテゴリがあります。
- 新しいアセンブリ、名前空間、クラス、およびユーザー定義の仮想エンティティ データ プロバイダーの開発をサポートするその他の種類の追加
- 外部データ ソース マッピングをサポートするためのいくつかの追加のプロパティや、この機能の初期実装の制限を反映する既存のエンティティおよび属性プロパティーの動作の変更を含む、コア プラットフォームの変更
新しい Dynamics 365 Customer Engagement Data SDK アセンブリ
Dynamics 365 Customer Engagement (on-premises) Data SDK アセンブリ、Microsoft.Xrm.Sdk.Data.dll には、ユーザー定義の仮想エンティティ データ プロバイダーの作成を支援するための種類が含まれています。 次の名前空間で構成されます:
| 名前空間 | 内容 |
|---|---|
| Microsoft.Xrm.Sdk.Data | AllowedQueryOptions 列挙などのいくつかの一般的な種類を含むベースの名前空間 |
| Microsoft.Xrm.Sdk.Data.CodeGen | 動的リフレクション、種類の一致、およびコードの生成をサポートするクラスとインターフェイスが含まれます。 主に内部プロバイダー エンジンによって使用されます。 |
| Microsoft.Xrm.Sdk.Data.Converters | 標準 XRM タイプを対応する .NET 基本タイプに変換する一連のクラス |
| Microsoft.Xrm.Sdk.Data.Exceptions | ランタイム値の解決時に発生する可能性のあるエラーを表す例外クラスのセット。 すべては Microsoft.Xrm.Sdk.SdkExceptionBase から派生しています。 |
| Microsoft.Xrm.Sdk.Data.Expressions | FILTER、JOIN、および ORDER などのサポートされているクエリ変換の実装を支援するクラス。 |
| Microsoft.Xrm.Sdk.Data.Infra | 中央クエリ処理をサポートするその他のクラス。 |
| Microsoft.Xrm.Sdk.Data.Mappings | 仮想エンティティ メタデータ タイプから外部タイプへのマッピングを構築するクラスとインターフェイス。 |
| Microsoft.Xrm.Sdk.Data.Visitors | RetrieveMultiple 中に ビジター パターン を実装して、データ プロバイダーに渡される QueryExpression パラメーター上で特定の操作を実行するクラス。 一般的なクエリと LINQ ベースの処理の両方に特定のサポートを提供します。 これらのクラスは Microsoft.Xrm.Sdk.Query.QueryExpressionVisitorBase から派生しています。 |
このアセンブリは、Dynamics 365 Customer Engagement (on-premises) Data SDK とともに配布されます。これは NuGet パッケージとしても提供されています。
コア プラットフォームへの変更
標準の Dynamics 365 の参照種類への次の変更が、仮想エンティティをサポートするために導入されました。
新しい Web API の種類
Dynamics 365 Customer Engagement Web API は、仮想エンティティ データ プロバイダーとソースを EntityDataProvider と EntityDataSource という新しいエンティティ タイプとして公開します。
新しい metadata.properties.key
4つの新しいプロパティが、Microsoft.Xrm.Sdk.Metadata.EntityMetadata クラスに追加されました:
- DataProviderId - 関連する仮想エンティティ データ プロバイダーを識別するGUID
- DataSourceId - 関連する仮想エンティティ データ ソースを識別するGUID
- ExternalName - 外部データ ソースのこの種類の名前
- ExternalCollectionName - UI で使用され、OData アクセスをサポートする、この種類の複数名
2 つの新しいプロパティが、Microsoft.Xrm.Sdk.Metadata.AttributeMetadata クラスに追加されました:
- ExternalName - 外部データ ソースの種類の名前
- IsDataSourceSecret - このフィールドに機密情報を含んでいるかどうかを示します
ExternalNameプロパティも、オプションおよび OptionSetMetadata クラスに追加されました。 これらの外部の名前は、外部データソース内の関連する種類の名前を指定することによって、外部データソースのマッピングを支援します。 これらのプロパティは仮想エンティティでのみ使用されます。組み込みまたは標準のユーザー定義にエンティティの種類の場合、これらの外部名は null でなければなりません。
仮想エンティティの作成
仮想エンティティの種類をプログラムで作成するアプローチは、標準のユーザー定義のエンティティの種類の作成とは少し異なります:
- 関連付けられたデータ プロバイダー (およびオプションのデータ ソース) が作成時にわかっている場合は、これらが指定されます。
- この種類のデータ プロバイダーがわからない場合は、最低でも、
EntityMetadata.DataProviderIdは7015A531-CC0D-4537-B5F2-C882A1EB65ADに設定し、EntityMetadata.DataSourceIdはnullに設定します。 実行時にこの種類のインスタンスを使用する前に、これらのプロパティに適切な値を割り当てる必要があります。
2 つの新しいエンティティの種類、EntityDataProvider およびオプションの EntityDataSource は、プラグイン、およびそれぞれの ID、entitydataproviderid および entitydatasourceid を登録する際に作成され、これらの必要な GUID を表します。 (それ以外の場合は、開発者はこれらのユーザー定義の種類に直接アクセスすることはめったにありません。) DataSourceには、対応するDataProvider の種類と一致する必要がある entitydataproviderid プロパティが含まれているか、実行時例外がスローされることに注意してください。
警告
標準 (非仮想) エンティティは関連する EntityMetadata.DataProviderId と EntityMetadata.DataSourceId の値がデフォルト値 (null) に設定されていることが必要で、それ以外の場合は実行時例外がスローされます。 作成される、非仮想の種類を仮想の種類に変換したり、またはその逆を行うことはできません。
エンティティ メタデータ プロパティ動作の変更
次の表は、標準の EntityMetadata properties の動作が仮想エンティティに適用されたときにどのように変更されるかについて説明しています。 一部のプロパティは仮想エンティティには有効ではありませんが、その他のプロパティは範囲や値に制限があります。
| メタデータ プロパティ | 適用? | メモ |
|---|---|---|
| ActivityTypeMask | 無効 | 常時 0 |
| 属性 | 有効 | |
| AutoCreateAccessTeams | 無効 | 常時 false |
| AutoRouteToOwnerQueue | 無効 | 常時 false、キューはサポートされていません。 |
| CanBeInManyToMany | 有効 | |
| CanBePrimaryEntityInRelationship | 有効 | |
| CanBeRelatedEntityInRelationship | 有効 | |
| CanChangeHierarchicalRelationship | 無効 | 常時 false、階層型の関連付けはサポートされていません。 |
| CanChangeTrackingBeEnabled | 無効 | 常時 false、変更の追跡および値の監査はサポートされていません。 |
| CanCreateAttributes | 有効 | |
| CanCreateCharts | 無効 | 常時 false |
| CanCreateForms | 有効 | |
| CanCreateViews | 有効 | |
| CanEnableSyncToExternalSearchIndex | 無効 | 常時 false |
| CanModifyAdditionalSettings | 有効 | |
| CanTriggerWorkflow | 無効 | 常時 false、ワークフローはトリガーできません。 |
| ChangeTrackingEnabled | 無効 | 常時 false |
| CollectionSchemaName | 有効 | |
| DaysSinceRecordLastModified | 無効 | 常時 null または 0 |
| 内容 | 有効 | |
| DisplayCollectionName | 有効 | |
| DisplayName | 有効 | |
| EnforceStateTransitions | 無効 | StateCode とステータスはサポートされていません。 |
| EntityColor | 有効 | |
| EntityHelpUrl | 有効 | |
| EntityHelpUrlEnabled | 有効 | |
| EntitySetName | 有効 | |
| ExtensionData | 無効 | 廃止されたプロパティ |
| HasChanged | 有効 | |
| IconLargeName | 有効 | |
| IconMediumName | 有効 | |
| IconSmallName | 有効 | |
| IntroducedVersion | 有効 | |
| IsActivity | 無効 | 常時 false、アクティビティはサポートされていません。 |
| IsActivityParty | 無効 | 常時 false |
| IsAIRUpdated | 無効 | 廃止 |
| IsAuditEnabled | 無効 | 常時 false、監査はサポートされていません。 |
| IsAvailableOffline | 無効 | 常時 false、オフラインでの使用はサポートされていません。 |
| IsBusinessProcessEnabled | 無効 | 常時 false、ビジネスプロセスはサポートされていません。 |
| IsChildEntity | 無効 | 常時 false、すべての仮想エンティティは組織的に所有されます。 |
| IsConnectionsEnabled | 有効 | |
| IsCustomEntity | 有効 | |
| IsCustomizable | 有効 | |
| IsDocumentManagementEnabled | 有効 | |
| IsDocumentRecommendationsEnabled | 無効 | 常時false、この新しい機能はサポートされていません。 |
| IsDuplicateDetectionEnabled | 無効 | 常時 false、しかし重複データ検出はソース データで実行できます。 |
| IsEnabledForCharts | 制限あり | サポートされた Fetch 句のみ。 |
| IsEnabledForTrace | 有効 | |
| IsImportable | 有効 | |
| IsInteractionCentricEnabled | 有効 | |
| IsIntersect | 有効 | |
| IsKnowledgeManagementEnabled | 無効 | 常時 false、ナレッジ マネージメントの統合はサポートされていません。 |
| IsMailMergeEnabled | 有効 | |
| IsManaged | 有効 | |
| IsMappable | 有効 | |
| IsOfflineInMobileClient | 無効 | 常時 false、仮想エンティティ値はオフラインでの使用にはキャッシュされません。 |
| IsOneNoteIntegrationEnabled | 有効 | |
| IsOptimisticConcurrencyEnabled | 無効 | 常時 false、同時実行をデータ ソースで実行する必要があります。 |
| IsPrivate | 有効 | |
| IsQuickCreateEnabled | 有効 | |
| IsReadOnlyInMobileClient | 有効 | |
| IsRenameable | 有効 | |
| IsSLAEnabled | 無効 | 常時 false |
| IsStateModelAware | 無効 | |
| IsValidForAdvancedFind | 有効 | |
| IsValidForQueue | 有効 | |
| IsVisibleInMobile | 有効 | |
| IsVisibleInMobileClient | 有効 | |
| キー | 無効 | 代替キーはサポートされていません。 |
| LogicalCollectionName | 有効 | |
| LogicalName | 有効 | |
| ManyToManyRelationships | 有効 | |
| ManyToOneRelationships | 有効 | 2 つの仮想エンティティ間ではサポートされていません。 |
| MetadataId | 有効 | |
| MobileOfflineFilters | 無効 | 常時 false、オフラインでの使用はサポートされていません。 |
| ObjectTypeCode | 有効 | |
| OneToManyRelationships | 有効 | |
| OwnershipType | 無効 | 常時 OrganizationOwned |
| PrimaryIdAttribute | 有効 | |
| PrimaryImageAttribute | 有効 | |
| PrimaryNameAttribute | 有効 | |
| 特権 | 無効 | |
| RecurrenceBaseEntityLogicalName | 無効 | |
| ReportViewName | 無効 | |
| SchemaName | 有効 | |
| SyncToExternalSearchIndex | 無効 | |
属性メタデータ プロパティ動作の変更
次の表は、標準の AttributeMetadata のプロパティ の動作が仮想エンティティに適用されたときにどのように変更されるかについて説明しています。 一部のプロパティは仮想エンティティには有効ではありませんが、その他のプロパティは範囲や値に制限があります。
| メタデータ プロパティ | 適用? | メモ |
|---|---|---|
| ColumnNumber | 無効 | |
| DeprecatedVersion | 有効 | |
| 内容 | 有効 | |
| DisplayName | 有効 | |
| EntityLogicalName | 有効 | |
| ExtensionData | 無効 | |
| HasChanged | 有効 | |
| InheritsFrom | 有効 | |
| IntroducedVersion | 有効 | |
| IsAuditEnabled | 無効 | 常時 false、監査はサポートされていません。 |
| IsCustomAttribute | 有効 | |
| IsCustomizable | 有効 | |
| IsFilterable | 有効 | |
| IsGlobalFilterEnabled | 有効 | |
| IsLogical | 有効 | |
| IsManaged | 有効 | |
| IsPrimaryId | 有効 | |
| IsPrimaryName | 有効 | |
| IsRenameable | 有効 | |
| IsSearchable | 有効 | |
| IsSecured | 無効 | 常時 false、フィールドレベルのセキュリティはサポートされていません。 |
| IsSortableEnabled | 有効 | |
| IsValidForAdvancedFind | 有効 | |
| IsValidForCreate | 有効 | |
| IsValidForRead | 有効 | |
| IsValidForUpdate | 有効 | |
| LinkedAttributeId | 有効 | |
| LogicalName | 有効 | |
| MetadataId | 有効 | |
| RequiredLevel | 有効 | |
| SchemaName | 有効 | |
| SourceType | 無効 | 常時 0、計算されたまたはロールアップ値はサポートされていません。 |