M-Files provides developers with a Visual Studio 2017/2019 template that can be used to develop Intelligent Metadata Layer Intelligence Service components using C#.
M-Files provides developers with Visual Studio 2017/2019 templates that can be used to rapidly develop Intelligent Metadata Layer Applications using C#. The template below is part of the M-Files Visual Studio Template Package, which can be downloaded from the Visual Studio Marketplace.
Testing of Intelligent Metadata Layer components requires that you are running a version of M-Files that includes the IML Core licence component. This is typically not included in development licences.
Downloading the Template
The Intelligence Service template is part of the
M-Files Online Visual Studio template package, which can be downloaded from the Visual Studio Marketplace.
Building your first Intelligence Service
In this example we will create a basic Intelligence Service and install it into the Sample Vault, running on the local machine. Note the following differences to typical Vault Application Framework development:
- Unlike the Vault Application Framework, Intelligence Services must be manually deployed into the vault.
- Compared to the Vault Application Framework, the Visual Studio template includes significantly more boilerplate code to aid development.
Creating an application from the template
Creating a new Intelligence Service can be done from within Visual Studio by clicking
Project, then selecting
M-Files Intelligence Service From the list of Visual C# templates:
An overview of the project contents
The default project contains a number of items:
Resources\defaultConfiguration.jsonThe default JSON configuration to apply on installation.
appdef.xmlThe application manifest file, containing information such as the publisher details and the current version number.
MyApplication.csThe entry point for the application. Defines the services which the application exposes.
MyConfiguration.csThe configuration information. Configuration members are defined in the same way as Vault Application Framework 2.0 configuration.
ExtractMetadatamethod, which provides the metadata suggestions.
MyIntelligenceService.csDefines the intelligence providers which the application exposes.
MyTerms.csDefines the metadata term suggestions. Once the service is installed, terms are mapped to individual vault property definitions during configuration.
packages.confThe packages configuration file details the Nuget packages that are required for the Intelligence Service to run.
Creating an intelligence service
This tutorial will focus on the minimum required changes to implement a working intelligence service. To that end, the only required changes are to
The default contents of
MyTerms.cs defines no actual terms, but a term named
MyTerm is commented out. Start by uncommenting the declaration, and ensure that the value is also returned when
MyTerms.All is retrieved:
/// Terms are used when returning suggested properties.
/// This class is simply used to declare the terms as constants, rather than
/// having strings manually typed everywhere.
internal static class MyTerms
// Terms are used when returning suggested properties.
// TODO: Add terms as constants here.
internal const string MyTerm = "My Term";
public static string All =
// TODO: Return all the available terms here, so they're added to the suggestions in the editor.
Altering the intelligence provider
The only method that requires modification in
ExtractMetadata. This method is called automatically by the server when a new document is being added, or when the
Analyse button is clicked for any existing document.
The comments within the default implementation of
ExtractMetadata show how to interact with the incoming metadata request, including how to read the file contents either as a Stream, or as text (if available).
To create a basic, hard-coded suggestion, we can simply add the suggestion to the result. The code below will define a suggested value of “Suggested value” for the term “My Term”, and provide a confidence level of 1.
public MetadataResult ExtractMetadata(
var result = new MetadataResult();
result.Suggestions.Add( new TextValueMetadataSuggestion( MyTerms.MyTerm, "Suggested value", 1 ) );
The code above creates a suggestion using the
TextValueMetadataSuggestion class, which can then be placed into properties of type
Text. References to other items within the current vault can be returned using the
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 “Output” or “Error List” windows.
.mfappx file in the build output (
/bin/Release, by default), and use the M-Files Admin software to install it into the
Applications list (right-click on the vault name and select
Applications). The vault will require a restart once the application is installed.
To configure the Intelligence Service, expand the vault in the M-Files Admin software and select the
Configurations node. Expanding the
Intelligence Services list should show the new Intelligence Service, and selecting the
Configuration tab will allow it to be configured. At a minimum, the following needs to be checked:
Enabledmust be set to
Suggestions, add one suggestion and map our term (
My Term) to a property in the vault. In this example, the suggestion was for a text value, so the Intelligence Service has been configured to put the suggestion into the
- If any changes have been made, click
To test the Intelligence Service, open the M-Files desktop client and navigate to the vault into which the Intelligence Service is installed. Add a document through any standard means (e.g. drag and drop from the desktop), and your suggestion should be shown:
If the suggestion is not shown then check for any build/deployment errors, or for exceptions in the Windows Event Log.
Intelligence Services can be debugged in the same manner as Vault Application Framework applications:
- Place a breakpoint within the code - in this case within the background operation.
Attach to Process
- Select all the
MFAppPlatform.exeprocesses and select
Tips and tricks
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.