Ability to simply add a reference to a project/winmd

[jaigak]

Today adding a project/winmd reference even if C#/WinRT is installed doesn't work. The documentation tells to create an interop assembly using C#/WinRT, package into a .nupkg and reference that instead but it seems complicated and I just want to reference a project/winmd directly. C#/WinRT should automatically generate the required interop code in the consuming project just like C++/WinRT and shouldn't require extra from the component development.

[angelazhangmsft]

@Jaiganeshkumaran - we recently added support for embedding WinRT types into your app or library with C#/WinRT. You can try out the feature and compile the interop code with your app. Here are samples for this scenario as well: https://github.com/microsoft/CsWinRT/tree/master/src/Samples/TestEmbedded

It would be great to get feedback on this and if it helps with your scenario.

[mmarczell-graphisoft]

@angelazhangmsft
I am trying right now to recreate the embedded scenario in my own project and am failing miserably. Maybe you or someone could help me? Or maybe my stumbling can illuminate where the documentation / example code is not informative enough / not up to date.

My goal is basically just to call a C++ library in an object-oriented way from a C# GUI app. P/Invoke looks too low level, so I thought a C++/WinRT could be the way to go.

Attempt 1 - Follow the documentation

Preparation

1. Create a WinRT/C++ component project with the VS template "Windows Runtime Component (WinUI 3)".
2. Write the MIDL, generate the code stubs, copy to the project, fill in the implementation.
3. Create a blank WinUI/C# project with the VS template "Blank App, Packaged (WinUI3 in Desktop)". Both projects build successfully.

Attempt

1. I add this in my WinUI/C# project file:

<PropertyGroup>
	<CsWinRTEmbedded>true</CsWinRTEmbedded>
	<CsWinRTWindowsMetadata>sdk</CsWinRTWindowsMetadata>
	<CsWinRTGenerateProjection>true</CsWinRTGenerateProjection>
	<CsWinRTIncludes>
		winuicomponent.cpp;
	</CsWinRTIncludes>
</PropertyGroup>

<ItemGroup>
	<ProjectReference Include="..\winuicomponent.cpp\winuicomponent.cpp.vcxproj" />
</ItemGroup>

<ItemGroup>
	<PackageReference Include="Microsoft.Windows.CsWinRT" Version="2.0.7" />
</ItemGroup>

2. I attempt to build my solution. I get 39 errors such as these:

   CS0234 The type or namespace name 'Runtime' does not exist in the namespace 'Microsoft.UI.System' (are you missing an assembly reference?)
   C:\Dev\Sandbox\winrttests\winui.csharp\obj\x64\Debug\net6.0-windows10.0.22621.0\win10-x64\Generated Files\CsWinRT\ExceptionHelpers.cs

    CS0246 The type or namespace name 'SerializationInfo' could not be found (are you missing a using directive or an assembly reference?)
   C:\Dev\Sandbox\winrttests\winui.csharp\obj\x64\Debug\net6.0-windows10.0.22621.0\win10-x64\Generated Files\CsWinRT\ExceptionHelpers.cs

   CS0122 'EventSource' is inaccessible due to its protection level
   C:\Dev\Sandbox\winrttests\winui.csharp\obj\x64\Debug\net6.0-windows10.0.22621.0\win10-x64\Generated Files\CsWinRT\EventHandler.cs

   CS0122 'State' is inaccessible due to its protection level
   C:\Dev\Sandbox\winrttests\winui.csharp\obj\x64\Debug\net6.0-windows10.0.22621.0\win10-x64\Generated Files\CsWinRT\EventHandler.cs

Looking at the first of these reveals this generated code in ExceptionHelpers.cs:

namespace Microsoft.UI.Xaml
{
    using System.Runtime.Serialization;
    // ...

Is this generated code wrong? I would think the using should go outside of the namespace, at the beginning of the file. I can fix this manually but it comes back when this code is regenerated at every build.

3. I add Windows.Foundation to CsWinRTIncludes as in the docs. Build Solution. Now I'm down to 26 errors, all of which arise in generated code.

At this point I have a vague guess that maybe I have "too much WinUI" in my project? I remember my initial confusion about choosing between these three, all of which have descriptions that each mention C++, Windows Runtime and UWP.

Suggestion

The descriptions of project templates should be much more informative, so that the differences are clear to the developer.

5. I create a "Windows Runtime component (Universal Windows)" and realize that although this is both C++ and Windows Runtime, it is in fact not C++/WinRT, but C++/CX which was mentioned nowhere. One down, one to go.

   (Oh, so WinRT is not the same thing as Windows Runtime. I wonder if Universal Windows Platform is the same thing as UWP?)

6. I create a "Windows Runtime component (C++/WinRT)". Recreate the MIDL and the implementation.

7. Modify my UI project to reference this instead of the earlier one. Rebuild Solution. I still get 6 errors, mainly the aforementioned ones about nonexisting namespaces, as well as a new one:

   CS0101 The namespace 'Windows.Foundation' already contains a definition for 'PropertyType'
   winui.csharp
   C:\Dev\Perforce\MM-Win-ACUIExperiment\nativeui\winrttests\winui.csharp\obj\x64\Debug\net6.0-windows10.0.22621.0\win10-x64\Generated Files\CsWinRT\Windows.Foundation.cs

8. I notice this in the sample project file, which was not mentioned in the documentation

<CsWinRTExcludes>
  Windows.Foundation.Diagnostics;
  Windows.Foundation.PropertyType;
</CsWinRTExcludes>

Suggestion:

The documentation should provide comprehensive steps to get to a working minimal example instead of providing some steps but leaving out others.

Adding this solves the latest error, now I have only 5, but after Rebuild Solution it's 7, adding two of these:

CS0121 The call is ambiguous between the following methods or properties: 'WinRT.ExceptionExtensions.SetHResult(System.Exception, int)' and 'WinRT.ExceptionExtensions.SetHResult(System.Exception, int)'
winui.csharp
C:\Dev\Perforce\MM-Win-ACUIExperiment\nativeui\winrttests\winui.csharp\obj\x64\Debug\net6.0-windows10.0.22621.0\win10-x64\Generated Files\CsWinRT\ExceptionHelpers.cs

I give up at this point and try to lego together something from the official samples.

Attempt 2 - Adapt the examples to my own usecase

1. I clone the CsWinRT repo
2. I open src/Samples/TestEmbedded/TestEmbedded.sln
3. I attempt to build and run "Net6App.Bootstrap" project
4. There is a build error saying

   error MSB3073: The command ""C:\Dev\git\CsWinRT\src_build\x64\Debug\cswinrt\bin\cswinrt.exe" @"C:\Dev\git\CsWinRT\src\Samples\TestEmbedded\Net6App.Bootstrap\Generated Files\net6.0-windows\CsWinRT\cswinrt.rsp"" exited with code 3.

Suggestion

The example project should be self contained and immediately runnable on its own in order for us to be able to use it as a template. It should not depend on a hardcoded path of a locally built version of the whole CsWinRT project.

5. Okay, so I try to build CsWinRT itself. I open src/CsWinRT.sln and try to build the solution. I get 127 build errors. The first one says

   This solution requires the TestWinRT repo, which is missing. Please run build.cmd from a Visual Studio command prompt.

   • I also noticed sometime around here that VS displayed a yellow warning in Solution Explorer that a required .NET version is not installed. I clicked the action button and did the thing.

Suggestion

Maybe use git submodules to immediately clone required related repos? Ideally the VS solution should be self contained. It really makes Microsoft itself look bad that its own development tools are not sufficient for its own projects and require custom shellscripts as glue.

6. Okay, so I open the VS cmd prompt and run build.cmd. I get a lot of errors and I can't even scroll back to see what the first one was, the buildlog is so long.
   • Sometime around here VS has displayed the yellow warning for another missing .NET SDK version. I clicked the action button and did the thing.
   • There were still some build errors about a specific .NET SDK minor version missing, but no yellow warning, so I installed it manually from the website.

Suggestion

VS should suggest installing all of the missing SDK-s at the same time, and the autofix installation should actually work.

7. After installing all 3 missing .NET versions, I finally get build.cmd to succeed. Back to cswinrt.sln, Build Solution. It still fails to build with 55 errors. But now I have a cswinrt.exe binary.
8. Back to TestEmbedded.sln, the solution now builds.
   • Now how in the nine Corellian hells should I rip out the custom scaffolding from this project that links it to a local CsWinRT build so that it uses the NuGet package and can be used in my own project?
   • One immediately apparent difference is that this is a console app while I'm trying to use CsWinRT in a WinUI app.

Attempt 3 - Try to use this in a WPF project

As long as I do not reference the WinRT component anywhere in my C# code, I can get the C# projection file of my library generated into obj/Debug/net6.0-windows/Generated Files/CsWinRT. As soon as I add the using directive in my C# UI code and build the solution again, the same projection file does not exist anymore in that folder.

"Summary"

My experience at this point is that the developer experience of cross-language Windows apps is abysmal. Just looking at the VS project template selector, the relationship between Universal Windows Platform, UWP, Windows Runtime, WinRT, WinUI, various versions of .NET, the differences between .NET Framework, .NET, .NET Core, .NET Standard and who knows how many others makes their compatibility matrix completely incomprehensible for the average developer. I tried to provide concrete suggestions where I could, but ultimately it should boil down to "create a project, write some code, create another project, reference the first one and start calling it from code". The fact that both C++ and C# have been first class languages on Windows since the inception of C# and there is still no straightforward, up to date, supported way, with a smooth developer experience, to create object-oriented bindings between them is mind blowing.

[manodasanW]

Thanks for the feedback on the embedded samples, I agree we do need to make them more standalone and not require you to run build.cmd and install multiple SDKs and so on.

For your original issue, can you confirm whether the project you are trying to use embedded support in is a WinUI app project as you mentioned in step 3 of preparation and has a WindowsAppSDK package reference? If so and based on the error, I assume your Target Framework (TFM) for this project is net6.0-windows10.0.22621.0. In this scenario, you won't need to use embedded support and you can just remove the CsWinRTEmbedded property unless there is another reason for you to need embedded support. Embedded support is targeted for scenarios where you can't use the Windows version specific TFM or where you have a library and you want to scope the usage of these projected APIs to within your library and you aren't using the distributed projections. Without it, you can still have CsWinRT generate a projection just for your component and use it in your app.

With respect to the actual errors, some of the errors are going to be due to using the Windows version specific TFM together with embedded support as it is going to see the same types being embedded already in the Windows SDK projection that is distributed with the TFM. And it is not going to know which one to call such as those errors saying ambiguous calls. Some of the other errors, specifically the ones you highlighted first, look to be because we hadn't tested embedded support with WinUI projections and looks like that discovered that the compiler is getting confused between Microsoft.UI.System and System.Runtime due to the missing global:: in the using namespace. We will get that fixed. But I think based on what I see, you should be able to get your scenario working without embedded support.

[mmarczell-graphisoft]

Thank you! I have managed to get it working in my WinUI app project.

Suggestion

I think it was the documentation that misled me down the wrong rabbithole. Here https://github.com/microsoft/CsWinRT/blob/master/docs/usage.md
it says that you can do one of three things with CsWinRT:

1. Generate and distribute an interop assembly
2. Embedded support for WinRT types
3. Author and consume a C#/WinRT component (in preview)

Nowhere does it say that you can simply include CsWinRT in your application project as a way to directly reference a WinRT component and start using it right there. It seems I'm not the only one that have read the docs and concluded that wasn't possible:

• This very Github Discussion where embedding is suggested as a solution to this exact scenario by a MS employee
• Support direct project references instead of NuGet for fast development loop #1268

I think the docs should emphasize the simplest usecases and then go into the complex ones.

WPF

When trying to use CsWinRT in WPF, I am still experiencing the bug where the generated projection file disappears as soon as I reference it in code. To illustrate it better: This compiles:

But this fails to build, and as you can see the file disappeared, which happens during the build:

This is my csproj:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net6.0-windows</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <UseWPF>true</UseWPF>
  </PropertyGroup>

	<PropertyGroup>
		<CsWinRTWindowsMetadata>sdk</CsWinRTWindowsMetadata>
		<CsWinRTGenerateProjection>true</CsWinRTGenerateProjection>
		<CsWinRTIncludes>
			winrtcomponent_cpp;
			Windows.Foundation;
		</CsWinRTIncludes>
		<CsWinRTExcludes>
			Windows.Foundation.Diagnostics;
			Windows.Foundation.PropertyType;
		</CsWinRTExcludes>
		<PlatformTarget>x64</PlatformTarget>
	</PropertyGroup>

	<ItemGroup>
		<PackageReference Include="Microsoft.Windows.CsWinRT" Version="2.0.7" />
	</ItemGroup>

	<ItemGroup>
	  <ProjectReference Include="..\winrtcomponent.cpp\winrtcomponent.cpp.vcxproj" />
	</ItemGroup>

</Project>

• Do I need to include a specific Windows version in TargetFramework?
• Do I need to include a specific Windows version in CsWinRTWindowsMetadata, and what is the meaning of the special value "sdk" that I found in the sample projects but I can find no mention of in docs?

(Experimenting with these does not fix the file-disappearing issue.)

[mmarczell-graphisoft]

@manodasanW Do you have a suggestion on what should I do to be able to use this in WPF?