WPF-Control v1.3.0 版本发行说明

v1.3.0 是一次面向现代 WPF 应用开发的架构升级版本。本版本以 .NET 8、模块化、统一配置、应用基础设施和扩展能力 为重点，进一步完善了主窗口、主题、设置、消息、日志、插件、国际化及在线更新等功能。

以下内容根据 v1.3.0 相关代码结构与功能整理，不按 Git 文件增删记录逐项罗列。

版本亮点

• 全面适配 .NET 8 WPF。
• 重构应用启动和模块注册体系。
• 主窗口类型调整为可继承的抽象基类。
• 完善主题、样式和运行时主题切换能力。
• 增强设置持久化、应用路径和关闭保存流程。
• 增加插件发现与插件服务注册机制。
• 增加第三方依赖及许可证展示模块。
• 完善文件日志和应用内日志体系。
• 完善国际化及语言切换能力。
• 增加在线版本检查和安装包下载能力。
• 补充多个模块的开发和二次开发文档。

1. 升级至 .NET 8

项目统一面向 .NET 8 WPF，充分利用现代 .NET 的依赖注入、Options、SDK 风格项目和运行时能力。

推荐项目配置：

<PropertyGroup>
  <TargetFramework>net8.0-windows</TargetFramework>
  <UseWPF>true</UseWPF>
</PropertyGroup>

建议开发环境：

• Visual Studio 2022
• .NET 8 SDK
• Windows 10 或更高版本

从旧版本升级时，需要检查所有业务项目、扩展项目和测试项目的目标框架及依赖包兼容性。

2. 应用基础架构升级

进一步完善 ApplicationBase，统一应用生命周期中的关键流程：

• 创建和构建依赖注入容器。
• 加载模块 Options。
• 加载设置和默认模板。
• 显示启动画面。
• 执行登录和身份认证。
• 创建主窗口。
• 恢复主窗口尺寸及状态。
• 执行主窗口加载服务。
• 处理未捕获异常。
• 应用退出时保存设置和业务状态。

新增或完善以下应用基础项目：

• H.ApplicationBases.Default
• H.ApplicationBases.Modules
• H.ApplicationBases.Themes
• H.ApplicationBases.Identify

应用可以选择基础的 ApplicationBase，也可以使用预组合的应用基类快速启用默认模块、主题和身份认证。

3. 服务注册与应用配置分离

模块统一采用两阶段配置方式：

protected override void ConfigureServices(
    IServiceCollection services)
{
    services.AddXxx(options =>
    {
        // 注册服务并配置标准 Options。
    });
}

protected override void Configure(IApplicationBuilder app)
{
    app.UseXxxOptions(options =>
    {
        // 配置运行时单例并加入设置系统。
    });
}

主要收益：

• 明确服务注册和运行时配置的职责。
• 统一模块初始化方式。
• 方便替换默认服务实现。
• 便于将模块设置接入 IocSetting。
• 减少应用启动代码中的重复逻辑。

4. 主窗口体系重构

主窗口框架类型调整为抽象基类：

• MainWindow 调整为 MainWindowBase。
• TransparencyMainWindow 调整为 TransparencyMainWindowBase。

MainWindowBase 提供：

• 自定义标题栏。
• 标题栏高度配置。
• 标题栏扩展模板。
• 侧栏模板。
• 最小化、最大化、还原和关闭命令。
• Adorner 和窗口级消息承载区域。
• 主窗口状态保存及恢复支持。
• 关闭前确认和统一保存流程。

升级后的主窗口示例：

<h:MainWindowBase
    x:Class="MyApp.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:h="https://github.com/HeBianGu"
    Title="MyApp">
    <Grid />
</h:MainWindowBase>

透明主窗口应继承：

TransparencyMainWindowBase

这是本版本需要重点关注的 API 兼容性变化。

5. 主窗口状态与关闭保存

完善 MainWindowOption 和 IMainWindowSavableService：

• 保存窗口宽度和高度。
• 保存窗口状态。
• 保存启动位置。
• 应用启动时恢复主窗口状态。
• 支持替换默认状态保存服务。

完善主窗口关闭流程：

• 支持关闭前确认。
• 支持保存已注册的设置项。
• 支持执行 ISplashSave 业务保存服务。
• 支持取消关闭。
• 避免业务模块分别实现重复的退出保存逻辑。

6. 主题和样式能力增强

进一步拆分主题与样式职责：

• H.Theme 提供主题基础能力。
• H.Style 提供默认控件样式。
• 颜色主题作为独立项目提供。
• 字体、布局、颜色和控件样式可以分别组合。

完善以下主题能力：

• 颜色主题切换。
• 字体大小配置。
• 布局尺寸配置。
• 图标字体配置。
• 主题设置持久化。
• 运行时动态资源更新。
• 主窗口和对话框主题适配。

推荐在自定义控件中使用语义资源：

<Border
    Background="{DynamicResource {x:Static h:BrushKeys.Background}}"
    Padding="{DynamicResource {x:Static h:LayoutKeys.Padding}}" />

避免在通用控件和模板中硬编码颜色及尺寸。

7. 设置系统增强

设置系统进一步统一到 IocSetting：

• 支持模块 Options 自动加入设置集合。
• 支持 JSON 持久化。
• 支持恢复默认设置。
• 支持默认设置模板。
• 支持应用级和登录用户级设置。
• 支持设置页面自动展示。
• 支持主窗口关闭时统一保存。
• 支持设置安全控制和显示控制。

设置目录由 AppPaths 统一管理，避免业务模块自行拼接文件路径。

8. 系统路径服务完善

完善 AppPaths、IAppPathServce、AppPathServce 和 AppDomianPaths。

统一管理：

• 应用数据目录。
• 设置目录。
• 配置目录。
• 日志目录。
• 缓存目录。
• 项目目录。
• 模板目录。
• 许可证目录。
• 登录用户独立目录。

同时约定应用运行目录中的静态目录：

Assets
Modules
Components
Plugins
Versions

支持通过公司名、应用名及版本号隔离不同应用和版本的数据。

9. 消息与对话框体系增强

统一窗口消息、对话框和 Presenter 展示方式：

• 窗口消息。
• Adorner 对话框。
• 普通窗口对话框。
• Notice 通知。
• Snack 消息。
• 表单消息。
• IOC Presenter 展示命令。

业务模块可以通过消息服务展示 Presenter，无需直接创建具体窗口，从而降低 ViewModel、Presenter 与窗口实现之间的耦合。

10. 插件模块

增加并完善 H.Modules.Plugin。

插件模块支持：

• 扫描应用目录下的 Plugins 文件夹。
• 递归发现插件 DLL。
• 使用程序集级 PluginAttribute 标记插件。
• 获取插件名称、分组和说明。
• 通过 IPluginService 注册插件服务。
• 调用插件的应用配置入口。
• 发现自定义扩展接口实现。
• 展示插件程序集路径、版本和文件信息。

插件程序集示例：

[assembly: Plugin(
    name: "报表插件",
    groupName: "业务插件",
    decription: "提供报表生成和导出功能")]

插件入口示例：

public sealed class ReportPluginService : IPluginService
{
    public IServiceCollection AddPluginService(
        IServiceCollection services)
    {
        services.AddSingleton<IReportService, ReportService>();
        return services;
    }

    public IApplicationBuilder UsePluginOptions(
        IApplicationBuilder builder)
    {
        return builder;
    }
}

当前插件机制属于启动期扩展，不提供独立加载上下文、运行时卸载和依赖版本隔离。

11. 第三方依赖展示模块

增加并完善 H.Modules.Dependency。

该模块用于集中展示应用使用的第三方组件信息：

• 名称。
• 作者。
• 版本。
• 许可证。
• 官方网站或源码地址。
• 用途说明。
• 分类分组。

提供多个内置依赖条目，并支持通过 DependencyItemBase 创建自定义依赖信息。

可通过 ShowDependenciesCommand 打开第三方依赖页面，适用于“关于软件”、开源许可证和产品合规信息展示。

12. 日志体系升级

日志能力拆分为三个层次：

• H.Services.Logger：日志接口和静态入口。
• H.Extensions.Log4net：文件日志实现。
• H.Modules.Logger：应用内日志展示。

统一日志入口：

IocLog.Debug("开始加载配置");
IocLog.Info("应用启动完成");
IocLog.Warn("未找到用户模板");
IocLog.Error(exception);
IocLog.Fatal("核心服务初始化失败");

支持的日志级别：

• Debug
• Info
• Error
• Warn
• Fatal

文件日志支持：

• 按日期创建目录。
• 按时间滚动文件。
• 自定义日志目录。
• 日志级别过滤。
• 异常对象记录。
• 打开日志目录。

应用内日志支持：

• 展示最近日志。
• 显示时间、级别和消息。
• 不同级别使用不同图标及颜色。
• 配置最大日志容量。
• 最新日志优先显示。

13. 国际化能力增强

完善 H.Modules.Globalization：

• 自动扫描卫星资源程序集。
• 自动生成支持的语言列表。
• 设置当前线程的 CultureInfo。
• 设置 WPF Dispatcher 线程区域信息。
• 保存用户语言选择。
• 语言切换后提示重新启动。
• 无匹配语言时回退到 zh-Hans。

语言设置可以通过统一设置页面或 ShowGlobalizationViewCommand 展示。

14. 在线更新模块

完善 H.Modules.Upgrade：

• 通过远程 XML 清单检查更新。
• 比较入口程序集版本。
• 显示新版本号。
• 显示更新说明。
• 支持手动检查更新。
• 支持内置安装包下载。
• 支持下载进度显示。
• 支持调用系统浏览器下载。
• 支持启动 .msi、.exe 和 .zip 文件。
• 支持替换 IUpgradeService。

更新清单示例：

<?xml version="1.0" encoding="utf-8"?>
<item>
  <url>https://example.com/MyApp-1.3.0.exe</url>
  <changelog>优化应用架构;增加插件支持;完善日志功能</changelog>
  <version>1.3.0.0</version>
  <force>false</force>
</item>

可以通过 ShowUpgradeCommand 提供“检查更新”菜单。

15. 帮助与产品信息模块完善

完善帮助相关模块：

• 关于软件。
• 联系方式。
• 官方网站。
• 技术支持。
• 反馈。
• 赞助。
• 发行说明。
• 商业许可。
• 新手向导。

相关功能统一通过 Options 和 IOC 服务配置，并支持通过命令打开对应页面或链接。

16. 登录与身份认证能力完善

进一步拆分登录、身份和权限能力：

• 登录页面和登录服务。
• 用户身份信息。
• 权限验证。
• 角色和用户数据。
• 登录前后加载流程。
• 登录用户独立设置及数据目录。
• 身份认证应用基类。

应用可以使用 H.ApplicationBases.Identify 快速启用默认身份认证组合。

17. 项目及业务数据管理增强

完善项目模块和服务接口：

• 项目创建。
• 项目打开。
• 项目编辑。
• 项目保存。
• 最近项目记录。
• 当前项目管理。
• 项目关闭。
• 项目路径及模板管理。
• 关闭应用前保存项目状态。

项目能力通过服务接口、命令和 Presenter 解耦，便于业务应用替换默认实现。

18. Presenter 和 MVVM 扩展

进一步完善 Presenter 驱动的 UI 组织方式：

• Presenter 可通过 IOC 注册。
• 消息服务负责展示 Presenter。
• 命令不再直接依赖具体窗口。
• 支持 DataTemplate 自动匹配 Presenter。
• 支持通用表单、列表和仓储 Presenter。
• 支持显示名称、图标、权限及可见性元数据。

这使业务模块可以更方便地独立开发和复用。

19. 控件及扩展能力完善

本版本继续完善多个控件和扩展项目，包括但不限于：

• 表单及属性项。
• PropertyGrid。
• Diagram。
• ZoomBox。
• Dock。
• DrawerBox。
• TransitionBox。
• NavigationBox。
• FilterBox。
• TagBox。
• FavoriteBox。
• RepositoryBox。
• ScheduleBox。
• PDF、VLC、二维码及打印相关控件。
• 数据库、Excel、邮件、FFmpeg 和压缩等扩展。

各能力进一步按照控件、服务、扩展和 Presenter 分层组织。

20. 开发文档完善

补充并整理了多个专项开发文档：

• ApplicationBase 应用基础架构
• 主窗口开发
• 系统路径服务
• IOC 与依赖注入
• 设置系统
• 消息与对话框
• 主题与样式
• 国际化
• 登录与身份认证
• 插件开发
• 第三方依赖展示
• 日志系统
• 在线更新
• 项目管理
• 启动画面
• Presenter 与常用控件

文档重点补充了注册方式、扩展点、配置流程和二次开发注意事项。

兼容性变化

主窗口类型调整

旧代码：

<h:MainWindow />

升级后：

<h:MainWindowBase />

透明主窗口由：

TransparencyMainWindow

调整为：

TransparencyMainWindowBase

应用自身仍可将具体窗口类命名为 MainWindow。

目标框架调整

应用和扩展项目需要升级至：

net8.0-windows

旧版 .NET Framework 项目不能直接引用当前 .NET 8 程序集。

模块注册方式调整

部分模块需要同时调用：

AddXxx()
UseXxxOptions()

仅注册服务而未注册 Options，可能导致设置界面、设置持久化或运行时配置不生效。

主题资源使用调整

自定义控件和模板建议改用 DynamicResource，以支持运行时主题切换。

保留的 API 拼写

为保持现有 API 兼容，部分名称继续采用源码中的原有拼写：

• CaptionTempate
• AppPathServce
• AppDomianPaths
• ShowAppLogerCommmand
• Log4netOptions.tempPath

调用时应使用实际 API 名称。

从 v1.2.0 升级建议

1. 将所有项目目标框架升级至 .NET 8。
2. 更新 WPF-Control 项目或 NuGet 包引用。
3. 将主窗口改为继承 MainWindowBase。
4. 将透明主窗口改为继承 TransparencyMainWindowBase。
5. 检查所有模块的 AddXxx() 注册。
6. 检查所有模块的 UseXxxOptions() 配置。
7. 将需要持久化的设置加入 IocSetting。
8. 检查主题资源键和自定义窗口模板。
9. 检查设置、缓存、日志和插件目录权限。
10. 检查主窗口关闭时的业务保存流程。
11. 验证登录、启动页和主窗口加载顺序。
12. 验证插件程序集和共享依赖版本。
13. 验证日志文件输出及应用日志页面。
14. 验证在线更新清单和安装包下载地址。
15. 完整回归主题切换、国际化、消息及对话框功能。

已知限制

• 插件模块暂不支持热加载、卸载及独立依赖隔离。
• 在线更新模块不提供安装包签名和哈希校验。
• 默认更新下载器不支持断点续传。
• 默认应用内日志需要注意后台线程更新集合的问题。
• 部分 Options 已公开，但默认实现尚未使用全部配置项。
• 部分历史 API 保留了原有拼写。
• 主窗口及透明主窗口基类调整可能需要修改现有 XAML。

总结

v1.3.0 将 WPF-Control 从以控件为主的项目进一步升级为完整的模块化 WPF 应用开发框架。

本版本不仅增强了控件和主题能力，也补齐了现代桌面应用常用的基础设施，包括：

• 应用生命周期
• 依赖注入
• 模块配置
• 设置持久化
• 主窗口管理
• 消息与对话框
• 日志
• 插件
• 国际化
• 身份认证
• 第三方依赖展示
• 在线更新

该版本为后续 v1.4.0 的功能演进和架构优化奠定了基础。

release version v1.1.0

1、部分代码重构
2、新增主题样式
3、新增部分通用模块
4、修复部分BUG

release version v1.0.4

release version v1.0.3

release version v1.0.2