M-Files UI Extension Template

A template project for developing M-Files extensions with both UI Extensibility Framework v2 (Frontend) and Vault Application Framework (Backend) components. Designed for AI-assisted development with GitHub Copilot, Claude, and other AI coding agents.

Project Structure

Uixv2Template/
├── AGENTS.md                             # Agent instructions (identical copy)
├── CLAUDE.md                             # Agent instructions (identical copy)
├── GEMINI.md                             # Agent instructions (identical copy)
├── .github/                              # GitHub configuration
│   ├── copilot-instructions.md          # Agent instructions (identical copy)
│   └── skills/                           # AI-optimized documentation
│       └── uix2-app/                     # UIX2 development skill
│           ├── SKILL.md                  # AI quick reference (start here)
│           └── references/               # Detailed documentation
│
├── src/                                    # Source code directory
│   ├── Backend/                           # VAF Backend Components
│   │   └── TemplateApp.VAF/              # Vault Application Framework backend
│   │       ├── TemplateApp.VAF.csproj    # SDK-style project file
│   │       ├── appdef.xml                # VAF application definition
│   │       ├── VaultApplication.cs       # Main VAF application class
│   │       └── Configuration.cs          # Configuration class
│   │
│   ├── Frontend/                          # UI Extensibility v2 Frontend
│   │   └── TemplateApp.UIExt/            # UI Extension v2 application
│   │       ├── appdef.xml                # UI Extension definition
│   │       ├── main.js                   # Main JavaScript entry point
│   │       ├── dashboard.html            # Dashboard HTML template
│   │       ├── dashboard-react.html      # Optional React dashboard bridge
│   │       ├── dashboard.js             # Dashboard handler
│   │       ├── styles.css                # Styling
│   │       ├── build-package.ps1         # Frontend build script
│   │       ├── package.json              # NPM config (ESLint)
│   │       ├── eslint.config.mjs         # ESLint flat config
│   │       └── react-dashboard/          # Optional Vite + React reference
│   │
│   └── Legacy/                            # Reference for v1 migration projects
│       └── README.md                     # Usage instructions (empty if fresh start)
│
├── build/                                # Build artifacts
│   ├── scripts/                         # PowerShell build scripts
│   │   ├── build-complete-solution.ps1
│   │   ├── build-frontend-only.ps1
│   │   ├── build-and-deploy-frontend.ps1
│   │   ├── install-application.user.json
│   │   └── install-complete-solution.ps1
│   ├── output/                          # Build output directory
│
├── docs/                                # Documentation
│   ├── eslint-setup.md                  # JavaScript validation guide
│   └── M-FILES-UIEXT-GUIDE.md          # UI Extension development guide
│
├── Uixv2Template.sln                   # Visual Studio solution
└── README.md                           # This file

Components

Backend: TemplateApp.VAF (Optional)

Note: The Backend VAF component is not always necessary. Only include it when you need:

• Server-side processing or offloading heavy operations
• Access to functionality restricted by UI Extension v2 sandbox limitations
• Background tasks, scheduled operations, or event handlers
• Direct vault operations not exposed through the client API

For simple UI customizations (menus, commands, dashboards), the Frontend alone may be sufficient.

• Location: src/Backend/TemplateApp.VAF/
• Purpose: Server-side Vault Application Framework backend
• Technology: C# .NET Framework 4.8, M-Files VAF
• Features:
  • Modern SDK-style project format
  • Automatic .mfappx package generation
  • Configurable vault extension methods
  • Event handler templates
  • Multi-Server-Mode-compatible baseline (multi-server-compatible=true)

Frontend: TemplateApp.UIExt

• Location: src/Frontend/TemplateApp.UIExt/
• Purpose: Client-side UI Extension with modern interface
• Technology: JavaScript ES6+, HTML5, CSS3
• Reference: UI Extensibility Framework v2 Documentation
• Features:
  • Shell UI module template
  • Vanilla JavaScript dashboard template for the default path
  • Optional React parity dashboard reference
  • ESLint validation configured
  • M-Files API patterns

Getting Started

Prerequisites

• Visual Studio 2019+ or VS Code
• .NET Framework 4.8 SDK
• M-Files Server (23.1 or later for full compatibility)
• PowerShell 5.1+
• Node.js (for ESLint validation)

Quick Start

1. Clone or copy this template

2. Customize the application:

   • Update GUIDs in appdef.xml files (generate new ones!)
   • Rename project namespaces if desired
   • Update publisher and copyright information

3. Build the solution:

   powershell.exe -NoProfile -ExecutionPolicy Bypass -File "build/scripts/build-complete-solution.ps1" -Configuration Debug

   Add -IncludeBackend if you need the VAF package too.

   If you include the backend, keep it safe for M-Files Multi-Server Mode: no in-memory shared state, no VAF background operations, use Named Value Storage or vault metadata for shared state, and use task queues for deferred work.

4. Deploy to M-Files:

   • Configure vault name in build/scripts/install-application.user.json
   • Run the installation script or manually install via M-Files Admin

Build Scripts

All build scripts are in build/scripts/:

Script	Purpose
build-complete-solution.ps1	Full solution build with output to build/output/
build-frontend-only.ps1	Frontend-only build (for UI development)
build-and-deploy-frontend.ps1	Build and auto-deploy frontend
install-complete-solution.ps1	Install frontend and optional backend to vault

Usage Examples

# Full solution build
.\build\scripts\build-complete-solution.ps1

# Frontend-only (faster for UI changes)
.\build\scripts\build-frontend-only.ps1

# Frontend-only with optional React reference dashboard bundle
.\build\scripts\build-frontend-only.ps1 -IncludeReactReference

# Frontend with deployment
.\build\scripts\build-and-deploy-frontend.ps1

# Frontend with optional React reference dashboard bundle + deployment
.\build\scripts\build-and-deploy-frontend.ps1 -IncludeReactReference

Development Workflow

Backend (VAF) Development

1. Edit C# files in src/Backend/TemplateApp.VAF/
2. Build backend: dotnet build src/Backend/TemplateApp.VAF/TemplateApp.VAF.csproj
3. To auto-install after build, opt in explicitly: dotnet build src/Backend/TemplateApp.VAF/TemplateApp.VAF.csproj /p:AutoInstall=true
4. Backend deployment requires vault restart

The template backend is marked multi-server-compatible=true by default. Keep backend code compatible with M-Files Multi-Server Mode: no in-memory shared state, no VAF background operations, use Named Value Storage or vault metadata for shared state, and use task queues for deferred work.

Frontend (UI Extension) Development

1. Edit JavaScript/HTML/CSS in src/Frontend/TemplateApp.UIExt/
2. Validate with ESLint: npm run lint
3. Build package: .\build-package.ps1
4. Deploy to vault (no restart needed for UI extensions)

The shipped default is the vanilla JavaScript dashboard. That path should cover many common UIX2 use cases, stays the easiest to debug, and should generally follow the native M-Files sample/client visual language unless a custom direction is explicitly requested.

For an optional React parity sample that renders the same CustomData payload as the vanilla dashboard, build with -IncludeReactReference and temporarily switch DASHBOARD_ID in main.js to DASHBOARD_IDS.REACT_REFERENCE. The React dashboard manifest entries are injected only into React-inclusive packages, so the default build remains vanilla-only.

Quick Deployment

Use the standardized build scripts for deployment:

# Build and deploy frontend (recommended)
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "build/scripts/build-and-deploy-frontend.ps1"

# Build only (no deploy)
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "build/scripts/build-and-deploy-frontend.ps1" -BuildOnly

Notes:

• Configure target vault in build/scripts/install-application.user.json
• UI Extensions don't require vault restart after deployment
• Increment version in appdef.xml before each deployment
• If browser dev tools still warn that the dashboard iframe has both allow-scripts and allow-same-origin, verify the packaged appdef.xml first. This template now packages sandbox="allow-scripts" for the default dashboard, so that warning may come from M-Files runtime iframe behavior rather than the manifest we ship.

JavaScript Validation

cd src/Frontend/TemplateApp.UIExt
npm install        # First time only
npm run lint       # Validate JavaScript
npm run lint:fix   # Auto-fix issues

Configuration

Vault Connection

Edit build/scripts/install-application.user.json (ships with default Sample Vault):

{
  "VaultConnections": [
    {
      "vaultName": "Sample Vault",
      "networkAddress": "localhost"
    }
  ]
}

Version Management

Update version in appdef.xml to force M-Files to recognize changes:

<version>1.0.1</version>

AI-Assisted Development

This template is optimized for AI coding assistants:

• Clear separation between Backend and Frontend
• Well-documented code patterns
• ESLint configured for M-Files globals
• Comprehensive documentation in docs/
• Tool-agnostic agent instructions: CLAUDE.md, GEMINI.md, AGENTS.md, and .github/copilot-instructions.md are four identical copies of the same guidance, so any AI tool (Claude, Gemini, Copilot, Codex, …) gets the full picture. When you edit one, copy it over the other three and run build/scripts/verify-instruction-sync.ps1 (it fails if they diverge).
• AI Skills in .github/skills/uix2-app/ for UIX2 development

AI Skills Reference

The .github/skills/uix2-app/ folder contains AI-optimized documentation:

File	Purpose
SKILL.md	AI quick reference - 30+ task mappings, constraints, API tables
references/concepts.md	Core architecture and mental models
references/common-tasks.md	Task-to-API cookbook with project examples
references/troubleshooting.md	Common errors and debugging
references/migration-uix1.md	UIX v1 to v2 migration guide
references/packaging.md	Manifest and deployment guidance
references/react-dashboard.md	React dashboard implementation guide

For AI agents: Load SKILL.md first for UIX2 tasks.

Tips for AI Agents

• Frontend JavaScript validation requires ESLint, not VS build
• VAF methods are called via VaultExtensionMethodsOperations.RunExtensionMethod (UIX v2)
• Access selected items via selectedItems.ObjectVersions[i] (array, not Item() method)
• Object IDs use obj_id.item_id.internal_id, versions use version.internal_version
• Dashboard vault access: dashboard.ShellFrame.ShellUI.Vault
• Always increment version for deployment verification

Documentation

• ESLint Setup - JavaScript validation configuration
• M-Files UI Extension Guide - Supplementary UIX2 development guide
• Prompt Cookbook - Startup prompts for migration and other agent-driven workflows

Resources

• M-Files Developer Portal
• VAF Documentation
• UI Extensibility Framework
• UIX2 Skill - Primary repo-specific UIX2 reference
• UIX1→UIX2 Migration Skill - Primary migration workflow reference
• Migration Analyzer and Verifier - uix_analyzer.js for archive discovery and verify_ts_output.js for post-conversion validation

License

This repository is licensed under the MIT License.

It is provided "as is", without warranty of any kind. See LICENSE for the full text.