Dynamics 365 Customer Engagement 9.x on-premises

If you are maintaining this today

9.x on-premises is still supported. Microsoft’s lifecycle page starts it on 31 October 2018, with mainstream support ending on 12 January 2029 and extended support on 9 January 2031.

The two releases in the branch do not share those dates:

Release	Support
9.0	Ended 11 July 2023
9.1	7 June 2021 to 9 January 2031

So “we’re on 9.x, we’re supported” is only true on 9.1. The route here from older versions, and what each one runs on, is on on-premises upgrade paths.

The documentation is a trap of a different kind. It is current, on Microsoft Learn under the on-premises section, and the version switcher (view=op-9-0 or view=op-9-1 in the address) matters. But for the parts on-premises shares with the online platform, such as the Web API, plug-ins in general and client scripting, the 9.x pages send you to the Dataverse and model-driven apps documentation. That documentation is written for the current online service. Anything you read there needs checking against 9.x before you rely on it.

There is no SDK download

Source: Microsoft’s “Download Dynamics 365 Customer Engagement (on-premises) version 9.x SDK”.

Earlier versions shipped the SDK as one package with a help file, assemblies, tools and samples. For 9.x the pieces are separate:

• Developer tools are NuGet packages: code generation, Configuration Migration, Package Deployer, Plug-in Registration and Solution Packager.
• SDK assemblies are NuGet packages, used directly from Visual Studio.
• Code samples are listed online.
• The reference documentation is Microsoft Learn itself.

Package	Assemblies
Microsoft.CrmSdk.CoreAssemblies	Microsoft.Xrm.Sdk.dll, Microsoft.Crm.Sdk.Proxy.dll
Microsoft.CrmSdk.Workflow	Microsoft.Xrm.Sdk.Workflow.dll
Microsoft.CrmSdk.XrmTooling.CoreAssembly	Microsoft.Xrm.Tooling.Connector.dll, Microsoft.Rest.ClientRuntime.dll
Microsoft.CrmSdk.Deployment	Microsoft.Xrm.Sdk.Deployment.dll
Microsoft.CrmSdk.Data	Microsoft.Xrm.Sdk.Data.dll
Microsoft.CrmSdk.Outlook	Microsoft.Crm.Outlook.dll

Web services and endpoints

Sources: Microsoft’s “Use Dynamics 365 Customer Engagement web services” and “Authenticate users” for on-premises 9.x.

• The Web API reached parity with the organization service in this release. It is the recommended choice for code that does not run on the server, including web resources and form scripts. On-premises and Dataverse share the same Web API, so its documentation lives with Dataverse.
• Plug-ins and workflow assemblies keep using the organization service. Their inputs and outputs are organization service classes, and Microsoft says the Web API cannot easily be used from server-side code.
• The 2011 SOAP endpoint is deprecated, not removed. The SDK assemblies still call it. Microsoft’s stated plan is to move the assemblies to the Web API internally, so that existing code keeps working after the run-time assemblies are replaced. The CRM 2016 page records the 2016 plan to remove this endpoint. On 9.x on-premises, the current documentation still describes it as deprecated.
• The OData v2 organization data service is deprecated but Microsoft says it will remain available as-is for years. The 9.x documentation no longer covers it and refers you to the CRM 2015 documentation.
• Authentication is claims-based, Active Directory, or OAuth 2.0. OAuth is for Internet-facing deployments (IFD) only. The recommended .NET class is CrmServiceClient.

Form scripting: Xrm.Page is deprecated

Sources: Microsoft’s 9.x on-premises “Client scripting” overview, and the deprecation list it links to.

The 9.x client scripting page warns that some client APIs are deprecated in this release. The list it links to is Microsoft’s general deprecation announcements page, which is maintained for the online service. The main changes:

Deprecated	Use instead
Xrm.Page in form scripts	executionContext.getFormContext()
Xrm.Page in commands	The PrimaryControl parameter
Xrm.Page.context	Xrm.Utility.getGlobalContext()
Xrm.Page.context.getUserId, getUserName, getUserRoles, getUserLcid	globalContext.userSettings
Xrm.Page.context.getOrgUniqueName, getOrgLcid, getIsAutoSaveEnabled	globalContext.organizationSettings
GridRow.getData	GridRow.data
Xrm.Mobile.offline	Xrm.WebApi.offline

According to that announcement, deprecated client APIs remain available and supported until a future major release removes them, with at least six months’ public notice. It also says Xrm.Page is so widely used that it will not be removed as soon as the others. HTML web resources in a form could still reach the form through parent.Xrm, but only when loaded in a form container.

For a 9.x system the practical reading is simple: Xrm.Page code still runs, and any script you touch should move to formContext, which is also what Dataverse expects.

Unified Interface

Sources: Microsoft’s on-premises “About Unified Interface” and “What’s new”.

9.x on-premises has the Unified Interface, and a system setting (“Use the new Unified Interface only”) switches an organization over to it. Not everything had moved across. The 9.1 update opened some features that were not yet in Unified Interface as legacy dialogs inside it: Advanced Find, bulk edit, merge records, record sharing, audit history, personal options and reports.

Plug-ins and workflows on-premises

Sources: Microsoft’s 9.x “On-premises plug-in development” and “Best practices for developing with Dynamics 365 Customer Engagement (on-premises)”.

On-premises deployments can run plug-ins outside the sandbox, which brings some rules that online code never meets:

• Don’t rely on references to objects passed into the pipeline. Data entering the pipeline is serialized and deserialized, so a plug-in works on a copy. Microsoft’s example: a QueryExpression sent with RetrieveMultipleRequest has its PageInfo updated during the query, but the caller’s original variable does not see the change.
• On-disk plug-in and custom workflow assemblies go in <installdir>\Server\bin\assembly.
• Design synchronous plug-ins to finish in under two seconds. The best-practices comparison gives plug-ins a two-minute limit, and the same limit applies to each activity in a workflow.
• Registering plug-ins or custom workflow activities needs the System Administrator or System Customizer role and membership in the Deployment Administrators group. On-premises and IFD, custom workflow activities can run in or outside the sandbox.
• Plug-ins run in an administrator’s context, so they can read data the calling user cannot. A plug-in that copies data elsewhere should run after the core operation, because the user’s privilege checks happen during it.
• For throughput, prefer one long workflow over child workflows. Each workflow instance costs start-up overhead. Child workflows are easier to maintain if the definition changes often.
• Custom workflow activities report errors by throwing InvalidPluginExecutionException, which shows on the workflow instance.

Virtual entities

Sources: Microsoft’s on-premises “Get started with virtual entities” and “What’s new”.

Version 9.0 introduced virtual entities: an entity defined in metadata whose records live in an external system and are fetched at run time by a data provider, itself a kind of plug-in. An OData v4 provider is included.

The 9.0 implementation was read-only and came with limits. Only organization-owned entities could be virtual. There was no field-level security, auditing or change tracking, and no queues, offline use, activities or business process flows. Every external record needed a GUID key, and virtual and standard entities cannot be converted into each other. The 9.1 update added create, update and delete through the OData v4 provider. Microsoft’s getting-started page still describes the read-only version, so read it as the 9.0 baseline.

Also in the 9.1 update

Source: Microsoft’s on-premises “What’s new”.

• The Power Apps Checker module for PowerShell, for static analysis of solutions against best-practice rules.
• Custom help panes and guided tasks for Unified Interface apps.

What this page still needs

Written from Microsoft’s current on-premises 9.x documentation and its lifecycle page. Not yet covered, and not guessed at: the upgrade path from 8.2, what 9.0 removed compared with 8.2, server requirements, and a side-by-side of where 9.x and current Dataverse differ.