Microsoft Dataverse supported and unsupported app building practices
Modern business applications use a metadata-driven architecture so that people can create apps without writing code. Metadata means “data about data” and it defines the structure of the data stored in Dataverse. With this metadata, an application knows about any changes to the data structure and this enables the application to adapt as the data structure changes. Since the metadata is known, additional capabilities can be included that are tied to the metadata.
Changing the Dataverse components, such as entities, views, fields, charts, and dashboards to build apps that work the way you want is called customization.
When you build and customize your apps using the tools in Power Apps, you’re adding or updating the metadata or data used by features that depend on the metadata. Because we know the kinds of data used to create apps, we can take this data into account and add new features to your Dataverse environment without breaking your apps.
You don’t need to be a developer to build and customize Power Apps apps. However, Power Apps provides a set of web services and APIs that allow developers to write code. When code is written using supported methods you can expect that it will continue to work when your Dataverse environment is updated.
What kinds of customizations are supported?
We expect that you can do most app building and customization using the available Power Apps tools. If the customization tools don’t meet your needs, you can install a solution provided by a third party or hire a developer to code your app. If you need to invest in a solution that requires code, you should make sure that the code is written using only supported APIs. This helps you protect your investment in both the apps and any solutions you get.
Developers who extend Power Apps apps have a responsibility to follow rules and best practices documented here. Microsoft supports only the APIs and practices that are documented in the SDK. You may find something on the Internet that describes how you can solve a problem, but if it doesn’t leverage APIs documented in the SDK, it isn’t supported by Microsoft. Before you have a developer apply a change you should verify whether it uses supported methods.
If developers use the APIs and best practices described in the SDK we can be sure to test whether any of the changes we make to Dataverse has the potential to break existing customizations. Our goal is that code customizations written using supported methods will continue to work when new versions or updates to Dataverse are released. You benefit because you can upgrade to new versions with improved features without having developers change their code each time.
If we detect that a change in a new version of Dataverse will cause a supported customization to break, we will document what is affected and how people can change their code to fix it.
What kinds of customizations aren’t supported?
Just because certain APIs and programming practices aren’t supported by Microsoft doesn’t mean that they don’t work. The developer who uses unsupported APIs and programming practices assumes the responsibility to support their code. They will need to test their code to make sure it works.
If you choose to use unsupported customizations in your Dataverse environment you should be sure to document what was done and have a strategy to remove those customizations before you contact Microsoft Technical Support. If you need help with unsupported customizations, contact the developer or organization who prepared the customizations.
Common unsupported customization practices
The following is a list of common customization practices that aren’t supported. This is not a complete list. More information: Supported extensions for Dynamics 365: Unsupported customizations.
Interacting with the web application Document Object Model (DOM) elements using JavaScript
Any JavaScript libraries used anywhere in the application must only interact with the documented APIs. When JavaScript developers work with applications they frequently access DOM elements using specific names. Because Power Apps apps are web applications these techniques work, but they are likely to break during an update because the names of the elements they reference are subject to change at any time. We reserve the right to make any changes necessary in the application and this frequently means changing how the page is constructed. Adding any changes that depend on the current structure of the page means that you’ll need to invest in testing and perhaps changing the custom code in these scripts each time you apply an update to your application.
jQuery is a very common library used by JavaScript developers. Most of the benefit of using jQuery is that it simplifies a developer’s ability to access and create DOM elements, which is exactly what we do not support in the Dataverse application pages. jQuery is recommended when developers are creating custom user interfaces with HTML web resources, but within the Power Apps application pages, the supported APIs do not require jQuery to be used.
Using any undocumented internal objects or methods using JavaScript
The Dataverse uses many JavaScript objects within pages. A JavaScript developer can discover these objects by debugging a page and then access and reuse these objects. We reserve the right to make any changes necessary to these objects, including removing them or changing the names of the methods. If a script references these objects, the script will break if they are not found.
Combine customization capabilities
The topics found in these sections describe individual customization capabilities in considerable depth. But it’s important to keep in mind that the solutions to meeting your business requirements will frequently use one of the capabilities together with one or more other capabilities.
Choose the right customization capability for the job
With all the different customization capabilities available in Power Apps it’s easy to become familiar with one of them and seek to use it to solve every problem. As you evaluate the business problems you want to solve, think about the end result you want to achieve and then work backwards to how you can get there.
Changes that affect Dataverse environment performance
Importing solutions and applying customizations that change metadata can affect Dataverse environment performance. Actions that can interfere with normal system operation include:
Add, remove, or change entities, alternate keys, attributes, or relationships.
Import solutions
Publishing customizations
If you’re applying these changes to a production system, we recommend that you schedule these operations when it is least disruptive to users.