Relax model restrictions to refactor overlayering into extensions


Dynamics 365 for Finance and Operations is now being licensed as Dynamics 365 Finance and Dynamics 365 Supply Chain Management. For more information about these licensing changes, see Dynamics 365 Licensing Update.

Dynamics 365 for Finance and Operations 8.0, and all subsequent releases, will not allow Microsoft’s code to be customized by using over-layering. Instead, extension capabilities should be used to modify and add behavior. The "no over-layering" restriction is a key part of the evolution of the product toward providing customers with a cloud ERP service that is simple to update and always running the most recent version possible to allow all customers to receive the benefits of the latest features and fixes.

After you upgrade code to 8.0 or later, when you compile, any customizations that still use over-layering will cause errors. To refactor the code, the over-layering restriction can be temporarily relaxed in the model descriptor file of the model that is being over-layered. This temporary relaxation only works on development and demo environments and cannot be deployed on runtime environments like Standard Acceptance Test (or higher) sandbox or production environments. Relaxing the descriptor restriction will enable the code to be gradually refactored to extensions, compiled, run, and then tested.

Detailed process

Complete the following steps to relax model restrictions. This procedure can be completed on a cloud environment or a local virtual machine (VM).

  1. Deploy a Dynamics 365 for Finance and Operations 8.0 development environment.

  2. Run the Lifecycle Services (LCS) code upgrade service to upgrade the solution.

  3. Temporarily allow over-layering in Microsoft models as needed to enable compilation.

    a. Locate the desired model within the C:\AOSService\PackagesLocalDirectory folder.

    b. Navigate to the descriptor folder. For example, \Currency\Descriptor.

    c. Open the XML file. For example, Currency.xml.

    d. Add a Customization metadata element inside the AxModelInfo metadata element to indicate AllowAndWarn so that the start of the file now looks like this.

    <AxModelInfo xmlns:i="">
    <AppliedUpdates xmlns:d2p1="" />
  4. Refactor over-layering to extensions and test. Make use of extension capabilities to eliminate over-layering. If needed, make extensibility requests.

  5. Revert the temporary changes to Microsoft models. The deployment of a model that uses over-layering will not be possible, so it's important to ensure that the descriptor file is updated.  

Prototyping extensibility requests

As a solution gradually migrates toward extensions, there will be places where an extensibility request is required to unblock the solution. To fully understand what is needed to unblock a solution and smooth the migration process toward extensions, extension capabilities can be prototyped in a separate model.

  1. Identify the need for an extension capability to refactor some over-layering.

  2. Add a prototype of extension capabilities into an extension prototype model.

    • For enumeration extensibility, put a copy of the enumeration into the extension prototype model and mark it as extensible.

    • For extract method extensibility, prototype the extracted method and the overlayered original in the extension prototype model.

  3. Use the prototype extension capability.

  4. If the prototype extension capability is sufficient, create a matching request.

  5. When the extension capability has been implemented in the platform or application, the prototype extension capability and any associated over-layering should be removed from the extension prototype model.

  6. After the solution has all over-layering refactored to extensions and the extension prototype model is empty, the solution refactoring is complete.