Visual Studio Template for building External Repository Connectors

Overview

M-Files provides developers with a Visual Studio 2017/2019 template that can be used to develop Intelligent Metadata Layer External Repository Connectors 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 External Repository Connector template is part of the M-Files Online Visual Studio template package, which can be downloaded from the Visual Studio Marketplace.

Building your first External Repository Connector

In this example we will create a basic External Repository Connector and install it into the Sample Vault, running on the local machine. Note the following differences to typical Vault Application Framework development:

Creating an application from the template

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

Creating a new project

An overview of the project contents

The project contents

The default project contains a number of items:

Connectors, connections and sessions

It is important to highlight the difference between connectors, connections and sessions; each have a specific part to play in the operation of the External Repository Connector.

Creating an external repository connector

The Visual Studio Template project includes a dummy connector which exposes information held in a set of in-memory objects. This tutorial will deal with building and running the dummy implementation.

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.

Locate the .mfappx file in the build output (/bin/Debug, or /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.

Installing the External Repository Connector

Configuring

To configure the External Repository Connector, expand the vault in the M-Files Admin software and select the Configurations node. Expanding the External Repositories list should show the new External Repository Connector. Click on the name of the connector and select Add Connection from the dashboard screen. The new connection can be configured by selecting the connection on the left, and selecting the Configuration tab. At a minimum, the following needs to be checked:

Configuring the External Repository Connector

Testing

To test the External Repository Connector, open the M-Files desktop client and navigate to the vault into which the connector is installed. The new connection should appear in the External Views section:

The connection

If the connection is not shown then check for any build/deployment errors, or for exceptions in the Windows Event Log.

Navigating into the folder structure should show sub-folders and objects:

The connection

Debugging

Intelligence Services can be debugged in the same manner as Vault Application Framework applications:

  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.

Breakpoint hit

Tips and tricks

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>).