M-Files provides partners with a Visual Studio 2015/2017/2019 template that can be used to rapidly develop Vault Application Framework Applications using C#. If you would like to use VB.NET then you will need to follow these instructions.

When installing the template into Visual Studio 2017 and 2019, a popup will be shown stating that the template does not use the 2017 format. This is expected, as the template is backwards compatible with Visual Studio 2015 as well. Simply accept the popup and continue installation.

Downloading the Template

The template can be downloaded from the M-Files Partner Portal, which is available to all M-Files Partners. If you are a partner and do not have access to the M-Files Partner Portal, then please contact your Channel Account Manager. To install the template, simply double-click on the “.vsix” file, which will then guide you through installing the template into the version of Visual Studio that you have installed.

Building your first application (“hello, world”)

In this example we will create a basic Vault Application Framework application and install it into the Sample Vault, running on the local machine.

If you do not have M-Files installed on the same machine as Visual Studio, then you must deploy the zip file manually. Debugging can be undertaken on remote applications by following these instructions.

Creating an application from the template

Creating a new Vault Application Framework application can be done from within Visual Studio by clicking File, New, Project, then selecting M-Files Vault Application From the list of Visual C# templates:

An overview of the project contents

The default project contains a number of items:

• src\VaultApplication.cs The actual Vault Application Framework application.
• appdef.xml The application manifest file, containing information such as the publisher details and the current version number.
• MFVaultApplicationInstaller.exe Used by the build event to create the installation package and, optionally, to deploy it to the local M-Files server.
• packages.conf The packages configuration file details the Nuget packages that are required for the Vault Application Framework to run.

The default application

The default application consists of two classes. The first, Configuration, contains a single MFIdentifier field describing a class with alias FailAlias. The second, VaultApplication, contains a sample vault application which defines a method which runs every 10 seconds. This method calls a Vault Extension Method which is also defined within the class.

When this code is executed it should output an entry to the Windows Event Log every 10 seconds containing the phrase Hello from MFVaultApplication1: TestClassAlias: -1. Note that “MFVaultApplication” is the name of the vault application, “TestClassAlias” is the alias provided to the MFIdentifier when the configuration is instantiated, and “-1” is the ID of the class in the vault with the alias “TestClassAlias” (if one existed - if not it returns -1).

Items to note

1. Attributes are used before properties and methods to define how the Vault Application Framework should interact with them.
   1. The MFClass attribute within the Configuration class denotes that the MFIdentifier refers to a class (rather than a property definition, object type, or other vault element.)
   2. The use of the MFConfiguration attribute persists the configuration to Named Value Storage. The attribute is provided with the namespace and key of the configuration item. Further information can be found within the Configuration attribute documentation.
2. The SysUtils helper object is used to report information to the event log.
3. The “Permanent Vault” (this.PermanentVault) is used within the background operation. This should only be used where a transactional vault is not provided by the Vault Application Framework.

Adjusting the build event

Details on the build event can be found by viewing the project properties (right-click on MFVaultApplication, or the name of your project, and select Properties) and selecting the Build Events tab on the left:

By default, the post-build event command line is set to the following: start "Installing Vault Application" /D "$(TargetDir)" "MFVaultApplicationInstaller.exe" "Sample Vault"

This instructs Visual Studio, after the build process has completed, to execute the M-Files Vault Application Installer. This installer will create a zip file within the output folder and then attempt to deploy the application to the vault named “Sample Vault”. This can be altered to the name of the vault you wish to install to. For example, the following will instruct the installer to deploy the application into a vault named “My Test Vault”. start "Installing Vault Application" /D "$(TargetDir)" "MFVaultApplicationInstaller.exe" "My Test Vault"

The name passed to the installer is the name of the vault on the server, not the name of the vault configured within the M-Files Desktop Settings application.

If you do not have an M-Files server running locally, the build event command line can be altered to avoid the deploy step. In this scenario the application zip will still be created, and the path to the zip output for manual deployment. This is done by simply removing the final argument from the command line: start "Installing Vault Application" /D "$(TargetDir)" "MFVaultApplicationInstaller.exe"

Building and deploying

To build and deploy the project, either select the Build menu item within Visual Studio and select Build Solution, or press F6, or press Ctrl-Shift-B. Any errors during build will be shown within the Visual Studio “Error List” window, and any errors during the deployment will be shown within the console window opened for the build task:

This screen shows the full path to the zip file created by the installer. If you are deploying the application manually, copy this file to the M-Files server and install using the M-Files Admin software.

Observing the output

Once the Vault Application Framework application has been successfully installed, it can be checked using the Windows Event Log:

Debugging

Debugging Vault Application Framework applications is relatively straight-forward:

1. Place a breakpoint within the code - in this case within the background operation.
2. Select Debug and select Attach to Process
3. Select all the MFAppPlatform.exe processes and select Attach.

Tips and tricks

Manual deployment

If you do not have an M-Files server running on your local machine, then the build event command cannot automatically deploy your code to the vault. In this instance, you must manually copy the zip file created by the build event to the server, and install it using the M-Files Admin software.

Nuget packages and versions

The current Vault Application Framework release (1.0.128.0) requires Newtonsoft.Json (JSON.NET) version 6.0.8. If this is upgraded to a later version then your Vault Application Framework application will not correctly load.

Application GUIDs

Whenever an application is created from the Visual Studio template, the <guid></guid> element in appdef.xml is automatically set to be a new Globally Unique IDentifier. This GUID is used to uniquely identify each application, as each M-Files vault can only have one application with each GUID installed.

If you manually create an appdef.xml file, or copy it from another location, you must ensure that the guid is altered to be unique. There are a number of online tools that can be used to generate GUIDs. Note that the GUID should be entered into the <guid></guid> element without braces, but with hyphens (e.g. <guid>f7fbe39a-2031-4b42-9856-05444ecce446</guid>).