Versions

Feature Compatibility Matrix

Feature / Version 1.0 2.0 2.1 2.2 2.3 22.12 24.1
Minimum M-Files Server Version 2015 2015.3 19.9 20.5 20.5 22.3 23.6
Minimum .NET Framework Version 4.5 4.5 4.5 4.5 4.5 4.7.2 4.7.2
Automatic State Transitions Yes Yes Yes Yes Yes Yes Yes
Background Operations Yes Yes Yes Yes Yes Yes Yes
Configuration Yes Yes Yes Yes Yes Yes Yes
Configuration commands and buttons - - Yes Yes Yes Yes Yes
Event Handlers Yes Yes Yes Yes Yes Yes Yes
File helpers - Yes Yes Yes Yes Yes Yes
Licensing - Yes Yes Yes Yes Yes Yes
Logging - - - - - Yes* Yes
ObjVerEx Yes Yes Yes Yes Yes Yes Yes
Property Calculation Yes Yes Yes Yes Yes Yes Yes
Property Validation Yes Yes Yes Yes Yes Yes Yes
Search helpers Yes Yes Yes Yes Yes Yes Yes
System helpers Yes Yes Yes Yes Yes Yes Yes
Url helpers - Yes Yes Yes Yes Yes Yes
Vault Extension Methods Yes Yes Yes Yes Yes Yes Yes
Workflow Pre- and Post-Conditions Yes Yes Yes Yes Yes Yes Yes
Workflow State Actions Yes Yes Yes Yes Yes Yes Yes
Multi-Server Mode helpers - - - Yes Yes Yes Yes

Version 22.12

This release brings a number of changes:

It is strongly recommended that you consider using the open-source VAF Extensions package. This will ensure that common functionality such as logging is correctly configured, provides useful short-hand helper methods for common functionality, as well as providing useful “dashboard” functionality such as exposing task queues. More details on the functionality in the library is available in its GitHub repository.

Version 22.12 Logging

Version 22.12 brings significant amounts of the Vault Application Logging framework into the VAF itself. For developers not using the VAF Extensions, note that the separate MFiles.VAF.Configuration.Logging.NLog package is needed.

If you are using the logging library then note that some method signatures have changed. More details are below.

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:

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:

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:

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.3 to Version 22.12

  1. Ensure that your vault application is targeting .NET Framework 4.7.2 or 4.8. To do this, right-click on the project in Visual Studio and select Properties and change the target framework version.
  2. Follow the instructions below to update the reference. This depends on whether you are using the VAF Extensions or not.
  3. The namespace MFiles.VaultApplication.Logging has changed to MFiles.VAF.Configuration.Logging. Change any using statements to use the new namespace location.
  4. Note that the basic string-based logging methods (e.g. Logger.Info("hello {0}", worldVar);) are no longer available, and interpolated strings should be used instead (e.g. Logger.Info($"hello {worldVar}")).

If using VAF Extensions

  1. Ensure you have undertaken step 1 above.
  2. Right-click on the project in Visual Studio and select Manage NuGet references.... Within the “Installed” tab, locate the VAF Extensions reference and upgrade it to the latest release (>=22.12.52). This will upgrade other referenced packages at the same time.
  3. If, after upgrading the VAF Extensions, the M-Files Vault Application Logging Framework is also still installed, uninstall it.
  4. Continue from step 3 above.

If not using VAF Extensions

The VAF Extensions library automatically wires up a lot of logging functionality. It is recommended that you use this library instead of implementing it manually. The below is included for reference only.

  1. Ensure you have undertaken step 1 above.
  2. Right-click on the project in Visual Studio and select Manage NuGet references.... Within the “Installed” tab:
    • Locate the installed M-Files Vault Application Logging framework and remove it.
    • Locate the M-Files VAF reference and upgrade it to the latest release (>=22.12).
    • Search for the MFiles.VAF.Configuration.Logging.NLog package and install it.
  3. Within your project, create a log manager and return the default sensitivity filters. An example is shown below.
  4. Locate your VaultApplication class’s default constructor (or add one) and ensure that the LogManager.Current instance is set to an instance of your log manager.
  5. Continue from step 3 above.
Example log manager
using MFiles.VAF.AppTasks;
using MFiles.VAF.Configuration;
using MFiles.VAF.Configuration.Logging;
using MFiles.VAF.Configuration.Logging.NLog;
using MFiles.VAF.Extensions.Logging.Sensitivity.Filters;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace MyVaultApplication
{
	public class MyLogManager
		: NLogLogManager
	{
		/// <summary>
		/// Returns the default sensitivity filters to be used by this log manager.
		/// </summary>
		/// <returns>The default list of sensitivity filters.</returns>
		public override List<ILogSensitivityFilter> GetDefaultSensitivityFilters()
		{
			// Extend defaults with those from VAF.
			List<ILogSensitivityFilter> filters = base.GetDefaultSensitivityFilters();
			filters.Add(new EventHandlerEnvironmentLogSensitivityFilter());
			filters.Add(new TaskManagerEventArgsSensitivityFilter());
			filters.Add(new ObjVerExLogSensitivityFilter());
			return filters;
		}

		/// <summary>
		/// Returns the default properties that should be exposed as layout renderers by this log manager.
		/// </summary>
		/// <returns>The default properties.</returns>
		public override List<string> GetDefaultMFilesScopePropertiesForLayout()
		{
			// Extend defaults with those from VAF.
			List<string> props = base.GetDefaultMFilesScopePropertiesForLayout();
			props.Add(AppTaskLogContextKeys.TaskQueue);
			props.Add(AppTaskLogContextKeys.TaskType);
			props.Add(AppTaskLogContextKeys.TaskId);
			props.Add(AppTaskLogContextKeys.BroadcastIds);
			return props;
		}
	}
}

Example of how to set LogManager.Current
public VaultApplication()
{
	MFiles.VAF.Configuration.Logging.LogManager.Current = new MyLogManager();
}

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:

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:

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:

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.

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.