diff --git a/docs/authoring.md b/docs/authoring.md
index 44a0c2b9f..52dca2732 100644
--- a/docs/authoring.md
+++ b/docs/authoring.md
@@ -19,11 +19,11 @@ It is recommended to use .NET 6 and Visual Studio 2022 for C#/WinRT authoring sc
```
- To access Windows Runtime types, you need to set a specific Windows SDK version in the TFM. See [.NET 5 and later: Use the TFM option](https://docs.microsoft.com/en-us/windows/apps/desktop/modernize/desktop-to-uwp-enhance#net-5-and-later-use-the-target-framework-moniker-option) for more details on the supported versions.
+ To access Windows Runtime types, you need to set a specific Windows SDK version in the TFM. See [.NET 5 and later: Use the TFM option](https://docs.microsoft.com/windows/apps/desktop/modernize/desktop-to-uwp-enhance#net-5-and-later-use-the-target-framework-moniker-option) for more details on the supported versions.
2. Install the [Microsoft.Windows.CsWinRT](https://www.nuget.org/packages/Microsoft.Windows.CsWinRT) NuGet package in your project.
-3. Add the following C#/WinRT-specific properties to the project file. The `CsWinRTComponent` property specifies that your project is a Windows Runtime component, so that a WinMD file is generated for the component.
+3. Add the following C#/WinRT-specific property to the project file. The `CsWinRTComponent` property specifies that your project is a Windows Runtime component, so that a WinMD file is generated when you build the project.
```xml
@@ -35,7 +35,7 @@ It is recommended to use .NET 6 and Visual Studio 2022 for C#/WinRT authoring sc
4. Implement your runtime classes in the class files in your library project, following the necessary [WinRT guidelines and type restrictions](https://docs.microsoft.com/windows/uwp/winrt-components/creating-windows-runtime-components-in-csharp-and-visual-basic#declaring-types-in-windows-runtime-components).
-### Packaging your WinRT component
+## Packaging your WinRT component
You may want to distribute and share your component as a NuGet package. To generate a NuGet package for the component, you can choose one of the options below. Your component can then be used in consuming apps by a `PackageReference`.
@@ -86,78 +86,140 @@ To make your component available as a NuGet package, it is important to include
This section describes the steps needed to consume a C#/WinRT component for the following scenarios:
-- [C++/WinRT desktop applications (Unpackaged)](#consuming-from-cwinrt-unpackaged)
-- [C# desktop applications](#consuming-from-c-applications) (.NET 5 or later)
-- [Packaged applications](#Consuming-from-packaged-applications)
-- [Out of process components](#Consuming-an-out-of-process-component)
+- [C# desktop applications](#consuming-from-c-applications)
+- [C++ desktop applications](#consuming-from-c-applications-1)
+- [Windows App SDK applications](#windows-app-sdk-applications)
+- [Out of process components](#consuming-an-out-of-process-component)
-### Consuming from C++/WinRT (Unpackaged)
+### Consuming from C# applications
+
+Consuming a C#/WinRT component from C#/.NET apps is supported by both package reference and project reference.
+This scenario is equivalent to consuming any ordinary C# class library and does not involve WinRT activation in most cases.
+The exception being in the out-of-process scenario, described below.
+
+**Note:** With C#/WinRT 1.3.5 or later, project references to a C#/WinRT component require .NET 6.
-Consuming a C#/WinRT component from a C++/WinRT desktop application is supported by both package reference or project reference:
+### Consuming from C++ applications
+
+Consuming a C#/WinRT component from a C++/WinRT desktop application is supported by either NuGet package reference or project reference.
- **Package Reference**: In Visual Studio, right-click on the project in Solution Explorer and click **Manage NuGet packages** to search for and install the component package.
- **Project Reference**: In Visual Studio, right-click on the project in Solution Explorer and click **Add** -> **Reference**. Select the C#/WinRT component project under the **Projects** node.
- Note: If your authored component is built with C#/WinRT version 1.3.3 or earlier, you also need a file reference to the `*.winmd` generated in the authored component's output directory. To add a file reference, right-click on the project in Solution Explorer and click **Add** -> **Reference**. Select the file from the **Browse** node.
-**Application Manifest file**
+#### Manifest Class Registration
-For consumption of C#/WinRT components from unpackaged applications, you need to create an [application manifest file](https://docs.microsoft.com/windows/win32/sbscs/application-manifests) named `YourNativeApp.exe.manifest`. The application manifest file must specify activatable Windows Runtime classes in the DLL that the application will be making use of. At runtime, this directs activation of the component’s classes. See the [sample manifest file](https://github.com/microsoft/CsWinRT/tree/master/src/Samples/AuthoringDemo/CppConsoleApp/CppConsoleApp.exe.manifest) for an example.
+Consuming a C#/WinRT component from a C++/WinRT desktop application requires adding manifest class registrations to the application.
+The specified activatable Windows Runtime class registrations will direct activation of the component’s classes at runtime.
+There are two different ways to do this depending on if the application is a packaged (with MSIX) or unpackaged C++ app:
-Follow these steps to add an application manifest file to your project:
+ - For **packaged** C++ apps: The app consumer needs to add `ActivatableClass` registration entries to the `Package.appxmanifest` package manifest file like below:
-1. In Visual Studio, right click on the project node under **Solution Explorer** and click **Add -> New Item**. Search for the **Text File** template and name your file `YourNativeApp.exe.manifest`.
+ ``` xml
+
+
+
+ WinRT.Host.dll
+
+
+
+
+
+ ```
-2. Add your activatable class registrations to the manifest file. Below is an example with a C#/WinRT component `MyAuthoredComponent` and activatable classes `WinRTComponent.Class*`. Note that `WinRT.Host.dll` must be specified as the file name.
+ See the [Simple C#/WinRT component sample](../src/Samples/AuthoringDemo) (specifically the WinUI3CppApp) for an example.
- ```xml
-
-
-
-
-
-
-
-
- ```
+ - For **unpackaged C++ apps**: The app consumer needs to create an [application manifest file](https://docs.microsoft.com/windows/win32/sbscs/application-manifests) (also known as a "fusion manifest") that follows the naming: `.exe.manifest`. See this [sample manifest file](https://github.com/microsoft/CsWinRT/tree/master/src/Samples/AuthoringDemo/CppConsoleApp/CppConsoleApp.exe.manifest) for an example.
-3. Modify the project to include the manifest file in the output when deploying the project. Right-click on the file in **Solution Explorer**, select **Properties**, and set the **Content** property to **True** using the drop-down arrow on the right.
+ Follow these steps to add an application manifest file to your project:
-### Consuming from C# applications
+ 1. In Visual Studio, right click on the project node under **Solution Explorer** and click **Add -> New Item**. Search for the **Text File** template and name your file `.exe.manifest`.
-Consuming a C#/WinRT component from C#/.NET apps is supported by both package reference or project reference. This scenario is equivalent to consuming any ordinary C# class library and does not involve WinRT activation in most cases.
+ 2. Add your activatable class registrations to the manifest file. Below is an example with a C#/WinRT component called `MyAuthoredComponent` and activatable classes `WinRTComponent.Class*`. Note that `WinRT.Host.dll` must be specified as the file name, without a relative path.
-**Note:** With C#/WinRT 1.3.5 or later, project references to a C#/WinRT component require .NET 6.
+ ```xml
+
+
+
+
+
+
+
+
+ ```
+
+ 3. Modify the project to include the manifest file in the output when deploying the project. Right-click on the file in **Solution Explorer**, select **Properties**, and set the **Content** property to **True** using the drop-down arrow on the right.
+
+### Windows App SDK Applications
+
+Authoring and consuming WinUI types in Windows App SDK applications is in development and is supported with some exceptions.
+Component authors can implement WinUI types using the Windows App SDK C# class library project template.
+Components can be consumed by application projects that reference the Windows App SDK.
-### Consuming from packaged applications
+#### Support Matrix
-Consuming C#/WinRT components from MSIX-packaged applications is supported with a few modifications.
+The following table outlines the Windows App SDK application types that are supported when consuming C#/WinRT authored components implementing WinUI types:
+
+- ✅ Scenario works
+- 🟨 Scenario partially works (i.e. with specific limitations)
+- 🟥 Scenario does not work
+- Note: "WAP" refers to the usage of a separate Windows Application Packaging Project in packaged apps.
+
+##### C++
+|Application Type|Project or Package Reference|Supported?|Tracking issue|
+|:--|:-:|:-:|:-:|
+|C++ Packaged|Project Reference| ✅ | |
+|C++ Packaged with WAP |Project Reference| 🟥 | [#1120](https://github.com/microsoft/CsWinRT/issues/1120) |
+|C++ Unpackaged|Project Reference| 🟥 | [#1116](https://github.com/microsoft/CsWinRT/issues/1116) |
+|C++ Packaged|Package Reference|🟨 | [#1118](https://github.com/microsoft/CsWinRT/issues/1118) |
+|C++ Packaged with WAP |Package Reference| 🟥 | [#1123](https://github.com/microsoft/CsWinRT/issues/1123) |
+|C++ Unpackaged|Package Reference|🟨 | [#1118](https://github.com/microsoft/CsWinRT/issues/1118) |
+
+##### C#
+|Application Type|Project or Package Reference|Supported?|Tracking issue|
+|:--|:-:|:-:|:-:|
+|C# Packaged|Project Reference| ✅ |
+|C# Packaged with WAP|Project Reference| ✅ |
+|C# Unpackaged|Project Reference|🟥| [#1116](https://github.com/microsoft/CsWinRT/issues/1116) |
+|C# Packaged|Package Reference| 🟨 | [#1118](https://github.com/microsoft/CsWinRT/issues/1118) |
+|C# Packaged with WAP |Package Reference| 🟨 | [#1118](https://github.com/microsoft/CsWinRT/issues/1118) |
+|C# Unpackaged|Package Reference|🟥 | [#1116](https://github.com/microsoft/CsWinRT/issues/1116) |
+
+#### Consumption of WinUI controls from C++ apps
+
+If a C++ app is consuming a component that provides a custom user control, there are a few extra configuration steps:
+Note that "MyAuthoredComponent" should be renamed to your component; "MyAuthoredComponent" is just an example.
+
+1. In the app's `pch.h` header file, add the following line:
+
+ ```cpp
+ #include
+ ```
+
+2. In the manifest file, add an additional `ActivatableClass` entry for `MyAuthoredComponent.MyAuthoredComponent_XamlTypeInfo.XamlMetaDataProvider`, in addition to the manifest entries for the classes being consumed.
+
+ i. For **unpackaged** apps: add an entry similar to the following to `AppName.exe.manifest`:
-- Consuming a C#/WinRT component from packaged C# apps is supported.
-- Consuming a C#/WinRT component from a C++/WinRT packaged app (e.g., a Windows App SDK C++ application) is supported with a few modifications listed below. See the [Simple C#/WinRT component sample](../src/Samples/AuthoringDemo) (specifically the WinUI3CppApp) for an example.
- - If consuming via project reference, adding a project reference to the C#/WinRT component project in Visual Studio may result in the error: *"A reference to 'MyAuthoredComponent' cannot be added because it is incompatible with this project"*. To workaround this, unload the `.vcxproj` file and add the `ProjectReference` manually, for example:
```xml
-
+
```
- - The app consumer needs to add the `ActivatableClass` registrations in the `Package.appxmanifest` file, like below. Note that packaged app consumers do not create a new application manifest (`.exe.manifest`) file.
+ ii. For **packaged** apps, add an entry similar to the following to `Package.appxmanifest`:
+
```xml
-
-
-
- WinRT.Host.dll
-
-
-
-
-
+
```
+ You will need to right-click on the file and select **Open With** -> **XML (Text Editor)** in order to edit the file.
+ You may need to add the appxmanifest to the solution view; to do this right-click the project and select **Add exisiting item** to select `Package.appxmanifest`.
+
### Consuming an out of process component
C#/WinRT supports authoring out-of-process components that can be consumed by Windows Runtime compatible languages. Currently, consuming an out-of-process component is supported for managed C# apps with the use of a packaging project. This scenario requires creating a `WinRT.Host.runtimeconfig.json` file, as demonstrated in the [background task component sample](https://github.com/microsoft/CsWinRT/tree/master/src/Samples/BgTaskComponent). Native C++ consumption of out-of-process C# components is not fully supported yet.
@@ -166,10 +228,14 @@ C#/WinRT supports authoring out-of-process components that can be consumed by Wi
- Project reference support (from C++ and C# apps) for C#/WinRT authored components is available with .NET 6. Referencing a C#/WinRT authored component by project reference in a C# app is **not supported with .NET 5**.
-- Hosting WinUI3 components is not fully supported yet.
-
- Authoring issues are [tagged under the *authoring* label](https://github.com/microsoft/CsWinRT/issues?q=is%3Aopen+is%3Aissue+label%3Aauthoring). Feel free to [file an issue](https://github.com/microsoft/CsWinRT/issues/new/choose) tagged with the *authoring* label if you encounter any new issues!
+- The docs [here](https://docs.microsoft.com/windows/uwp/cpp-and-winrt-apis/troubleshooting#symptoms-and-remedies) have useful troubleshooting tips for working with C++/WinRT.
+
+- When adding an `exe.manifest`, if you get an error in the linker (LNK) typically this is due to multiple manifests being found,
+ and `app.manifest` can be removed to resolve the issue.
+
+
## Resources
Here are some resources that demonstrate authoring C#/WinRT components and the details discussed in this document.
@@ -184,4 +250,4 @@ Here are some resources that demonstrate authoring C#/WinRT components and the d
4. [Managed component hosting](https://github.com/microsoft/CsWinRT/blob/master/docs/hosting.md)
-5. [Diagnose component errors](https://docs.microsoft.com/en-us/windows/uwp/csharp-winrt/authoring-diagnostics)
+5. [Diagnose component errors](https://docs.microsoft.com/windows/uwp/csharp-winrt/authoring-diagnostics)
diff --git a/nuget/Microsoft.Windows.CsWinRT.Authoring.Transitive.targets b/nuget/Microsoft.Windows.CsWinRT.Authoring.Transitive.targets
index 98a5f1b0c..223bb9be7 100644
--- a/nuget/Microsoft.Windows.CsWinRT.Authoring.Transitive.targets
+++ b/nuget/Microsoft.Windows.CsWinRT.Authoring.Transitive.targets
@@ -15,7 +15,7 @@
-
+
@@ -25,15 +25,19 @@
-
+
-
-
+
+ trueWinRT.Host.dll
+
+
+
+
diff --git a/nuget/Microsoft.Windows.CsWinRT.Authoring.targets b/nuget/Microsoft.Windows.CsWinRT.Authoring.targets
index 798a9374d..35e5117d5 100644
--- a/nuget/Microsoft.Windows.CsWinRT.Authoring.targets
+++ b/nuget/Microsoft.Windows.CsWinRT.Authoring.targets
@@ -11,9 +11,8 @@ Copyright (C) Microsoft Corporation. All rights reserved.
trueWinRT.Host.runtimeconfig.json
-
- truetrue
+ $(GetCopyToOutputDirectoryItemsDependsOn);CsWinRTAuthoring_AddManagedDependencies
@@ -59,19 +58,11 @@ Copyright (C) Microsoft Corporation. All rights reserved.
-
-
-
WinRT.Host.Shim.dllPreserveNewest
-
- WinRT.Runtime.dll
- PreserveNewest
-
-
WinRT.Host.dll
@@ -80,8 +71,59 @@ Copyright (C) Microsoft Corporation. All rights reserved.
+
+
+
+
+
+
+ <_CsWinRTDeDupRuntime_NETSDK Include="@(ReferenceCopyLocalPaths)" Condition="'%(ReferenceCopyLocalPaths.NuGetPackageId)' == 'Microsoft.Windows.SDK.NET.Ref' AND '%(ReferenceCopyLocalPaths.Filename)' == 'WinRT.Runtime'"/>
+ <_CsWinRTDeDupRuntime_CsWinRT Include="@(ReferenceCopyLocalPaths)" Condition="'%(ReferenceCopyLocalPaths.NuGetPackageId)' == 'Microsoft.Windows.CsWinRT' AND '%(ReferenceCopyLocalPaths.Filename)' == 'WinRT.Runtime'"/>
+
+
+
+
+
+
+ <_CsWinRTDeDupRuntime_CsWinRT_Version_IsLatest Condition="'@(_CsWinRTDeDupRuntime_NETSDK)' == ''">true
+
+
+
+
+
+ <_CsWinRTDeDupRuntime_NETSDK_Version>%(_CsWinRTDeDupRuntime_NETSDK.FileVersion)
+ <_CsWinRTDeDupRuntime_CsWinRT_Version>%(_CsWinRTDeDupRuntime_CsWinRT.NuGetPackageVersion)
+
+ <_CsWinRTDeDupRuntime_CsWinRT_Version_IsLatest>$([MSBuild]::VersionGreaterthanOrEquals($(_CsWinRTDeDupRuntime_CsWinRT_Version),$(_CsWinRTDeDupRuntime_NETSDK_Version)))
+
+
+
+
+
+ <_CsWinRTDeDupRuntime_Newest Include="@(_CsWinRTDeDupRuntime_CsWinRT)" Condition="'$(_CsWinRTDeDupRuntime_CsWinRT_Version_IsLatest)' == 'true'"/>
+ <_CsWinRTDeDupRuntime_Newest Include="@(_CsWinRTDeDupRuntime_NETSDK)" Condition="'$(_CsWinRTDeDupRuntime_CsWinRT_Version_IsLatest)' != 'true'"/>
+
+
+
+ %(ReferenceCopyLocalPaths.DestinationSubDirectory)%(ReferenceCopyLocalPaths.Filename)%(ReferenceCopyLocalPaths.Extension)
+ PreserveNewest
+
+
+
+ %(_CsWinRTDeDupRuntime_Newest.DestinationSubDirectory)%(_CsWinRTDeDupRuntime_Newest.Filename)%(_CsWinRTDeDupRuntime_Newest.Extension)
+ PreserveNewest
+
+
+
+
+
+
-
@@ -166,27 +208,8 @@ Copyright (C) Microsoft Corporation. All rights reserved.
-
-
-
-
-
-
-
-
-
-
- <_ThisProjectItemstoCopyToOutputDirectory Include="@(CsWinRTSDKRefDll)">
- %(FileName)%(Extension)
- PreserveNewest
- Microsoft.Windows.SDK.NET.dll
-
-
-
-
-
-
+
@@ -255,6 +278,11 @@ Copyright (C) Microsoft Corporation. All rights reserved.
+
+
+ true
+ lib\$(TargetFramework)
+
@@ -269,7 +297,12 @@ Copyright (C) Microsoft Corporation. All rights reserved.
-
+
+ true
+ lib\$(TargetFramework)
+
+
+ truelib\$(TargetFramework)