Upgrading from previous versions

note

This is a preview version of the User Interface Extensibility Framework v2.0. Some features may be disabled or may still be under active development.

Version 2.0 of the M-Files User Interface Extensibility Framework contains some significant differences to previous versions. Depending upon the functionality of the application it may require significant refactoring for an application to run in the new framework version. Some functionality may not be supported at all.

Commonalities with previous versions

Whilst there are some significant differences to previous versions of the framework, many concepts remain the same. For example:

• Applications are still structured and deployed in the same way: as a zipped file, with a manifest describing the application and its primary components.
• Applications still contain modules, with those modules being the primary entry points to the application.
• Applications can still add tabs, commands, and show dashboards.
• Many common UIX interfaces such as IShellFrame remain the same and expose the same - or similar - functionality.

Primary differences to previous versions

The UIXv2 is designed in a fundamentally different way to previous versions of the framework, and these differences can have a profound impact on your application structure and functionality. Some primary differences you will encounter:

• UI Extensions now run within a more modern browser context, not within the older embedded browser. This enables you to use more modern development approaches and technologies.
• API functions are typically asynchronous, and you must use async functions (or the Promise pattern) to await results of your actions.
• The Vault API reference is fundamentally different. Instead of using/mimicing the M-Files COM API, access is now available to a lower-level M-Files Vault API. Data structures and method names that you may be used to in other environments may have changed in this one.
• Technologies such as Managed Assemblies are not compatible with the User Interface Extensibility Framework 2.0.
• UI Extension dashboards run within a sandboxed <iframe />. This introduces some limitations:
  • You cannot directly pass references to objects or functions using the dashboard's CustomData. Instead you should pass a command ID into the dashboard and then execute it from the dashboard.
  • You cannot access the properties and objects of the parent window directly. Communications between windows should be done using the UI Extension API.
• Some UI constructs, such as the task pane, are not available on newer versions of the client.

Upgrade process

It is important to note that upgrading a UI Extension from earlier versions of the framework is likely to be a non-trivial task, especially where the extension utilises the M-Files API to interact with the vault. It is also important to note that some technologies - for example: Managed Assemblies - are not compatible with the User Interface Extensibility Framework 2.0.

To upgrade an application, you will need to perform the following broad process:

1. Take a copy of the existing application.
2. Alter the application manifest to use the new schema, the new module type, and ensure that the platform targets are correct.
3. Identify areas in your application where the UI will be different to previous clients; for example: if your application previously used the task pane then you will need to alter the approach to use the main menu instead.
4. Alter your module entry points to be asynchronous (async function OnNewShellUI(){ ... }).
5. Work through all UI Extension code to use the async/await pattern (e.g. when creating tabs or commands).
6. Identify code that interacts with the M-Files vault, and alter it to use the new Vault API.
7. Deploy your code into the M-Files vault, connect using the M-Files Web interface, and test/debug.

Consider looking at the samples to help guide with common approaches.