Overview
Feature Compatibility Matrix
Feature | Version 1.0 | Version 2.0 | Version 2.1 | Version 2.2 | Version 2.3 |
---|---|---|---|---|---|
Minimum M-Files Server Version | 2015 | 2015.3 | 19.9 | 20.5 | 20.5 |
Automatic State Transitions | Yes | Yes | Yes | Yes | Yes |
Background Operations | Yes | Yes | Yes | Yes | Yes |
Configuration | Yes | Yes | Yes | Yes | Yes |
Configuration commands and buttons | - | - | Yes | Yes | Yes |
Event Handlers | Yes | Yes | Yes | Yes | Yes |
File helpers | - | Yes | Yes | Yes | Yes |
Licensing | - | Yes | Yes | Yes | Yes |
ObjVerEx | Yes | Yes | Yes | Yes | Yes |
Property Calculation | Yes | Yes | Yes | Yes | Yes |
Property Validation | Yes | Yes | Yes | Yes | Yes |
Search helpers | Yes | Yes | Yes | Yes | Yes |
System helpers | Yes | Yes | Yes | Yes | Yes |
Url helpers | - | Yes | Yes | Yes | Yes |
Vault Extension Methods | Yes | Yes | Yes | Yes | Yes |
Workflow Pre- and Post-Conditions | Yes | Yes | Yes | Yes | Yes |
Workflow State Actions | Yes | Yes | Yes | Yes | Yes |
Multi-Server Mode helpers | - | - | - | Yes | Yes |
Version 2.3
This release brings huge improvements around the utilisation of task queues. These improvements include improved stability and retry logic/control, but the primary visible improvement is the removal of almost all boilerplate code required to implement and use task queues. The previous method for using task queues is still available, but you may wish to consider migrating to the new approach.
Note that when upgrading existing projects to VAF 2.3 you will need to re-install the Newtonsoft.JSON
package and potentially alter long-running task queue processes. More details are below.
Version 2.2
Alongside numerous internal bugfixes and performance work, this release brings compatibility with the M-Files Multi-Server Mode functionality. This version can also be used on single-server implementations of M-Files, provided the M-Files server version is at least 20.5.
In this release, if inheriting from ConfigurableVaultApplicationBase
, the Vault Application Framework will only find and resolve MFIdentifier
instances created on your Configuration
class. If you are using MFIdentifier
instances in other locations (e.g. directly on your VaultApplication
class) then note that these will not automatically be resolved at vault startup.
Version 2.1
Alongside numerous internal bugfixes and performance work, this release brings four new major features:
-
The Vault Application Framework is now published to NuGet. This allows us to publish more easily - and faster - Vault Application Framework versions, and for code to be upgraded to use these new versions.
-
Ability to define security constraints in configuration.
-
Commands can be added to various built-in areas in the M-Files Admin Configurations area screens.
-
Buttons within dashboards can call server-side code when clicked.
In addition, please note that there are two changes in method signatures from version 2.0. Both of these changes are implemented to work around situations where code attempts to start background operations when the vault may not yet be fully operational:
BackgroundOperationManager.StartRecurringBackgroundOperation
now returns aTask<BackgroundOperation>
, a change fromBackgroundOperation
in VAF 2.0.BackgroundOperationManager.RunOnce
now returns aTask
, a change fromvoid
in VAF 2.0.
Version 2.0
Alongside numerous internal bugfixes and performance work, this release brings two new major features:
Configuration compatibility
Version 2.0 of the Vault Application Framework introduces a new pattern for exposing application-specific configuration into the M-Files Admin. As M-Files 2015.3 (and earlier) do not contain this section within the M-Files Admin interface, it is recommended that the earlier configuration approach (which continues to work in Version 2.0) is used where compatibility is required with legacy versions.
Version 2.1 of the Vault Application Framework extends this configuration ability, allowing developers to instruct the user interface to mask values that are entered (e.g. passwords), to restrict sections of configuration so that only server administrators (not vault administrators) can change the values, and to add buttons to the dashboard which run server-side code.
It is recommended that you use the new approach to configuration for new VAF applications, and upgrade older approaches where possible.
Version 1.0
Version 1.0 of the Vault Application Framework was released in early 2016. This release included a wide variety of functionality, including:
- Attribute-based automated installation of scripts into the M-Files vault, including workflow state actions, property calculations, event handlers and more.
- Background operations
- Helper objects to aid working with the M-Files vault and Microsoft Windows environment.
- Search helpers
Name-Value Storage Configuration
The initial release of the framework supported configuration attributes that were used to mark up configuration objects used by each application. These configuration objects were serialised into Name-Value storage, and the Name-Value Storage Manager could be used to alter them at runtime.
The 2.0 release of the framework introduced another approach which integrates with the new configuration administration interface in M-Files 2018. It is recommended that applications that target M-Files 2018 and upwards migrate to the new version.
Upgrading versions
When you upgrade the Vault Application Framework you may need to make some small changes due to changes in class namespaces or method signatures.
From Version 2.2 to Version 2.3
Newtonsoft.JSON reinstallation
Due to a change in the way in which references are used, upgrading from VAF 2.2 (or older) to VAF 2.3 may cause the application to not be able to find the Newtonsoft.JSON
DLL. New projects created from the VAF 2.3 Visual Studio template are not affected. When upgrading an existing project to VAF 2.3, you must:
- Click the
Tools
menu in Visual Studio, selectNuGet Package Manager
, and thenPackage Manager Console
- In the NuGet Package Manager Console, ensure that the “Default Project” is your VAF project.
- Enter the following command:
Update-Package -id Newtonsoft.JSON -reinstall
. This will reinstall the current version of the package to the project.
Migrate to VAF 2.3 task queues
Migrate older background operations, or VAF 2.2-style task queues, across to the new VAF 2.3 approach. Note that in VAF 2.3 the task processors run, by default, in Hybrid
transaction mode.
From Version 2.1 to Version 2.2
New VAF 2.2 applications can be created using the M-Files Online Visual Studio template. Projects using the Vault Application Framework 2.1 nuget package can be manually upgraded to use the Vault Application Framework 2.2 runtime:
- Right-click on the project name and select
Manage NuGet Packages...
- Select the existing
M-Files.VAF
reference and click theUpdate
button to upgrade to the latest published 2.2 version.
To upgrade your VAF 2.2 application to be compatible with M-Files Multi-Server Mode, please follow the online conversion guidance.
If inheriting from ConfigurableVaultApplicationBase
, the Vault Application Framework will only find and resolve MFIdentifier
instances created on your Configuration
class. If you are using MFIdentifier
instances in other locations (e.g. directly on your VaultApplication
class) then these should be moved into your Configuration
class to continue to be resolved automatically. Alternatively you can call MFIdentifier.Resolve
at runtime to manually resolve the items.
From Version 2.0 to Version 2.1
New VAF 2.1 applications can be created using the M-Files Online Visual Studio template. Projects using the existing Vault Application Framework 2.0 template need to be manually upgraded to use the Vault Application Framework 2.1 runtime:
- Open the existing project in Visual Studio.
- Locate the
Solution Explorer
window, and find the VAF project within the solution. - Expand the project’s
References
node and delete the existing references to:MFiles.Crypto
MFiles.VAF
MFiles.VAF.Configuration
MFilesAPI
- Right-click on the project name and select
Manage NuGet Packages...
- Select the existing
M-Files.VAF
reference and click theUpdate
button to upgrade to the latest published 2.1 version.
It is recommended to update your entry point class (typically VaultApplication
) to use the new base class. This will require some changes to your code but is required to enable some of the new VAF 2.1 functionality. A sample on how to convert a VAF 2.0 application to VAF 2.1 is also available.
From Version 1.0 to Version 2.0
New VAF 2.0 applications can be created using the M-Files Online Visual Studio template. To upgrade an existing VAF 1.0 application to 2.0, the following steps need to be taken.
- Create a blank VAF 2.0 application from the updated template.
- From the new application, locate the
MFiles.VAF.dll
,MFiles.VAF.Configuration.dll
andMFiles.Crypto.dll
files.
- From the new application, locate the
- Open the existing VAF 1.0 application in Visual Studio:
- Update the references
- Expand the
References
node inSolution Explorer
. - Locate and delete the existing
MFiles.VAF.dll
reference. - Add a reference to
MFiles.VAF.dll
,MFiles.VAF.Configuration.dll
andMFiles.Crypto.dll
from the VAF 2.0 release. - Use nuget to update the
Newtonsoft.JSON
reference from6.0.x
to10.0.3
.
- Expand the
- Resolve any namespace issues, for example:
MFIdentifier
(and other configuration attributes) have moved fromMFiles.VAF.Common
toMFiles.VAF.Configuration
.
- Update the references
At this point the VAF application can be altered to support 2.0 features such as licensing and integration into the M-Files 2018 Administration Configuration interface.