diff --git a/msix-src/desktop/com-support.md b/msix-src/desktop/com-support.md new file mode 100644 index 00000000..f3b530a3 --- /dev/null +++ b/msix-src/desktop/com-support.md @@ -0,0 +1,166 @@ +--- +description: Learn how MSIX packages register COM servers and type libraries. +title: COM support in MSIX packages +ms.date: 08/27/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. 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). + +> [!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: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) +- [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