microsoft
Documentation on AppXManifest COM Schema for Com:ComInterface
Describe the bug
The documentation for COM:ComInterface https://learn.microsoft.com/en-us/uwp/schemas/appxpackage/uapmanifestschema/element-com-cominterface and the chain below them are shown as a child of the COM:Extension under an Application. This likely stems from the COM:Extension documentation showing it only as an Application extension when it can be either an Application level extension or a Package level extension, depending on its contents.
The Package-level COM:Extension is used to define typelibs, interfaces, and proxystubs. The SDK schema files confirm this. Microsoft's MSIX Packaging Tool always creates them this way, MakeAppx/MakeMsix utilities also support them this way.
As I see it, at least the following documentation pages need updating:
- https://learn.microsoft.com/en-us/uwp/schemas/appxpackage/uapmanifestschema/element-com-extension
- https://learn.microsoft.com/en-us/uwp/schemas/appxpackage/uapmanifestschema/element-com-cominterface
- https://learn.microsoft.com/en-us/uwp/schemas/appxpackage/uapmanifestschema/element-com-proxystub
- https://learn.microsoft.com/en-us/uwp/schemas/appxpackage/uapmanifestschema/element-com2-proxystubdll (Also check title on that page as it says COM when it is COM2)
- https://learn.microsoft.com/en-us/uwp/schemas/appxpackage/uapmanifestschema/element-com-interface
- https://learn.microsoft.com/en-us/uwp/schemas/appxpackage/uapmanifestschema/element-com-typelib
- https://learn.microsoft.com/en-us/uwp/schemas/appxpackage/uapmanifestschema/element-com-version
- https://learn.microsoft.com/en-us/uwp/schemas/appxpackage/uapmanifestschema/element-com-win32path
- https://learn.microsoft.com/en-us/uwp/schemas/appxpackage/uapmanifestschema/element-com-win64path
Some of the elements might have dual use both under Application and Package level in certain scenarios.
Quite possibly the COM4:ComInterface also needs some reviewing, but I'm not trying to work with it currently.
I am pretty sure that I reported this as an issue on the direct page back when we reported issues that way several years ago (probably Drew might remember it) but it was never resolved.
Steps to reproduce the bug
Review the COM schema files for the AppXManifest from the SDK. Look at the referenced documentation pages for hierarchy structure.
Expected behavior
No response
Screenshots
No response
NuGet package version
None
Packaging type
Packaged (MSIX)
Windows version
No response
IDE
No response
Additional context
Here is an example of usage form seen in AppXManifest files:
<Package ...>
<Identity ... />
...
<Applications>
...
</Applications>
<Extensions>
<com:Extension Category="window.comInterface">
com:ComInterface
<com:TypeLib Id="...">
<com:Version VersionNumber="..." ... >
<com:Win32Path Path="..." />
</com:Version>
</com:TypeLib>
<com:Interface Id="..." ... >
<com:TypeLib Id="...">
...
</com:TypeLib>
</com:Interface>
</com:Extension>
</Extensions>
</Package>
The annoying thing about docs updates is that it is often faster to do it yourself. The fastest and most definitive course of action would be to mirror the MicrosoftDocs/winrt-related repo, make the changes that you think are needed and then create a pr out of it.
This isn't the first time that docs have been stale for a long period, I still remember that it took years for the namespaces for application manifests to be fixed. They were https for such a long period of time.
Thank you for reporting this. I've passed along word to the doc and dev team.
There were a couple of separate issues in the content. For some of the elements, like com:Extension, there were two separate articles, one which showed the element in the Application hierarchy and another which showed the element in the Package hierarchy. This was a decision made years and years ago when the schema docs were first created. In consultation with the COM team, we decided that since it's actually a single element "type" defined in the .xsd, that we should combine the two pages into a single page and show both hierarchies. For the newer schemas, com4 and com5, only the Application hierarchy was included. For these pages, we added the Package hierarchy.
In summary, for every com* element, we made a determination about whether it was supported in Application, Package, or both, and then put the appropriate hierarchy in each page.
+1. Great work.
Get Outlook for Androidhttps://aka.ms/ghei36
From: drew batchelor @.> Sent: Wednesday, October 23, 2024 5:42:18 PM To: microsoft/WindowsAppSDK @.> Cc: TIMOTHY MANGAN @.>; Author @.> Subject: Re: [microsoft/WindowsAppSDK] Documentation on AppXManifest COM Schema for Com:ComInterface (Issue #4700)
Closed #4700https://github.com/microsoft/WindowsAppSDK/issues/4700 as completed.
— Reply to this email directly, view it on GitHubhttps://github.com/microsoft/WindowsAppSDK/issues/4700#event-14831704609, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AEVBJFOOIFWGIB5ZC5K3YJ3Z5AJ3VAVCNFSM6AAAAABN4XYW5WVHI2DSMVQWIX3LMV45UABCJFZXG5LFIV3GK3TUJZXXI2LGNFRWC5DJN5XDWMJUHAZTCNZQGQ3DAOI. You are receiving this because you authored the thread.Message ID: @.***>