Skip to content

Update documentation for CsWin32RunAsBuildTask mode #1497

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 21, 2025
Merged

Update documentation for CsWin32RunAsBuildTask mode #1497

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5fda5e1
Doc updates
jevansaks Oct 21, 2025
224e4b7
Update docfx/docs/getting-started.md
jevansaks Oct 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 23 additions & 2 deletions docfx/docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,15 +121,36 @@ To keep CsWin32 generating the referred types you need, add them explicitly to `

### Support for trimming, AOT, and/or disabling the runtime marshaler

Newer .NET runtime versions may fail for CsWin32 generated code when the application project builds with one or both of these properties set:
**NEW!** CsWin32 now has improved support for NativeAOT by generating code from an MSBuild task rather than a source generator so that it can leverage other source generators that support `[LibraryImport]` and others.

If you set one of these flags:

```xml
<PublishAot>true</PublishAot>
<DisableRuntimeMarshalling>true</DisableRuntimeMarshalling>
<PublishTrimmed>true</PublishTrimmed>
```

CsWin32 supports these environments by avoiding code that relies on the runtime marshaler when the `allowMarshaling` setting is disabled in the `NativeMethods.json` file.
Then you have two options:

#### Enable CsWin32RunAsBuildTask

CsWin32 now supports AOT by generating code which relies on `GeneratedComInterface` and `LibraryImport`, which are source generators.
To make this chaining work, you have to request CsWin32 to run as a build task to generate the source code _before_ compile. Do this by adding this to your csproj:

```xml
<CsWin32RunAsBuildTask>true</CsWin32RunAsBuildTask>
<DisableRuntimeMarshalling>true</DisableRuntimeMarshalling>
```

It is also strongly recommended to set DisableRuntimeMarshalling=true as shown here to ensure that the COM source generators handle
all the marshalling correctly. See https://learn.microsoft.com/en-us/dotnet/standard/native-interop/pinvoke-source-generation and
https://learn.microsoft.com/en-us/dotnet/standard/native-interop/comwrappers-source-generation for more information on these .NET source
generators.

#### Disable runtime marshalling

CsWin32 can also support these environments by avoiding code that relies on the runtime marshaler when the `allowMarshaling` setting is disabled in the `NativeMethods.json` file.
For example:

```json
Expand Down
Loading