WinSW 贡献指南：环境准备、源码构建与测试验证全流程

WinSW 贡献指南环境准备、源码构建与测试验证全流程【免费下载链接】winswA wrapper executable that can run any executable as a Windows service, in a permissive license.项目地址: https://gitcode.com/gh_mirrors/wi/winswWinSWWindows Service Wrapper是一个以宽松许可MIT发布的可执行程序包装器它能把任意可执行程序包装并管理为 Windows 服务。本文基于仓库根目录的 CONTRIBUTING.md 撰写面向希望参与 WinSW 开发、贡献代码或自行构建源码的开发者完整覆盖从开发环境搭建、Visual Studio 与 .NET CLI 两种开发方式、构建与测试命令到仓库源码结构导航、测试组织与代码质量门槛的实战全流程。读完本文你将能够在本仓库默认分支WinSW 3.x 开发主线见 README.md上独立完成一次拉取代码 → 构建 → 运行测试 → 验证修改的完整开发闭环。一、前置条件开发环境总览CONTRIBUTING.md 对贡献者提出的环境要求非常明确.NET SDK7.0 或更高版本外加你熟悉的代码编辑器。由于 WinSW 本质上是一个 Windows 服务包装器其开发、构建与调试都围绕 Windows 平台展开。组件版本要求说明.NET SDK7.0 或更高构建与测试的核心工具链Visual Studio2022 或更高需安装.NET 桌面开发.NET desktop development工作负载Visual Studio Code最新版需安装 [C# for Visual Studio Code] 扩展官方 C# 扩展从源码看这一版本要求与项目的多目标框架TFM设计直接相关。WinSW 主程序项目文件 声明了双目标框架TargetFrameworksnet461;net7.0-windows/TargetFrameworks也就是说同一份源码既要面向 .NET Framework 4.6.1 编译对应旧版 Windows 与无 .NET 运行时的系统也要面向 .NET 7Windows编译。测试项目 WinSW.Tests.csproj 则面向net471;net7.0-windows两个目标框架。因此本地至少安装 .NET SDK 7.0才能让两个目标框架都能完成编译与测试。二、在 Visual Studio 中开发CONTRIBUTING.md 给出的 Visual Studio 使用方式极为简洁直接打开解决方案文件src\WinSW.sln然后即可在 IDE 内完成构建并运行测试。从 解决方案文件 的实际内容看WinSW.sln共包含 5 个项目构成了完整的工程拓扑项目角色WinSW主可执行程序wrapper 可执行体含命令行入口WinSW.Core核心库承载配置解析、服务包装、日志、扩展等主要逻辑WinSW.Plugins插件程序集WinSW.TasksMSBuild 自定义任务如发布后 Trim 处理WinSW.TestsxUnit 测试项目此外解决方案还挂载了两个解决方案项.editorconfig与.runsettings前者用于统一编辑器/IDE 的代码风格后者则作为测试运行配置Directory.Build.props中通过RunSettingsFilePath指定了 .runsettings 位置。测试项目的运行行为还受到 xunit.runner.json 约束shadowCopy: false关闭程序集卷影复制便于调试与代码覆盖率收集。提示Visual Studio 打开解决方案后直接使用CtrlShiftB生成解决方案与Test Explorer测试资源管理器即可完成与命令行等价的构建与测试操作。三、使用 .NET CLI 构建与测试CONTRIBUTING.md 提供了两条核心命令这也是 CI 与本地验证最直接的方式注意原文使用 Windows 风格的反斜杠路径在 Windows 终端中可直接执行3.1 构建dotnet build src\WinSW.sln构建产物统一输出到仓库根目录下的artifacts目录。Directory.Build.props 中对输出布局做了集中定义ArtifactsDir$(MSBuildThisFileDirectory)artifacts\/ArtifactsDir ArtifactsBinDir$(ArtifactsDir)bin\/ArtifactsBinDir ArtifactsPublishDir$(ArtifactsDir)publish\/ArtifactsPublishDir因此artifacts\bin下按项目名分目录存放编译结果artifacts\publish存放发布结果如合并后的单文件可执行体这与常规 SDK 项目默认输出到bin/、obj/的习惯不同是 WinSW 仓库刻意设计的统一布局。在构建过程中还有两个值得新贡献者注意的细节net461 目标会执行 ILMerge 合并WinSW.csproj 中定义了一个Merge目标将WinSW.Core.dll、WinSW.Plugins.dll、log4net.dll、System.CommandLine.dll等程序集通过 ILMerge 合并进单个WinSW-net461.exe之后再由WinSW.Tasks.Trim任务对产物做裁剪。net7.0-windows 目标会执行单文件发布与裁剪WinSW.csproj 在指定 RuntimeIdentifier 时启用PublishSingleFile、PublishTrimmedTrimModepartial从而产出原生自包含的可执行文件。3.2 测试dotnet test src\WinSW.sln该命令会为解决方案中的测试项目WinSW.Tests编译并执行全部 xUnit 测试。测试项目依赖的测试栈见 WinSW.Tests.csproj包括xunit 2.4.2与xunit.runner.visualstudio 2.4.5测试框架与 VS 测试适配器Microsoft.NET.Test.Sdk 17.5.0.NET 测试宿主coverlet.collector 3.1.0代码覆盖率收集器Microsoft.Diagnostics.Runtime用于进程/内存诊断相关测试Microsoft.Windows.CsWin32Win32 API 的 C# 互操作生成器与NativeMethods.txt配套。如果只想运行部分用例可以借助 .NET CLI 自带的--filter参数按类名或特性筛选这是 .NET CLI 的通用能力例如按测试类名过滤dotnet test src\WinSW.Tests\WinSW.Tests.csproj --filter FullyQualifiedName~ServiceConfigTests注意由于测试项目同时面向net471与net7.0-windows在非 Windows 环境下部分目标框架尤其是依赖 Windows 服务 API 的用例无法执行建议在 Windows 上完成完整验证。四、源码结构导航新贡献者的第一张地图CONTRIBUTING.md 本身篇幅精简但仓库内 docs/developer/project-structure.md 提供了官方的结构说明该文档还附有一场仓库代码走读录制的视频链接。结合当前仓库实际目录顶层布局如下|_ docs # 文档XML 配置规范、CLI 命令、日志、扩展、疑难解答等 |_ eng # 工程化相关文件 |_ samples # 配置模板样例 |_ src # 全部源代码 |_ WinSW # 主可执行程序Program.cs 入口、命令扩展、服务控制器扩展 |_ WinSW.Core # 核心库配置、扩展、日志、Native 互操作、Util、WrapperService 等 |_ WinSW.Plugins # 插件程序集 |_ WinSW.Tasks # MSBuild 任务如 Trim |_ WinSW.Tests # xUnit 测试对各源码目录的职责结合 project-structure.md 与实际文件清单可以总结为src/WinSW可执行程序外壳。Program.cs是程序入口负责命令行参数解析与主流程调度CommandExtensions.cs、ServiceControllerExtension.cs提供命令与服务控制器扩展能力日志输出由Logging/下的ServiceEventLogAppender.cs、WinSWConsoleAppender.cs承载。src/WinSW.Core项目真正的核心。Configuration/ServiceConfig.cs、XmlServiceConfig.cs、ProcessCommand.cs、SettingNames.cs负责从 XML 配置文件提取服务配置Extensions/实现插件 APIIWinSWExtension、WinSWExtensionManager等Native/封装了大量 Win32 API 互操作服务、进程、注册表、作业、凭据、文件等Util/提供FileHelper、XmlHelper等工具WrapperService.cs、WinSWSystem.cs则是服务包装的核心实现。src/WinSW.Tests测试套件详见下一节。samples/存放配置模板其中minimal.xml是最小必需配置模板complete.xml是带文档注释的全量配置模板这一说明来自 project-structure.md 对 samples 文件夹的描述。新贡献者在动手前建议按入口Program.cs→ 核心配置WinSW.Core/Configuration→ 服务包装WrapperService→ 测试WinSW.Tests的顺序阅读能够快速建立全局认知。五、测试组织了解现有测试再动手修改功能时CONTRIBUTING.md 虽然没有展开测试编写规范但测试项目本身提供了很好的参照。src/WinSW.Tests下按功能域组织了若干测试文件例如测试文件覆盖主题CommandLineTests.cs命令行解析与命令分发ServiceConfigTests.csXML 服务配置解析DownloadConfigTests.cs、DownloadTests.cs下载功能及其配置LogAppenderTests.cs日志追加器行为SharedDirectoryMapperTests.cs共享目录映射器MetadataTests.cs元数据相关Configuration/ExamplesTest.cs校验samples/中的示例配置可被正确解析测试基础设施方面Attributes/ElevatedFactAttribute.cs定义了一个需要管理员/提升权限才能执行的 xUnit 事实特性对应 WinSW 服务安装、控制类操作需要高权限的场景Util/下提供ConfigXmlBuilder、ServiceConfigAssert、CommandLineTestHelper、FilesystemTestHelper等辅助类用来简化构造 XML 配置 → 解析断言的常见测试模式。编写新测试时复用这些辅助类而非重新造轮子是与现有代码风格保持一致的好做法。六、代码质量门槛构建失败前先过静态关WinSW 仓库在代码质量上设了较高的门槛这主要体现在警告即错误Directory.Build.props 设置了TreatWarningsAsErrorstrue/TreatWarningsAsErrors。任何编译警告都会让构建失败因此在提交前务必保证代码零警告。这是新贡献者最容易踩到的坑例如未使用的变量、隐式类型转换等。代码风格约束仓库根目录的Directory.Build.props通过AdditionalFiles引入了 src/stylecop.json配合解决方案项.editorconfig统一格式stylecop.json目前显式要求using指令放置在命名空间外usingDirectivesPlacement: outsideNamespace。ILLink 警告例外ILLinkTreatWarningsAsErrors被显式关闭见 Directory.Build.props表明对 .NET 7 裁剪trimming产生的链接器警告采取了宽容策略这属于有意为之而非疏漏。因此本地开发的建议流程是每次改动后先dotnet build确认零警告再dotnet test确认测试全绿两条命令都通过后再考虑提交。七、持续集成与产物根据 README.md 中的徽章与下载说明该仓库使用Azure Pipelines作为持续集成与发布平台构建徽章与部署徽章均指向 Azure DevOpsCI 构建产物也通过 Azure Pipelines 对外提供。这意味着你的提交合入前会在 CI 上自动执行构建与测试本地验证与 CI 验证应当保持一致的命令与标准。另外值得了解的分发渠道信息GitHub Releases 提供稳定版2.x与 3.x 预发布版可执行文件NuGet 与 Maven 包目前对应 2.x 版本3.x 的原生基于 .NET 732 位/64 位可执行文件面向未安装 .NET Framework 的系统提供以上均为 README 陈述的项目事实。八、调试 Windows 服务应用CONTRIBUTING.md 在文末See also部分指引贡献者查阅微软官方主题How to: Debug Windows Service Applications如何调试 Windows 服务应用程序。这一点对 WinSW 开发者尤其重要因为 WinSW 本身包装的就是 Windows 服务调试时无法像普通控制台程序那样直接附加调试器。结合仓库源码可以理解其调试的难点与切入点WrapperService.cs 实现了服务生命周期OnStart/OnStop等Native/Service.cs、Native/ServiceApis.cs封装了与 SCM服务控制管理器的互操作。调试此类代码时通常需要以管理员身份运行 Visual Studio、将调试器附加到正在运行的服务进程或在服务启动路径中预留交互/日志入口WinSW 自身的Logging/模块与docs/logging-and-error-reporting.md所描述的日志机制也是排查服务运行时问题的重要手段。具体的微软官方调试步骤请按 CONTRIBUTING.md 的指引在文档库中检索该主题。九、贡献流程速览综合 CONTRIBUTING.md 与 README.mdContributing一节明确欢迎贡献并指向 CONTRIBUTING.md一个规范的贡献过程应至少包含环境就绪安装 .NET SDK 7.0 与选定的编辑器Visual Studio 2022 或 VS Code C# 扩展。理解代码通过 docs/developer/project-structure.md 与 samples 建立对仓库结构的认识修改配置解析相关代码时务必阅读 XML 配置规范。构建验证dotnet build src\WinSW.sln确保在net461与net7.0-windows两个目标框架下均构建通过、零警告。测试验证dotnet test src\WinSW.sln全部用例通过若改动涉及新行为参照现有测试文件补充用例可借助ConfigXmlBuilder、ServiceConfigAssert等测试工具类。风格自查符合.editorconfig与 stylecop.json 的格式约定using 指令置于命名空间外等。提交改动以 Pull Request 方式将改动提交回仓库交由维护者与 CIAzure Pipelines进一步验证。按照这条路径你即可在本仓库只读镜像之外基于上游 WinSW 3.x 开发主线顺利开展自己的贡献工作。十、常见问题速查为什么dotnet build在我本机报警告错误因为仓库将警告视为错误TreatWarningsAsErrorstrue请消除全部警告再构建。为什么测试项目有两个目标框架测试项目面向net471与net7.0-windows前者覆盖 .NET Framework 场景后者覆盖 .NET 7 场景非 Windows 环境下无法完整执行依赖 Windows 服务 API 的用例。构建产物在哪里统一输出到仓库根目录artifacts/bin 与 publish 分离这是 Directory.Build.props 集中定义的布局。如何确认我的配置改动没有破坏现有样例运行测试项目中的 ExamplesTest.cs它会校验 samples 下的示例配置能够被正确解析。【免费下载链接】winswA wrapper executable that can run any executable as a Windows service, in a permissive license.项目地址: https://gitcode.com/gh_mirrors/wi/winsw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考