You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/authoring.md
+46-42Lines changed: 46 additions & 42 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,6 +5,7 @@
5
5
**Note: Authoring Support is still in preview**
6
6
7
7
C#/WinRT provides support for authoring Windows Runtime components. You can write a library in C#, and specify that it is a `CsWinRTComponent` for C#/WinRT to produce a WinMD that any WinRT compatible language can use. For example, a library written in C# can be used by a C++ program, via C#/WinRT and C++/WinRT.
8
+
Managed apps only need a project or package reference to the authored component, and native apps will need some extra steps that we cover in this documentation.
8
9
9
10
## References
10
11
Here are some resources that demonstrate authoring C#/WinRT components and the details discussed in this document.
@@ -36,23 +37,57 @@ The library you are authoring should specify the following properties in its pro
36
37
```
37
38
And don't forget to include a `PackageReference` to `Microsoft.Windows.CsWinRT`!
38
39
39
-
## Generate a NuGet package for the component
40
-
To generate a NuGet package for the component, you can simply right click on the project and select **Pack**. Alternatively, you can add the following property to the library project file to automatically generate a NuGet package on build.
40
+
## Using an Authored Component in a Native App
41
41
42
-
```csproj
42
+
You'll need to author some files to assist the hosting process of a consuming native app: `YourNativeApp.exe.manifest` and `WinRT.Host.runtimeconfig.json`.
43
+
If your app is packaged with MSIX, then you don't need to include the manifest file, otherwise you need to include your activatable class registrations in the manifest file.
44
+
45
+
To add these files, **in Visual Studio**, right click on the project node on the "Solution Explorer" window, click "Add", then "New Item".
46
+
Search for the "Text File" template and name your file `YourNativeApp.exe.manifest`.
47
+
Repeat this for the `WinRT.Host.runtimeconfig.json` file.
48
+
For each item, right-click on it in the "Solution Explorer" window of Visual Studio; then select "Properties" and change the "Content" property to "Yes" using the drop-down arrow on the right -- this ensures it will be added to the output directory of your solution.
49
+
50
+
We have some [hosting docs](https://github.com/microsoft/CsWinRT/blob/master/docs/hosting.md) as well, that provide more information on these files.
51
+
52
+
For consuming by "PackageReference", this is all that is required. C++ apps will need to use [C++/WinRT](https://docs.microsoft.com/en-us/windows/uwp/cpp-and-winrt-apis/intro-to-using-cpp-with-winrt) to consume the authored component. So make sure you have C++/WinRT installed, and have added `#include <winrt/MyAuthoredComponent.h>` to the file `pch.h` of the native app.
53
+
54
+
## Native Consumption by Project Reference
55
+
56
+
If you choose to consume your component through a project reference in a native app, then some modifications to the native app's `.vcxproj` file are needed.
57
+
Because dotnet will assume a `TargetFramework` for your app that conflicts with `net5`, we need to specify the `TargetFramwork`, `TargetFrameworkVersion` and `TargetRuntime`.
58
+
Examples of this are seen in the code snippet below. This is needed for this preview version, as we continue working on proper support.
59
+
60
+
You will need to add a reference to both the C#/WinRT component project, and the WinMD produced for the component.
61
+
The WinMD can be found in the output directory of the authored component's project. References are added by right-clicking on the project node you want to add a reference to, clicking "Add" then clicking "Reference" and browsing to the files.
62
+
63
+
Here are the additions made to the native app's project file:
64
+
```vcxproj
65
+
<!-- Note: this property group is only required if you are using a project reference,
66
+
and is a part of the preview while we work on proper support -->
**If you are going to write your own nuspec, i.e. not rely on automatic packaging** then the CsWinRT target that adds the hosting dlls to your package will not run, and you should make sure your nuspec contains the following ```file``` entries for ```MyAuthoredComponent``` (note: your TargetFramework may vary).
74
+
Project references for managed apps only need the reference to the authored component's project file.
75
+
76
+
## Packaging
77
+
To generate a NuGet package for the component, you can simply right click on the project and select **Pack**. Alternatively, you can add the following property to the library project file to automatically generate a NuGet package on build: `GeneratePackageOnBuild`.
78
+
79
+
To make your component available as a NuGet package, it is important to include the DLLs necessary for C#/WinRT hosting.
80
+
When you pack your C#/WinRT component the DLLs/WinMD are automatically added to your nupkg, based on a nuspec generated from your project file.
81
+
82
+
**If you are going to write your own nuspec**, then you should make sure your nuspec contains the following ```file``` entries for your component ```MyAuthoredComponent``` (note: your TargetFramework may vary). This is so our targets that supply the DLLs for any consumers of your package work.
83
+
Similarly, any other dependencies, e.g. `Microsoft.WinUI`, will need to be included in your nuspec as well.
@@ -78,40 +113,9 @@ To generate a NuGet package for the component, you can simply right click on the
78
113
</files>
79
114
```
80
115
81
-
## Using your authored component
82
-
To use the component in a C# app, the authored component just needs to be added as a project/package reference.
83
-
84
-
For native (C++) apps, there are DLLs needed to host your authored component. When you use the automatic NuGet packaging on-build support (in Visual Studio) to make a nupkg for your runtime component, the DLLs/WinMD are automatically added to your nupkg, before the ```GenerateNuspec``` MSBuild step.
85
-
86
-
### For native app (C++) consumption
87
-
Install your authored component's package -- this will come with a targets file that automatically adds a reference to the component's WinMD and copies the DLLs necessary for native support.
116
+
Your component can then be added as a PackageReference to any consumer.
88
117
89
-
You'll need to use [C++/WinRT](https://docs.microsoft.com/en-us/windows/uwp/cpp-and-winrt-apis/intro-to-using-cpp-with-winrt) to consume your API. So make sure you have C++/WinRT installed, and have added `#include <winrt/MyAuthoredComponent.h>` to the file `pch.h` of the native app.
90
-
91
-
You'll need to author some files to assist the hosting process by the native app: `YourNativeApp.exe.manifest` and `WinRT.Host.runtimeconfig.json`.
92
-
93
-
If your app is packaged with MSIX, then you don't need to include the manifest file, otherwise you need to include your activatable class registrations in the manifest file.
94
118
95
-
To do this, **in Visual Studio**, right click on the project node on the "Solution Explorer" window, click "Add", then "New Item". Search for the "Text File" template and name your file "YourNativeApp.exe.manifest".
96
-
Repeat this for the "WinRT.Host.runtimeconfig.json" file.
97
-
98
-
This process adds the nodes `<Manifest Include=... >` and `<None Include=... >` to your native app's project file -- **you need to update these to have `<DeploymentContent>true</DeploymentContent>` for them to be placed in the output directory with your executable**.
99
-
100
-
You should read the [hosting docs](https://github.com/microsoft/CsWinRT/blob/master/docs/hosting.md) as well, for more information on these files.
101
-
102
-
In summary, here is the fragment of additions made to the native app's project file:
103
-
```vcxproj
104
-
<ItemGroup>
105
-
<!-- the runtimeconfig.json -->
106
-
<NoneInclude="WinRT.Host.runtimeconfig.json">
107
-
<DeploymentContent>true</DeploymentContent>
108
-
</None>
109
-
<!-- the manifest -->
110
-
<ManifestInclude="YourNativeApp.exe.manifest">
111
-
<DeploymentContent>true</DeploymentContent>
112
-
</Manifest>
113
-
</ItemGroup>
114
-
```
115
119
116
120
## Known Authoring Issues
117
121
You can follow along [here](https://github.com/microsoft/CsWinRT/issues/663) as we develop authoring support.
0 commit comments