WinMIDL 0.1.16

WinMIDL — Microsoft Interface Definition Language Compiler

A modern, fast, editor-friendly MIDL compiler. Ships as a single ~5.5 MB native executable — no .NET runtime required.

Overview

WinMIDL is a ground-up rewrite of the Microsoft MIDL compiler. It compiles MIDL3 (and classic MIDL) source into Windows Metadata, C/C++ headers, IID files, and custom proxy/stub code for COM marshaling — all from a single self-contained binary.

Outputs

The same binary also serves as an LSP server — editor extensions for VS Code and Visual Studio ship with it bundled.

Quick Start

# Compile a MIDL file (header + IIDs)
Midl.Cli /winrt /h Widget.h /iid Widget_i.c Widget.idl

# Generate Windows Metadata
Midl.Cli /winmd Widget.winmd Widget.idl

# Generate proxy/stub code for COM marshaling
Midl.Cli /winrt /h Widget.h /iid Widget_i.c /cppproxy Widget_proxy.cpp Widget.idl

# Decompile a .winmd back to IDL
Midl.Cli --decompile Windows.Foundation.winmd

# Inspect WinMD metadata tables
Midl.Cli --dump-winmd Widget.winmd

# Syntax check only (no output)
Midl.Cli /Zs Widget.idl

# Analyze with diagnostics
Midl.Cli --analyze Widget.idl

Editor Extensions

VS Code

Install the MIDL Language Support extension from a .vsix package:

code --install-extension midl-language.vsix

Visual Studio

Install the WinMIDL extension for Visual Studio 2022+:

VSIXInstaller.exe Midl.VsExtension.vsix

Both extensions bundle the compiler binary (x64 + ARM64) and provide:

Command-Line Reference

Midl.Cli [switches] <input.idl>

Key Switches

Generating Windows Metadata (WinMD)

Use the /winmd switch to emit a .winmd file from your IDL:

# Generate a .winmd file (implicitly enables /winrt mode)
Midl.Cli /winmd output.winmd input.idl

# Generate both header and WinMD
Midl.Cli /winrt /h output.h /winmd output.winmd input.idl

The emitter produces spec-compliant WinMD files with:

• Full attribute emission — [contract], [activatable], [composable], [static], [deprecated], [threading], [marshaling_behavior], [version], [experimental], [noexcept], [remote_async], [attributeusage], and user-defined attributes
• Correct version encoding — integer versions encoded as (major << 16) | minor, hex passthrough, major.minor notation
• ApiContract types — emitted as structs with [ApiContract] and [ContractVersion] attributes
• Custom attribute types — emitted with [AttributeUsageAttribute] using CLR System.AttributeTargets flags (matching MIDL.exe behavior)
• Deterministic GUIDs — synthesized interfaces get stable UUIDs derived from their ABI signature

Inspecting WinMD Files

# Dump metadata tables (types, methods, attributes)
Midl.Cli --dump-winmd output.winmd

# Decompile back to IDL
Midl.Cli --decompile output.winmd

Custom Proxy/Stub Code Generation

WinMIDL can generate custom C++ proxy/stub code for COM marshaling, replacing the traditional MIDL-generated NDR stubs with compiled, type-safe serialization.

# Generate header, IID file, and proxy/stub C++ code
Midl.Cli /winrt /h Widget.h /iid Widget_i.c /cppproxy Widget_proxy.cpp Widget.idl

What's Generated

Building a Proxy/Stub DLL

The generated proxy code compiles into a standard COM proxy/stub DLL:

# Compile the proxy/stub DLL (MSVC)
cl /nologo /std:c++latest /EHsc /LD ^
    Widget_proxy.cpp Widget_i.c dlldata.c ^
    /I path/to/winmidl/include ^
    ole32.lib oleaut32.lib rpcrt4.lib ^
    /link /DEF:proxy.def /OUT:Widget_proxy.dll

# Register for in-process marshaling
regsvr32 Widget_proxy.dll

Runtime Headers

The proxy code depends on include/winmidl/proxy_helpers.h which provides:

• Zero-copy GetRuntimeClassName using WindowsCreateStringReference
• marshal_interface / unmarshal_interface with typed IID + IID_IUnknown fallback
• HSTRING serialization helpers
• EventRegistrationToken marshaling
• Struct and array serialization

Supported Marshaling Patterns

• Primitives — all WinRT value types, HSTRING, GUID, EventRegistrationToken
• Structs — nested structs with correct alignment
• Interfaces — with typed IID marshaling and IID_IUnknown fallback for system objects
• Delegates — typed callback proxies with event registration
• Enums and flags
• Out parameters — including interface out params with cleanup
• Properties — get/set with full round-trip
• Events — add/remove with EventRegistrationToken
• Multiple interfaces — QI, GetIids, inheritance chains

See docs/marshaling-architecture.md and docs/payload-format-spec.md for the full design.

Project Configuration (winmidl.json)

For multi-file projects, create a winmidl.json in your project root:

{
    "inputs": ["src/Widget.idl", "src/Helper.idl"],
    "references": ["lib/MyLibrary.winmd"],
    "defines": ["FEATURE_X"],
    "includePaths": ["include"],
    "noSdk": false
}

The LSP discovers this file automatically, enabling cross-file symbol resolution, autocomplete, and diagnostics. For lightweight per-file hints, use // @ref: other.idl at the top of your source.

See docs/winmidl-json.md for the full specification.

Supported MIDL3 Syntax

• Namespaces — nested and dotted
• Runtime classes — static, partial, unsealed, base types, interface requires
• Interfaces — including requires clauses
• Delegates
• Structs and enums (including [flags])
• API contracts and versioned blocks
• Events, properties, and constructors
• Generics — parameterized interfaces and delegates
• Modern built-in types — String, Boolean, Int32, IVector<T>, etc.
• Custom attributes — user-defined attribute types with [attributeusage]

Links

• Diagnostics Reference
• Marshaling Architecture
• Payload Format Spec
• Project Configuration (winmidl.json)
• MIDL3 Documentation

Building from Source

dotnet build
dotnet test

See CONTRIBUTING.md for prerequisites, project structure, and development workflow. See docs/architecture.md for compiler internals and design.

License

© Microsoft Corporation. All rights reserved.