Migration and upgrade code for Dynamics 365 from CRM2011/2013/2016

Upgrading code is a critical activity for an upgrade, especially if you are upgrading from an earlier version such as Dynamics CRM 2011. There are some client-side methods that are deprecated to make it easy to move from one client to another. So, even if you are upgrading from Dynamics CRM 2016, you need to upgrade your client-side code to make it compatible with Dynamics 365 CE. Although old methods can work due to compatibility support, they will stop working in some major Dynamics 365 CE releases. Let's discuss high-level changes that we need to make in our Dynamics CRM 2016 code, as follows:

• Xrm.Page: In Dynamics CRM 2016, the Xrm.Page object was used to refer to entity forms and fields from JavaScript written on entity forms as well as HTML web resources. But now, using Xrm.Page to access entity forms and fields in the script written for entity forms is deprecated. Instead of using Xrm.Page, we need to use formContext to refer to an entity and its field. We can get formContext from executionContext, which we can pass from form and field events. We can use the following code to get formContext from the method parameter:

AccountName_OnChange:function(executionContext)
{
//get formContext from execution contextvar formContext = executionContext.getFormContext();   
}

In the preceding code, we are getting the executionContext parameter, which is configured to pass from an event definition.

The use of Xrm.Page in HTML web resources is still supported if we have an HTML web resource that is using Xrm.Page. We don't need to change anything there.

• Xrm.Page.context: Xrm.Page.context was used in Dynamics CRM 2016 to get contextual information about where our code is executing—for example, to get the client URL, organization name, and organization language code. But now, we need to change our code to use getGlobalContext from Xrm.Utility. This object can be used to get details about the following three settings:
• client: This returns information about the client where our code is executing—for example, web for web client and the Unified Interface client, Outlook, and mobile.

• organizationSettings: We can use this to get details about our organizations—for example, organization ID, language code, and default currency code. All the methods that we use to get organization-related information will be replaced with globalContext.organizationSettings using Xrm.Page.context. 
• userSettings: We can use this to get details about the current user—for example, current user security roles, user ID, username, and time zone information. So, any method that we used earlier to get user setting details such as Xrm.Page.context.getUserLcid needs to change to globalContext.userSetings.languageId.

Apart from the preceding objects, getContext also has some methods available that help us to get the current client URL to make Web API service code, the client version, the current app name, and the app URL.

• Xrm.Page.context.getQueryStringParameters: In CRM 2016, if we wanted to pass any query string parameter, we used the Xrm.Page.context.getQueryStringParameters method. Now, in Dynamics 365 CE, we have to change it to formContext.data.attributes.
• Xrm.Utility.alertDialog and Xrm.Utility.confirmDialog: Xrm.Utility contain many methods that were used earlier to display a prompt to users, such as an alert or confirm dialog, but now, we have to use Xrm.Navigation for these prompts. For example, let's change the following code of CRM 2016:

Xrm.Utility.alertDialog(“Please provide account phone number!”);

We'll change it to the following:

Xrm.Navigation.openAlertDialog(AlertMsg).then(
function success(result) {
//code which we want to execute after alert
},           
function (error) {
//capture error and write in console
console.log(error.message); //in case any error write it under cosole.
} );

Similarly, we need to change the confirmDialog code as well.

• Xrm.Utility.isActivityType: This method was used to know about the entity type. It returns and informs us whether the entity is an activity-type entity or not. This method has been replaced with Xrm.Utility.getEntityMetadata. We can use this method to get entity metadata.
• Xrm.Utility.openEntityForm: This method was used to open an entity form to create a new record, or to open any existing record. But now, it has been replaced with Xrm.Navigation.openForm. We can use this method as follows:

var entityFormOptions = {};
entityFormOptions["entityName"] = "account";
entityFormOptions["openInNewWindow"] = true;
var parameters = {};
//set account number
parameters["accountnumber"] = 1101;
Xrm.Navigation.openForm(entityFormOptions, parameters).then(
function (success) {
//do nothing
},
function (error) {
console.log(error.message);
 });

You can find more details about openForm at https://docs.microsoft.com/en-us/powerapps/developer/model-driven-apps/clientapi/reference/Xrm-Navigation/openForm.

• Xrm.Utility.openQuickCreate: This method was used to open quick create forms in Dynamics CRM 2016, but now, we can use the XrmNavigation.openForm method to open quick create forms. To open a quick create form, we need to set the useQuickCreateForm parameter as follows in Xrm.Navigation.openForm, under entityFormOptions:

entityFormOptions["useQuickCreateForm"] = true;

• Xrm.Utility.openWebResource: openWebResource from Xrm.Utility was used to open any HTML web resource in CRM 2016, but in Dynamics 365 CE it is replaced with Xrm.Navigation.openWebResource. We can use this method with the following syntax:

Xrm.Navigation.openWebResource(webResourceName,windowOptions,data)

Where webResourceName is the name of the web resource that we want to open, windowsOptions are the windows-related options such as height, width, and openInNewWindow. The data parameter is used to send a data collection to the web resource that we want to populate.

We need to change all of the preceding methods from CRM 2016 code to Dynamics 365 CE-compatible code. You can find more details about deprecated methods at https://docs.microsoft.com/en-us/dynamics365/get-started/whats-new/customer-engagement/important-changes-coming#some-client-apis-are-deprecated.

If we are upgrading from CRM 2016, we don't need to upgrade any server-side code as there are no changes to the server-side methods. But if you are upgrading from CRM 2011, you definitely need to remove any references to the 2007 endpoint from your code. You can utilize the tools that we discussed in the Code review section. Now, we know all the activities that we need to perform while upgrading to Dynamics 365 CE. Another thing we need to perform is data migration, when we are moving from one server to another, or we are coming to Dynamics 365 CE from any other legacy system. In the next section, we are going to discuss different data migration options that we can use to import data in Dynamics 365 CE.