From 28a4ed5fd49bbff47da7682bec25c8500d8debd7 Mon Sep 17 00:00:00 2001 From: Roy <59626501+RDMacLachlan@users.noreply.github.com> Date: Tue, 25 Aug 2026 09:36:25 -0700 Subject: [PATCH 1/3] Document COM server support in MSIX packages Add focused guidance for COM server, interface, and type library manifest registration in MSIX packages. Reference ADO bug 26070760. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4b5b11f6-6bf8-4401-90b8-68f710728c8e --- msix-src/desktop/com-support.md | 165 ++++++++++++++++++++++++++++ msix-src/desktop/extend-overview.md | 3 +- msix-src/toc.yml | 2 + 3 files changed, 169 insertions(+), 1 deletion(-) create mode 100644 msix-src/desktop/com-support.md diff --git a/msix-src/desktop/com-support.md b/msix-src/desktop/com-support.md new file mode 100644 index 00000000..3ab1fb1a --- /dev/null +++ b/msix-src/desktop/com-support.md @@ -0,0 +1,165 @@ +--- +description: Learn how MSIX packages register COM servers and type libraries. +title: COM support in MSIX packages +ms.date: 08/25/2026 +ms.topic: concept-article +keywords: windows 10, windows 11, msix, com +--- + +# COM support in MSIX packages + +An MSIX package can declare COM registrations in its package manifest. Windows uses those +manifest extensions to make the COM registrations available at package deployment time instead +of requiring the installer or the packaged application to write directly to `HKCR` or `HKLM`. +The registration is serviced with the package and is removed when the package is uninstalled. + +Use this article when you need to package an existing desktop application that exposes COM +classes, COM servers, interfaces, proxy stubs, or type libraries. + +## How packaged COM registration works + +COM registrations in an MSIX package use package manifest extensions: + +- A `windows.comServer` extension registers COM servers and class registrations. With the + current `com4` schema, a `com4:ComServer` extension can contain out-of-process servers, + in-process servers, service servers, surrogate servers, class registrations, ProgIDs, and + `TreatAsClass` registrations. +- A `windows.comInterface` extension registers interface-related data. With the current + `com4` schema, a `com4:ComInterface` extension can contain `com4:Interface`, + `com4:ProxyStub`, and `com4:TypeLib` registrations. +- A `com4:TypeLib` under `com4:ComInterface` defines the type library and one or more + `com4:Version` children. The `com4` schema allows multiple `com4:Version` children + under the same type library ID. Each `com4:Version` must specify `com4:Win32Path`, + `com4:Win64Path`, or both. +- A `com4:TypeLib` under `com4:Class` or `com4:Interface` associates a class or interface + with a type library by referencing the `Id` of a `com4:TypeLib` definition. If it includes + `VersionNumber`, that value must reference a `com4:Version` under the referenced type + library. + +The `com4` schema is a superset and replacement for the older `com`, `com2`, and `com3` +syntax. Use `com4` for new Windows 11 package manifests that can depend on Windows 10 +Build 20348 or later. If your package must install on earlier Windows versions, review the +older namespace schema and validate the manifest against every target OS version. + +> [!IMPORTANT] +> Do not treat packaged COM as direct registry authoring. Packaged COM support works with +> existing COM activation APIs, but application extensions that directly read COM registry +> keys might not work because packaged COM data is stored in a private location. + +## Server and activation scenarios + +The following table summarizes common packaging decisions. + +| Scenario | Manifest registration | Notes | +| --- | --- | --- | +| Out-of-process COM server in the package | `com4:ExeServer` under `com4:ComServer` | The executable path is relative to the package root. COM servers registered in the manifest use Activate As Package behavior, so the server runs with package and application claims. | +| In-process COM DLL in the package | `com4:InProcessServer` under `com4:ComServer` | Use this only after validating the client and package scenario. In-process modules loaded into processes that aren't in the package, such as shell extensions, aren't supported. | +| Same CLSID with in-process and out-of-process registrations | Top-level `com4:Class` with server `com4:ClassReference` children | The `com4` schema supports this structure so that one class registration can be shared by multiple server registrations. | +| Interface, proxy stub, or type library | `com4:ComInterface` | Keep dependent registrations in a consistent `com4` schema. For example, an interface that uses the OLE Universal Marshaler must include a `com4:TypeLib` reference. | +| Type library for 32-bit and 64-bit clients | `com4:TypeLib` with `com4:Version`, `com4:Win32Path`, and `com4:Win64Path` | Include paths for the architectures you support. The paths are relative to the package root and must reference files in the package. | + +In multi-application packages, put COM server registrations under the correct +`Applications/Application` element. Out-of-process COM server processes run with the identity +of the ancestor `Application` element. + +## Example: in-process server, class, interface, and type library + +The following fragment shows the COM-related manifest extensions for one packaged desktop +application. Replace the GUIDs, paths, display names, ProgIDs, and interface details with +values from your COM server. + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +This example defines a 64-bit type library path. If your package supports 32-bit COM clients, +add the corresponding `com4:Win32Path` entry and include the 32-bit type library file in the +package. If your in-process DLL path differs by architecture, use the architecture-specific +`com4:InProcessServerDll` child elements instead of a single `Path` value. + +## Limitations and operational risks + +- In-process extensions loaded into processes that aren't in the MSIX package aren't + supported. This boundary affects shell extensions and similar plug-in models where an + external process loads the package's DLL. +- The `com4` schema page notes that in-process COM support is currently functionally limited + and intended for packages with external location because normal package install locations + can prevent DLLs from being loaded outside the package. Test this scenario on every target + OS and package layout. +- Out-of-process COM servers registered in the manifest use Activate As Package behavior. + Other COM activation behaviors, such as `RunAs`, aren't supported for manifest-registered + COM servers. +- Some extension visibility settings require restricted capabilities. For example, + `desktop7:CompatMode="classic"` and `desktop7:Scope="machine"` have capability + requirements. Don't add those settings unless your package is approved for the required + capability. +- If a COM client or plug-in installer directly reads or writes classic COM registry keys, + validate the scenario. Packaged COM registration is not the same as writing classic registry + keys under `HKCR` or `HKLM`. + +## Related schema and conceptual references + +- [com4:Extension](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-extension) +- [com4:ComServer](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-comserver) +- [com4:InProcessServer](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-inprocessserver) +- [com4:ExeServer](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-exeserver) +- [com4:ComInterface](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-cominterface) +- [com4:TypeLib in ComInterface](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-cominterface-typelib) +- [com4:TypeLib in Class](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-class-typelib) +- [com4:Version](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-version) +- [Prepare to package a desktop application](desktop-to-uwp-prepare.md) +- [Understanding how packaged desktop apps run on Windows](desktop-to-uwp-behind-the-scenes.md) +- [Component Object Model (COM)](/windows/win32/com/component-object-model--com--portal) + + diff --git a/msix-src/desktop/extend-overview.md b/msix-src/desktop/extend-overview.md index 8ac5387f..61008340 100644 --- a/msix-src/desktop/extend-overview.md +++ b/msix-src/desktop/extend-overview.md @@ -20,5 +20,6 @@ App extensions are also independent packages. They can be standalone apps and ca |Topic| Description | |:---|:---| |[Creating and hosting an app extension](/windows/uwp/launch-resume/how-to-create-an-extension?context=%252fwindows%252fmsix%252frender)|This section discusses how to create and host an app extension in your MSIX package. | -[Custom properties for app extensions](custom-props-app-extensions.md)|This section discusses how to use custom properties for app extensions. | +|[COM support in MSIX packages](com-support.md)|This section discusses how to declare COM servers, classes, interfaces, proxy stubs, and type libraries in the package manifest. | +|[Custom properties for app extensions](custom-props-app-extensions.md)|This section discusses how to use custom properties for app extensions. | |[Extending your app using optional packages](../package/optional-packages-with-executable-code.md)| This section discusses how to take advantage of the optional package model to load content into your main package. | diff --git a/msix-src/toc.yml b/msix-src/toc.yml index 658278a0..7fc03352 100644 --- a/msix-src/toc.yml +++ b/msix-src/toc.yml @@ -211,6 +211,8 @@ href: desktop/before-packaging-overview.md - name: Prepare to package a desktop app href: desktop/desktop-to-uwp-prepare.md + - name: COM support in MSIX packages + href: desktop/com-support.md - name: Understanding how packaged desktop apps run on Windows href: desktop/desktop-to-uwp-behind-the-scenes.md - name: Bundling MSIX packages From c62ed0d9609caaae618a1fc6b3a34780f14129e7 Mon Sep 17 00:00:00 2001 From: Roy <59626501+RDMacLachlan@users.noreply.github.com> Date: Wed, 26 Aug 2026 11:54:06 -0700 Subject: [PATCH 2/3] Address packaged COM review feedback Clarify com4 version support, complete the schema links, and remove internal notes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- msix-src/desktop/com-support.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/msix-src/desktop/com-support.md b/msix-src/desktop/com-support.md index 3ab1fb1a..1932365d 100644 --- a/msix-src/desktop/com-support.md +++ b/msix-src/desktop/com-support.md @@ -37,9 +37,12 @@ COM registrations in an MSIX package use package manifest extensions: library. The `com4` schema is a superset and replacement for the older `com`, `com2`, and `com3` -syntax. Use `com4` for new Windows 11 package manifests that can depend on Windows 10 -Build 20348 or later. If your package must install on earlier Windows versions, review the -older namespace schema and validate the manifest against every target OS version. +syntax. Its minimum supported OS version is Windows 10, build 20348. Windows 11 meets this +requirement. Use `com4` for new package manifests when your minimum supported OS meets that +requirement. If your package must install on earlier Windows versions, review the older +namespace schemas and validate the manifest against every target OS version. For the complete +set of COM schema references, see the +[package manifest schema reference](/uwp/schemas/appxpackage/uapmanifestschema/schema-root). > [!IMPORTANT] > Do not treat packaged COM as direct registry authoring. Packaged COM support works with @@ -151,6 +154,7 @@ package. If your in-process DLL path differs by architecture, use the architectu - [com4:Extension](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-extension) - [com4:ComServer](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-comserver) - [com4:InProcessServer](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-inprocessserver) +- [com4:InProcessServerDll](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-inprocessserverdll) - [com4:ExeServer](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-exeserver) - [com4:ComInterface](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-cominterface) - [com4:TypeLib in ComInterface](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-cominterface-typelib) @@ -159,7 +163,3 @@ package. If your in-process DLL path differs by architecture, use the architectu - [Prepare to package a desktop application](desktop-to-uwp-prepare.md) - [Understanding how packaged desktop apps run on Windows](desktop-to-uwp-behind-the-scenes.md) - [Component Object Model (COM)](/windows/win32/com/component-object-model--com--portal) - - From b651193520bea31dfe3b5a7a5ea1aad8d6e19386 Mon Sep 17 00:00:00 2001 From: Roy <59626501+RDMacLachlan@users.noreply.github.com> Date: Thu, 27 Aug 2026 15:11:29 -0700 Subject: [PATCH 3/3] Clarify com4 minimum OS version and cite schema reference Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 485b92b6-ded3-49ac-8734-e0badb78eb39 --- msix-src/desktop/com-support.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/msix-src/desktop/com-support.md b/msix-src/desktop/com-support.md index 1932365d..f3b530a3 100644 --- a/msix-src/desktop/com-support.md +++ b/msix-src/desktop/com-support.md @@ -1,7 +1,7 @@ --- description: Learn how MSIX packages register COM servers and type libraries. title: COM support in MSIX packages -ms.date: 08/25/2026 +ms.date: 08/27/2026 ms.topic: concept-article keywords: windows 10, windows 11, msix, com --- @@ -37,9 +37,10 @@ COM registrations in an MSIX package use package manifest extensions: library. The `com4` schema is a superset and replacement for the older `com`, `com2`, and `com3` -syntax. Its minimum supported OS version is Windows 10, build 20348. Windows 11 meets this -requirement. Use `com4` for new package manifests when your minimum supported OS meets that -requirement. If your package must install on earlier Windows versions, review the older +syntax. As listed in the [`com4:Extension` schema reference](/uwp/schemas/appxpackage/uapmanifestschema/element-com4-extension), +its minimum supported OS version is Windows 10, build 20348 (the Windows Server 2022 build), +and Windows 11 meets this requirement. Use `com4` for new package manifests when your app +targets Windows 11 or later. If your package must install on earlier Windows versions, review the older namespace schemas and validate the manifest against every target OS version. For the complete set of COM schema references, see the [package manifest schema reference](/uwp/schemas/appxpackage/uapmanifestschema/schema-root).