Dynamics 365 CRM On-Premises — Gotchas

These traps apply to any kalamos project working against a D365 CE on-prem deployment. Cross-project; not specific to CRMAPIGenerator.

Auth quirks

Plain Windows auth + ADFS + IFD is the production scaffold for most regulated customers. The CrmServiceClient connection string has different shapes for each:
- AD: AuthType=AD; Url=...; Domain=...; UserName=...; Password=...;
- ADFS: AuthType=Federation; Url=...; HomeRealmUri=...; UserName=...; Password=...;
- IFD: AuthType=IFD; Url=...; Username=...; Password=...; HomeRealmUri=...;
OAuth on-prem requires the deployment to have ADFS configured for OAuth flows (not all do).
S2S / app-user auth is not available on on-prem before v9.0 RU8 — and even then has limitations vs Online.
Token-cache misses on long-running services manifest as silent retries; instrument with logging at the CrmServiceClient boundary.

OData v4 endpoint at /api/data/v9.x/. The version segment matters; mismatched client/server versions fail with HTTP 404.
Web API uses different metadata than the SOAP/Org Service endpoint. A property name in EntityMetadata.LogicalName may not equal the OData entity-set name (e.g., account → accounts). Always introspect at runtime; don’t hardcode pluralization.
Batch operations via $batch have a hard 1000-change-set limit per request. Larger payloads must be chunked.
Prefer: odata.include-annotations="*" header is needed for FormattedValue, navigation-property, and lookup logical-name annotations. Most agent code forgets this and ends up with nulls where labels were expected.

Sandbox plugins (the only kind allowed in cloud, optional but recommended on-prem) cannot:
- Make outbound network calls except via IOrganizationService
- Touch the filesystem
- Use System.Reflection.Assembly.Load*
- Spawn threads
Plugin steps at Pre-Validation run outside the database transaction. Pre-Operation and Post-Operation run inside. State leakage across stages is a common bug source.

Import and BulkDelete jobs are async and report progress via ImportJob and BulkDeleteOperation entities. Polling these is the only reliable way to know when they finish.
Audit data does not export through standard tools. Custom retrieval against Audit entity required.

Customer environments are typically pinned at a specific Update Rollup (Microsoft.Crm.Sdk.Proxy). Mismatched SDK version on the agent’s machine vs server: most ops still work but specific entity attributes (newer ones) won’t appear in metadata calls.