[Windows] Define native ABI and versioning policy #4

Activity

1. richiemsft

   added

   enhancementNew feature or requestNew feature or request

   on Sep 16, 2026
2. richiemsft commented on Sep 17, 2026

   

   richiemsft

   on Sep 17, 2026

   Last edited by richiemsft

   OwnerAuthor

   More actions

   The Windows guide now documents the selected application/API boundary in commit ab04ac4:

   • Matter.Windows.Controller (matter.winrt) is the versioned application-facing WinRT API.
   • Matter SDK C++ types and symbols remain internal and are not a supported application ABI.
   • Preview applications must deploy the native DLL from the exact NuGet package used at build time; compatibility is not promised between preview versions.
   • Stable packages will use semantic versioning: additive APIs increment the minor version and breaking changes require a new major version.
   • Each package pins a Matter SDK commit; SDK updates require a package version change and x64/ARM64 component and sample validation.
   • The native DLL exposes only the standard WinRT activation exports.

   The implementation and fuller package policy are proposed upstream in dotMorten/matter.winrt#1: dotMorten/matter.winrt#1

   This establishes the preview policy. The issue should remain open until a stable package adds automated WinMD compatibility validation and a formal servicing/deprecation process.
3. richiemsft commented on Sep 17, 2026

   

   richiemsft

   on Sep 17, 2026

   OwnerAuthor

   More actions

   The application-facing API policy is now implemented and published in Matter.Windows.Controller v0.1.0-preview.6.

   The release provides one versioned NuGet package containing the WinRT metadata and native x64/ARM64 DLLs. Preview applications must deploy the native DLL from this exact package version; Matter SDK C++ symbols remain outside the supported application ABI.

   Package SHA-256: 8DC16FB9707BADB8BAAF4CDCA4FB590FDDB12D55FA3796B7FE8EC4F4C4B02334

   The remaining work before closing this issue is stable WinMD/export compatibility automation and a formal servicing/deprecation policy.
4. richiemsft

   closed this as completedin dotMorten/matter.winrt#2on Sep 17, 2026
5. richiemsft commented on Sep 17, 2026

   

   richiemsft

   on Sep 17, 2026

   OwnerAuthor

   More actions

   The remaining compatibility work is now complete:

   • dotMorten/matter.winrt#2 added the formal versioning, compatibility, deprecation, and servicing policy plus WinMD/native-export validation.
   • dotMorten/matter.winrt#3 corrected clean Release sample restore and the ABI workflow invocation.
   • Windows run 35285501309 passed x64/ARM64 package builds, both Release sample consumers with ReadyToRun enabled, checksum-pinned baseline download, 48-declaration WinMD compatibility validation, cross-architecture metadata validation, native export validation, and artifact upload.

   The enforced public native exports are DllCanUnloadNow and DllGetActivationFactory. Existing stable WinRT interfaces cannot change; additive metadata follows semantic versioning; namespace moves and removed metadata fail validation. VERSIONING.md defines preview/stable compatibility, deprecation timing, servicing windows, and Matter SDK pin-update requirements.