cswin32-interop

星标1

分支0

更新时间2026年7月20日 05:07

Guides CsWin32 P/Invoke interop in a multi-targeted .NET 10 and .NET Framework library. Consult when replacing [DllImport] with source-generated PInvoke.* calls, working with generated Windows.Win32 projections (HANDLE / HMODULE / HRESULT / BOOL and typed enum/constant types), configuring NativeMethods.txt / NativeMethods.json, composing a public PInvoke across foundation/owner/extender packages with extensionReceiver, deciding which support library owns a helper, auditing native allocation and byte/element lengths, selecting compile-time / runtime / analyzer guards for Windows-only code, or choosing between CsWin32 and [LibraryImport]. Not for managed-only changes with no native boundary. Paired with the cswin32-com skill for the struct-based COM layer.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

来源

JeremyKuhne

JeremyKuhne/agent-skills

打开 GitHub 仓库查看创作者相关仓库

下载

CsWin32 P/Invoke interop

If overlay.md exists beside this file, read it before acting; it contains repository-specific bindings. This core remains usable without it.

CsWin32 is a source generator that replaces hand-written [DllImport] declarations with generated PInvoke.* calls and strongly-typed projections of Win32 handles, structs, enums, and constants. You list the API, type, or constant names you need in NativeMethods.txt; the generator emits them and pulls in their dependencies.

This skill is the general P/Invoke layer. The struct-based COM layer builds on it - see the paired cswin32-com skill, whose vtable methods follow the same blittable-signatures rules.

Rules

Replace a hand-written [DllImport] with PInvoke.* when CsWin32 can project the API. After verifying the generated declaration and supporting types, delete their hand-written equivalents. Keep a source-generated [LibraryImport] on .NET 10 and [DllImport] on .NET Framework for an export absent from the available Win32 metadata. See types-and-constants.md.
Use the generated types directly (HANDLE, HMODULE, HRESULT.S_OK, FILE_FLAGS_AND_ATTRIBUTES, ...). Never keep a parallel local copy of a Win32 enum or struct CsWin32 already projects.
Call the generated method directly - no thin wrapper. Within one ownership layer, generate once and share internal types with friend assemblies. When a downstream package intentionally extends a public owner, use the owner/extender composition model instead.
Prefer CsWin32 for Windows APIs present in its metadata. Use [LibraryImport] (or [DllImport] on .NET Framework) for private, custom, or otherwise unprojectable Windows exports and for non-Windows native calls such as libc. Keep those signatures blittable under the same rules.
Preserve the original error-handling contract when migrating. Check the old declaration for PreserveSig / SetLastError / BOOL / HRESULT semantics and reproduce them: PreserveSig=false becomes .ThrowOnFailure(); SetLastError=true plus a failed BOOL becomes throw new Win32Exception(). Silently returning where the old code threw is a behavior change. The paired cswin32-com skill has the COM-side parity table.
Keep signatures blittable. CsWin32 is configured allowMarshaling: false, so every [DllImport] and every COM vtable method must be blittable. The full rule set is in blittable-signatures.md.
Audit ownership and size units. Generated wrappers do not decide which allocator frees an output, whether a COM reference remains caller-owned, or whether a length is bytes or elements. Record and test those contracts using ownership-and-units.md.

Platform and target-framework guards

CsWin32 projects Windows APIs, but compile inclusion, runtime reachability, and the public platform contract are separate decisions. Generated declarations can live in a cross-platform assembly; reachable calls still need a recognized Windows runtime guard or a Windows-only API context. Exclude source at compile time only when a target intentionally omits that interop surface or one of its dependencies. In the .NET 10 / .NET Framework target model, use NET for the .NET 10 leg and NETFRAMEWORK for the Framework leg. See gating.md for the decision table, CA1416, and guarded-build verification. An overlay records the concrete TFMs and any repository-specific compile symbol or source-item condition.

Configuration

NativeMethods.txt - one API / type / constant name per line; the generator projects each and pulls in its dependencies.
NativeMethods.json - generator options. allowMarshaling: false (raw blittable signatures, no marshaller) and useSafeHandles: false are the interop-friendly defaults these skills assume.
Run the generator in a single project within an ownership layer and share via InternalsVisibleTo rather than adding CsWin32 to every implementation project. A package that extends another package's public projection is a separate layer: configure className / extensionReceiver as described in composition.md.

Source generator versus build task

The Roslyn source generator is the default. Setting CsWin32RunAsBuildTask=true replaces it with an MSBuild task that writes .cs files under the intermediate output directory and adds them to Compile; the source generator stands down. Treat this as an opt-in for a specific build ordering, generated-file, or tooling requirement, not as a general upgrade.

Before keeping build-task mode, clean and build all .NET 10 and .NET Framework TFMs, compare the emitted public API, and measure clean-build time. It can be materially slower. It also does not make an allowMarshaling: false project more AOT-safe by itself, so do not enable DisableRuntimeMarshalling merely because generation moved to the task.

Sibling pages

blittable-signatures.md - the signature rules shared by [DllImport] and COM vtables (HRESULT, T** vs out T*, void*, nint, PCWSTR / PWSTR, typed enum parameters).
types-and-constants.md - using the generated handle / enum / constant projections, "grep the metadata before redefining", type conversions, FILETIME, and native integers.
composition.md - composing one public PInvoke across an owner package and downstream extender, including constants, XML docs, and package verification.
library-layering.md - placing generic utilities, shared Win32 support, domain extensions, and applications in a directed package stack, with migration and release ordering.
ownership-and-units.md - matching native allocators and deallocators, caller-owned COM references, failure cleanup, and byte-versus-element conversions.
gating.md - source inclusion, runtime and TFM guards, CA1416, a stack-first scratch-buffer strategy, and guarded-build verification.

同仓库更多 Skills

同仓库

cswin32-com

JeremyKuhne/agent-skills

Guides struct-based COM interop using CsWin32 - AOT-compatible raw pointer calls without [ComImport] or built-in CLR marshalling; managed [ComImport] mirrors are limited to CCW bridges. Consult when working with ComScope, IID.Get, delegate* unmanaged vtables, CoCreateInstance or a class factory, IComIID across .NET 10 and .NET Framework, connection-point Advise/Unadvise ownership, caller-owned CCW references, manually defining COM interfaces absent from Win32 metadata, COM pointer lifetime in fields, cross-assembly CCWs, or mocking struct-based COM in tests. Not for ordinary RCW-based COM consumption with no raw struct pointers or CCW bridge. Paired with the cswin32-interop skill for the general P/Invoke layer and blittable-signature rules.

2026-07-201

performance-testing

JeremyKuhne/agent-skills

Author and run BenchmarkDotNet performance tests in a multi-targeted .NET library's perf project, and translate a user's outcome-shaped performance question into a measurement. Use when adding new benchmarks, running existing ones, comparing implementations, profiling to find which method or source line dominates, evaluating allocations / memory usage, reading the generated code (sharplab / DisassemblyDiagnoser / HardwareCounters), or when a user asks how long something takes, how much memory it uses, where time is spent, or to help make a method faster - which this skill turns into a scenario, a benchmark, and a drill-down.

2026-07-191

engineering-baseline

JeremyKuhne/agent-skills

Create a new .NET repository fully wired for building, testing, and publishing with OSS best practices, or bring an existing repository up to a documented engineering baseline. Use when asked to "create a new repository" / "scaffold a new project" (a CLI tool, a class library / NuGet package, or a multi-target library) with CI, packaging, branch protection, and governance files, or to "ensure this repo follows modern engineering best practices" / "audit this repository" / "bring this repo up to standard". Scores a repository across nine domains - foundation, build, test, publish, versioning, CI, supply-chain security, OSS governance, and agent enablement - against an industry-cited baseline, then reports gaps and remediates. Irreversible or remote actions (repository creation, branch protection, release settings, publishing) are proposed for explicit approval, never run silently.

2026-07-111

github-actions-cost-optimization

JeremyKuhne/agent-skills

Audit and reduce GitHub Actions runner usage and normalized cost without weakening required validation. Use when asked to reduce CI cost, spend, minutes, or job count; optimize workflow triggers, matrices, runner selection, caches, or artifact retention; eliminate duplicate Actions runs; or decide which checks should be automatic versus scheduled or manual. Not for application runtime performance, which belongs in a performance-testing workflow.

2026-07-111

framework-jit-optimization

JeremyKuhne/agent-skills

Optimize hot-path code for the `net481` (.NET Framework) target in a multi-targeted library's Framework-only sources. Use when writing or reviewing performance-sensitive loops, deciding whether to specialize a generic method for primitive types, choosing between scalar/unrolled/BCL-delegating implementations, or diagnosing why a net481 micro-benchmark regresses on the older RyuJIT. Also covers the modern .NET (net10) counterpart - vectorization, hardware intrinsics, struct-generic kernels, JIT-friendly shapes - and the cross-TFM codegen fundamentals shared by both targets (arithmetic and branchless lowering, struct layout, zero-allocation static data, hot-path allocation anti-patterns). For BenchmarkDotNet harness mechanics (authoring/running benchmarks, evaluating allocations) see the `performance-testing` skill.

2026-07-101

manage-skills

JeremyKuhne/agent-skills

Find, add, update, and share agent skills in this repo. Use when asked to "find a skill" for a task, "build a skill" or "create a skill" (this skill checks whether one already exists - in the repo, the shared commons, or a public catalog - before authoring a new one), "update a skill", or reconcile a local skill change against the upstream commons vs a repo-local overlay. Covers the find-first build path, the tiered search, and the pull/push update flow. Not for validating one agent file's syntax - that is `agent-files-review`.

2026-07-101

name	cswin32-interop
description	Guides CsWin32 P/Invoke interop in a multi-targeted .NET 10 and .NET Framework library. Consult when replacing [DllImport] with source-generated PInvoke.* calls, working with generated Windows.Win32 projections (HANDLE / HMODULE / HRESULT / BOOL and typed enum/constant types), configuring NativeMethods.txt / NativeMethods.json, composing a public PInvoke across foundation/owner/extender packages with extensionReceiver, deciding which support library owns a helper, auditing native allocation and byte/element lengths, selecting compile-time / runtime / analyzer guards for Windows-only code, or choosing between CsWin32 and [LibraryImport]. Not for managed-only changes with no native boundary. Paired with the cswin32-com skill for the struct-based COM layer.
license	MIT
compatibility	Requires the .NET SDK and the Microsoft.Windows.CsWin32 source generator; projects Windows APIs across .NET 10 and .NET Framework. Owner/extender composition requires C# 14.
metadata	{"portability":"portable","applicability":"dotnet","binding":"optional-overlay","risk":"local-write","maturity":"canary","requires":"none","related":"cswin32-com, dotnet-polyfills, scratch-buffer-strategy, security-review"}

CsWin32 P/Invoke interop

If overlay.md exists beside this file, read it before acting; it contains repository-specific bindings. This core remains usable without it.

This skill is the general P/Invoke layer. The struct-based COM layer builds on it - see the paired cswin32-com skill, whose vtable methods follow the same blittable-signatures rules.

Rules

Replace a hand-written [DllImport] with PInvoke.* when CsWin32 can project the API. After verifying the generated declaration and supporting types, delete their hand-written equivalents. Keep a source-generated [LibraryImport] on .NET 10 and [DllImport] on .NET Framework for an export absent from the available Win32 metadata. See types-and-constants.md.
Use the generated types directly (HANDLE, HMODULE, HRESULT.S_OK, FILE_FLAGS_AND_ATTRIBUTES, ...). Never keep a parallel local copy of a Win32 enum or struct CsWin32 already projects.
Call the generated method directly - no thin wrapper. Within one ownership layer, generate once and share internal types with friend assemblies. When a downstream package intentionally extends a public owner, use the owner/extender composition model instead.
Prefer CsWin32 for Windows APIs present in its metadata. Use [LibraryImport] (or [DllImport] on .NET Framework) for private, custom, or otherwise unprojectable Windows exports and for non-Windows native calls such as libc. Keep those signatures blittable under the same rules.
Preserve the original error-handling contract when migrating. Check the old declaration for PreserveSig / SetLastError / BOOL / HRESULT semantics and reproduce them: PreserveSig=false becomes .ThrowOnFailure(); SetLastError=true plus a failed BOOL becomes throw new Win32Exception(). Silently returning where the old code threw is a behavior change. The paired cswin32-com skill has the COM-side parity table.
Keep signatures blittable. CsWin32 is configured allowMarshaling: false, so every [DllImport] and every COM vtable method must be blittable. The full rule set is in blittable-signatures.md.
Audit ownership and size units. Generated wrappers do not decide which allocator frees an output, whether a COM reference remains caller-owned, or whether a length is bytes or elements. Record and test those contracts using ownership-and-units.md.

Platform and target-framework guards

Configuration

NativeMethods.txt - one API / type / constant name per line; the generator projects each and pulls in its dependencies.
NativeMethods.json - generator options. allowMarshaling: false (raw blittable signatures, no marshaller) and useSafeHandles: false are the interop-friendly defaults these skills assume.
Run the generator in a single project within an ownership layer and share via InternalsVisibleTo rather than adding CsWin32 to every implementation project. A package that extends another package's public projection is a separate layer: configure className / extensionReceiver as described in composition.md.

Source generator versus build task

Sibling pages

blittable-signatures.md - the signature rules shared by [DllImport] and COM vtables (HRESULT, T** vs out T*, void*, nint, PCWSTR / PWSTR, typed enum parameters).
types-and-constants.md - using the generated handle / enum / constant projections, "grep the metadata before redefining", type conversions, FILETIME, and native integers.
composition.md - composing one public PInvoke across an owner package and downstream extender, including constants, XML docs, and package verification.
library-layering.md - placing generic utilities, shared Win32 support, domain extensions, and applications in a directed package stack, with migration and release ordering.
ownership-and-units.md - matching native allocators and deallocators, caller-owned COM references, failure cleanup, and byte-versus-element conversions.
gating.md - source inclusion, runtime and TFM guards, CA1416, a stack-first scratch-buffer strategy, and guarded-build verification.