用途:指导在 MSBuild 代码库中使用 CsWin32 进行 Windows P/Invoke 互操作。CsWin32 用源生成的 PInvoke.* 调用替代 [DllImport];FEATURE_WINDOWSINTEROP 是编译期开关,源码构建会禁用它。本技能只覆盖通用 P/Invoke 层,基于结构体的 COM 互操作由配套技能 cswin32-com 覆盖。
主要能力与规则:用 PInvoke.* 替换 [DllImport],删除旧声明和手写结构体、枚举、常量;用 #if FEATURE_WINDOWSINTEROP 加守卫,并在内部加运行时 IsWindows 检查,两者都必需;直接使用 CsWin32 类型(HANDLE、HMODULE、HRESULT.S_OK、FILE_FLAGS_AND_ATTRIBUTES 等),直接调用 PInvoke.*,不加包装。Windows API 优先用 CsWin32;非 Windows 原生调用(如 libc)才用 [LibraryImport],并以 #if NET 守卫。需保留原错误处理契约:检查原 [DllImport] 的 PreserveSig / SetLastError / BOOL / HRESULT 语义并复现,PreserveSig=false 用 .ThrowOnFailure(),SetLastError=true 且 BOOL 失败时抛 Win32Exception。
blittable 签名:配置为 allowMarshaling: false,边界不做封送。HRESULT 返回类型用 HRESULT 而非 int,用 .ThrowOnFailure() 替代手写异常;宽字符串用 PCWSTR / PWSTR,不用托管 string;指针输出用 T** 而非 out T*;不透明参数用 void*,传 null 而非 IntPtr.Zero;原生大小整数优先 nint / nuint;签名中不得出现托管引用类型。标志参数应约束为带 [Flags] 的强类型枚举。
基础设施:FEATURE_WINDOWSINTEROP 与 $(FeatureWindowsInterop) 在 src/Directory.BeforeCommon.targets 中定义;CsWin32 配置位于 src/Framework/NativeMethods.txt 与 NativeMethods.json,其他项目通过 InternalsVisibleTo 使用,不要给其他项目添加 CsWin32。命名空间导入必须放在 #if FEATURE_WINDOWSINTEROP 内。
其他要点:常量替换遵循 CsWin32EnumType.ORIGINAL_NAME 模式,优先使用生成枚举;FILETIME 用 FileTimeExtensions 的 ToLong / ToDateTime / ToDateTimeUtc;缓冲区用 BufferScope<T>,始终配合 using,栈分配不超过 1024 字节。推送前必须同时运行普通构建与源码构建:dotnet msbuild MSBuild.Dev.slnf -v:q 和 dotnet msbuild MSBuild.SourceBuild.slnf /p:DotNetBuildSourceOnly=true -v:q,以捕获守卫内未使用成员等警告。限制:资料未提供收费、平台支持范围等额外信息。