XFE Git
XFE Studio Git
Git 首页 全局搜索
XFE 主站 文档 NuGet

XFEToolBox

【WPF】XFE工具箱

公开
关注 0 Fork 0 Star 0
2.46 KB
6.27 KB
11.08 KB
README.md

XFEToolBox

XFEToolBox Logo

XFEToolBox 是一个基于 .NET 10 与 WPF 的 Windows 桌面工具箱。项目由桌面客户端、工具与软件下载服务端、共享契约、测试程序和安装器组成,当前程序集版本为 0.2.0

项目仍在持续开发中,界面、服务接口和工具包规范可能继续调整。请勿在生产环境中使用默认管理员密码或未经审核的源码工具包。

主要功能

  • WPF 桌面客户端:提供主页、控制台、工具库、软件下载、设置和个人中心。
  • XFEToolBox Code Studio:使用 Monaco Editor 与 WebView2 创建和编辑 WPF 源码工具,可预览、独立编译运行、导出或发布 .xfetool 工具包。
  • 工具分发:服务端校验、保存和发布源码工具包;客户端在下载后校验 SHA-256,并在独立窗口中编译运行。
  • 软件下载目录:支持搜索、分类、多下载渠道、浏览器跳转、客户端下载和服务端文件托管。
  • 账号与管理:支持注册、登录、个人资料以及管理员侧的用户、工具包和软件目录管理。

环境要求

  • Windows 10 1809(Build 17763)或更高版本,用于运行 WPF 客户端。
  • .NET 10 SDK
  • Microsoft Edge WebView2 Runtime,用于 Code Studio 编辑器和 Markdown 预览。
  • 可选:支持 .NET 10 与 WPF 的 Visual Studio。

服务端和不依赖 WPF 的核心项目以 net10.0 为目标框架;完整解决方案建议在 Windows 上构建。

快速开始

克隆仓库并还原、构建解决方案:

git clone https://github.com/XFEstudio/XFEToolBox.git
Set-Location .\XFEToolBox
dotnet restore .\XFEToolBox.sln
dotnet build .\XFEToolBox.sln

启动桌面客户端:

dotnet run --project .\XFEToolBox\XFEToolBox.Client.csproj

启动服务端:

dotnet run --project .\XFEToolBox.Server\XFEToolBox.Server.csproj

服务端默认监听 http://localhost:3000/api。首次启动会生成 AutoConfig XML 配置及初始管理员 admin;默认密码为 ChangeMe_123!,登录后应立即修改。工具包和软件文件的默认数据目录位于服务端输出目录下的 Data,这些运行数据不应提交到仓库。

客户端当前通过 XFEToolBox/Utilities/Server/ClientSession.cs 中的 ApiAddress 连接已部署服务。联调本地服务时,请先将该地址切换为本地 API 地址。

测试

仓库中的验证项目是可直接运行的控制台程序。客户端与 WPF 项目仍使用兼容期内的 SMTest 基准标记,因此需要显式传入 --benchmarks

dotnet run --project .\XFEToolBox.Test\XFEToolBox.Client.Test.csproj --configuration Release -- --benchmarks --quick
dotnet run --project .\XFEToolBox.Server.Test\XFEToolBox.Server.Test.csproj
dotnet run --project .\XFEToolBox.Client.Wpf.Test\XFEToolBox.Client.Wpf.Test.csproj --configuration Release -- --benchmarks --quick

最后一项会初始化 WPF 和图形环境,应在 Windows 桌面会话中运行。SMTest 已被测试框架标记为弃用,后续应迁移到 Benchmark

项目结构

路径 说明
XFEToolBox/ WPF 桌面客户端与 Code Studio
XFEToolBox.WpfCore/ 客户端、安装器与源码工具共享的 WPF 控件、主题、行为和窗口适配
XFEToolBox.Client.Core/ 客户端可复用的非 WPF 基础能力
XFEToolBox.Core/ 客户端与服务端共享的模型、契约和目录客户端
XFEToolBox.Server/ 服务端入口、用户体系、目录与管理接口
XFEToolBox.Server.Core/ 工具包校验、语义化版本与文件仓库实现
XFEToolBox.Client.Installer/ WPF 安装器项目
XFEToolBox.Test/ 客户端核心测试
XFEToolBox.Server.Test/ 服务端核心测试
XFEToolBox.Client.Wpf.Test/ WPF 渲染与性能测试
docs/ 功能与扩展规范

文档

贡献与许可

欢迎提交问题和改进。开始编码前请阅读 CONTRIBUTING.md,并确保构建及相关测试通过。

本项目采用 Apache License 2.0 许可。

LICENSE.txt Apache-2.0
                             Apache License
                       Version 2.0, January 2004
                    http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

  1. Definitions.

    "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.

    "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.

    "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.

    "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.

    "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.

    "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.

    "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).

    "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.

    "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."

    "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.

  2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.

  3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.

  4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:

    (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and

    (b) You must cause any modified files to carry prominent notices stating that You changed the files; and

    (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and

    (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.

    You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.

  5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.

  6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.

  7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.

  8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.

  9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

APPENDIX: How to apply the Apache License to your work.

  To apply the Apache License to your work, attach the following
  boilerplate notice, with the fields enclosed by brackets "[]"
  replaced with your own identifying information. (Don't include
  the brackets!)  The text should be enclosed in the appropriate
  comment syntax for the file format. We also recommend that a
  file or class name and description of purpose be included on the
  same "printed page" as the copyright notice for easier
  identification within third-party archives.

Copyright [2024] [XFEstudio]

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

CONTRIBUTING.md

为 XFEToolBox 贡献

感谢你愿意改进 XFEToolBox。本文说明本地开发、测试、提交和文档维护的约定,适用于客户端、服务端、共享核心与工具包规范。

开始之前

  • 使用 Windows 与 .NET 10 SDK;涉及 Code Studio 时还需要 Microsoft Edge WebView2 Runtime。
  • 先搜索已有 Issue 和 Pull Request,避免重复工作。较大的功能、公共契约变更或界面重构建议先发 Issue 说明目标和方案。
  • dev 是日常开发分支。请从最新的 dev 创建短生命周期分支,并将 Pull Request 合并目标设为 dev
  • 不要提交密码、管理密钥、登录令牌、AutoConfig 生成的本地配置、服务端 Data、日志、构建产物或个人 IDE 设置。

本地开发

git clone https://github.com/XFEstudio/XFEToolBox.git
Set-Location .\XFEToolBox
git switch dev
git pull --ff-only
git switch -c feature/short-topic
dotnet restore .\XFEToolBox.sln
dotnet build .\XFEToolBox.sln

常用启动命令:

# WPF 客户端
dotnet run --project .\XFEToolBox\XFEToolBox.Client.csproj

# 服务端
dotnet run --project .\XFEToolBox.Server\XFEToolBox.Server.csproj

服务端首次运行会创建管理员 admin,默认密码为 ChangeMe_123!。该账号仅用于本地初始化,首次登录后应立即修改密码。若要让客户端连接本地服务,需要同步调整 ClientSession.ApiAddress;请勿把个人环境地址意外提交到 Pull Request。

代码约定

  • 遵循现有 C# 风格:启用 Nullable 与 Implicit Usings,优先使用文件范围命名空间、清晰的类型名和早返回。
  • 异步 I/O 使用 async/await 并以 Async 结尾;可传播的调用应继续传递 CancellationToken
  • 公共契约放在 XFEToolBox.Core,客户端专用的非 UI 能力放在 XFEToolBox.Client.Core,服务端存储与校验放在 XFEToolBox.Server.Core
  • WPF 页面保持 View、ViewModel 和业务服务边界清晰。客户端与安装器共用的控件、行为、主题或窗口适配应放入 XFEToolBox.WpfCore;新增样式前先复用现有 ResourceDictionary、控件和主题资源。
  • 用户可见文字应明确、可操作;同一功能内保持中英文术语一致。
  • 文件、ZIP、下载地址和用户输入必须在信任边界处校验。不要降低路径穿越、符号链接、文件数量、解压大小、压缩率或 SHA-256 校验等安全限制。
  • 不要静默吞掉会影响数据、登录、下载或发布结果的异常;应记录或向用户显示有意义的信息。
  • 保持修改聚焦,避免把无关格式化、资源重排或生成文件混入同一提交。

工具包与服务端变更

修改 .xfetool 清单、目录契约或接口时,需要同时检查以下位置:

  • XFEToolBox.Core 中的共享模型与客户端契约;
  • XFEToolBox.Server.Core 中的校验和存储;
  • XFEToolBox.Server 中的公开及管理接口;
  • WPF 客户端中的 Code Studio、下载、缓存和运行流程;
  • docs/tool-packages.mddocs/software-catalog.md 中的示例与限制。

破坏兼容性的工具包变更应提升 packageFormatVersion,并明确旧版本的迁移或拒绝策略。新增管理员能力时,应继续校验登录态和管理员角色;遗留的 API Key 接口不得暴露到不受信网络。

测试与验证

提交前至少构建整个解决方案,并运行与修改范围相关的测试:

dotnet build .\XFEToolBox.sln --configuration Release
dotnet run --project .\XFEToolBox.Test\XFEToolBox.Client.Test.csproj --configuration Release -- --benchmarks --quick
dotnet run --project .\XFEToolBox.Server.Test\XFEToolBox.Server.Test.csproj --configuration Release
dotnet run --project .\XFEToolBox.Client.Wpf.Test\XFEToolBox.Client.Wpf.Test.csproj --configuration Release -- --benchmarks --quick

客户端与 WPF 验证当前使用兼容期内的 SMTest 基准标记;缺少 --benchmarks 时运行器会发现 0 项。新增代码应使用当前测试框架的 Test/TestCaseBenchmark,不要继续增加 SMTest

涉及 WPF 的改动还应手动检查窗口缩放、DPI、滚动、键盘操作、空数据、错误状态和主题资源;涉及服务端的改动应检查未登录、普通用户、管理员、非法输入和大小边界。

若某项测试受环境限制无法运行,请在 Pull Request 中写明未运行的命令、原因和已完成的替代验证。

提交和 Pull Request

提交信息使用简短、具体的中文或英文,说明实际结果,例如 修复工具包路径校验。一个提交尽量只表达一个逻辑变更。

Pull Request 应包含:

  • 变更目的和用户可见效果;
  • 关键实现与兼容性、安全性说明;
  • 实际运行过的构建、测试和手动验证;
  • UI 变更前后的截图或录屏;
  • 关联的 Issue,以及仍待处理的限制。

提交前检查:

  • 修改范围聚焦,未覆盖他人的无关改动。
  • 未包含密钥、令牌、本地配置、运行数据或生成产物。
  • Debug/Release 构建和相关测试通过,或已说明限制。
  • 新行为有测试覆盖,边界和失败路径已验证。
  • 公共接口、配置、工具包格式或用户流程变化已同步更新文档。
  • UI 变更已进行人工视觉检查。

报告安全问题

发现认证绕过、任意文件访问、危险工具包执行或敏感信息泄露时,请不要在公开 Issue 中披露利用细节。应通过仓库维护者提供的私密联系方式报告,并附上影响范围、复现条件和建议修复方向。