快速开始

开发环境

后端开发，你必须具备：

安装 .NET 10 SDK 或更高版本
使用 Visual Studio 2026 或 JetBrains Rider 作为开发工具
使用 Redis 服务作为分布式缓存服务
使用 MySQL/Oracle 作为数据库

💡 建议：移动 nuget 缓存目录
powershell
[Environment]::SetEnvironmentVariable("NUGET_PACKAGES", "D:\env\.nuget", "User")

如果你使用 WinForm 作为前端，你必须准备：

安装 .NET 10 SDK 或更高版本
使用 Visual Studio 2026 作为开发工具
安装 DevExpress v25.2 的前端控件库

⚠️ 请采用静默安装方式，否则会要求填写账号密码：
bash
.\DevExpressNETComponentsSetup-25.2.8.exe /Q /EULA:accept "Windows Forms" "XtraReports" "Demos"
命令执行后请在任务管理器观察进程，一般会在3分钟之内完成。

如果你使用 WEB 作为前端，你必须准备：

NodeJS: >=18.12.0，推荐 18.19.0 或更高。建议采取 nvs 管理
pnpm: >= 8.7.0，推荐最新版本
推荐使用 VSCode 进行开发

Node.js 环境配置

bash

# 确认当前可用的 Node 版本
nvs ls

# 将目标版本设为全局默认
nvs link 22.18.0

# 为 npm 配置国内镜像源
npm config set registry https://registry.npmmirror.com/
npm config get registry

# 更新 Corepack 到最新版本
npm install --global corepack@latest

# 启用并安装 pnpm
corepack enable pnpm

# 配置 pnpm 存储目录
pnpm config set store-dir D:\env\pnpm-store

# 设置淘宝镜像源
pnpm config set registry https://registry.npmmirror.com/
pnpm config get registry

VSCode 推荐安装扩展

核心语言与框架支持（必装）

插件名称	插件标识	作用说明
Vue - Official	Vue.volar	Vue 3 官方插件，提供语法高亮、类型检查等核心能力
Prettier - Code formatter	esbenp.prettier-vscode	代码格式化工具，统一团队代码风格
ESLint	dbaeumer.vscode-eslint	代码检查工具，实时检查语法错误和风格问题
TypeScript Vue Plugin	Vue.vscode-typescript-vue-plugin	增强 TypeScript 对 Vue 文件的支持

UI 开发增强（高频推荐）

插件名称	插件标识	作用说明
Tailwind CSS IntelliSense	bradlc.vscode-tailwindcss	提供 CSS 类名补全、悬浮预览、代码提示
Color Highlight	naumovs.color-highlight	自动高亮颜色值，方便调整主题色
Vue VSCode Snippets	sdras.vue-vscode-snippets	提供 Vue 3 代码片段，输入 v3 快速生成模板

项目效率与协作（团队通用）

插件名称	插件标识	作用说明
GitLens	eamodio.gitlens	在代码行号旁显示最近提交信息、作者和时间
Git Graph	mhutchie.git-graph	可视化 Git 提交树，方便查看分支和合并历史
i18n Ally	lokalise.i18n-ally	多语言文件可视化，提供一键提取、翻译缺失提醒
DotENV	mikestead.dotenv	为 .env 环境变量文件提供语法高亮

编辑器美化与辅助（可选）

插件名称	插件标识	作用说明
Material Icon Theme	pkief.material-icon-theme	为文件类型提供清晰图标
One Dark Pro	zhuangtongfa.Material-theme	经典护眼深色代码主题
Auto Rename Tag	formulahendry.auto-rename-tag	自动重命名成对的 HTML/XML 标签
Auto Close Tag	formulahendry.auto-close-tag	自动添加关闭标签

新建项目

新建项目之前，我们先准备文件夹（建议遵守这个结构）：

Test/
├── Hello.Admin/           # 内置 admin 模块
├── Hello.Service/         # 项目服务端相关的项目代码
├── Hello.Winform/         # 项目前端相关的项目代码
└── startups/              # 程序启动相关的项目代码

第一步：拉取 Admin 代码

地址：https://cnb.cool/zhaxg/rv/hmx_admin/-/tree/rmes_core

拉取的最新代码放入到 Hello.Admin 里面：

Hmx.Service.Admin
Hmx.Service.Admin.Impl
Hmx.Service.Widgets
Hmx.Service.Widgets.Impl
Hmx.WinForms
Hmx.WinForms.Widgets

第二步：新建【启动】项目

以下新建的项目都在一个解决方案中

新建前端 WinForm 启动项目：

语言：C#，平台：Windows，项目类型：桌面 → Windows 窗体应用
项目名称：Hello.Winform.Startup
框架：.NET 10.0
项目存放位置：Test/startups 文件夹

新建后端 Service 启动项目：

语言：C#，平台：Windows，项目类型：Web → ASP.NET Core Web 应用
项目名称：Hello.Service.Startup
框架：.NET 10.0
项目存放位置：Test/startups 文件夹

第三步：新建【业务】项目

新建项目服务端使用的项目：Hello.Service

语言：C#，平台：Windows，项目类型：库 → 类库
项目名称：Hello.Service
框架：.NET Standard 2.0
项目存放位置：Test/Hello.Service 文件夹

新建项目服务端使用的项目：Hello.Service.Impl

语言：C#，平台：Windows，项目类型：库 → 类库
项目名称：Hello.Service.Impl
框架：.NET 10.0
项目存放位置：Test/Hello.Service 文件夹

第四步：新建【前端】项目（WinForm）

语言：C#，平台：Windows，项目类型：桌面 → Windows 窗体应用
项目名称：Hello.Winform
框架：net10.0-windows
项目存放位置：Test/Hello.Winform 文件夹

第五步：添加 Admin 项目到解决方案

结果如下图：

验证最终的项目结构

Test/
├── Hello.Admin/                    # 内置 admin 模块
│   ├── Hmx.Service.Admin           # 后台管理服务接口层
│   ├── Hmx.Service.Admin.Impl      # 后台管理服务实现层
│   └── Hmx.WinForms                # WinForm 桌面端核心库
│
├── Hello.Service/                  # 项目服务端相关的项目代码
│   ├── Hello.Service               # 业务服务接口层（类库）
│   └── Hello.Service.Impl          # 业务服务实现层（类库）
│
├── Hello.Winform/                  # 项目前端相关的项目代码
│   └── Hello.Winform               # WinForm 业务功能模块（类库）
│
└── startups/                       # 程序启动相关的项目代码
    ├── Hello.Service.Startup       # 后端 Web API 启动项目
    └── Hello.Winform.Startup       # 前端桌面端启动项目

项目引用关系

Hello.Winform.Startup

├── Hello.Winform
├── Hello.Service
├── Hmx.WinForms
└── Hmx.Service.Admin

Hello.Service.Startup

├── Hello.Service.Impl
└── Hmx.Service.Admin.Impl

Hello.Service.Impl

├── Hello.Service            （实现接口）
├── Hmx.Service.Admin        （调用/扩展）
├── Hmx.Service.Widgets      （调用/扩展）
└── Hmx.Http.Core            （NuGet 包引用，自行添加）

Hello.Winform

└── Hmx.WinForms

准备数据库

在 Admin 代码库的 scripts 文件夹找到 dbinit_****.sql 的脚本文件，比如 dbinit_postgresql.sql（按你自己的数据库对应）。

在你的数据库建立数据库，比如 Hello，然后执行 SQL 脚本导入现有的数据库表格和基础数据。

⚠️ 注意：如果你使用 PostgreSQL，特别注意数据库名称、表名和字段名的规则：
只使用 小写字母、数字和下划线，首字母必须为 小写字母
多个单词用 下划线 分隔（如 order_items，而不是 OrderItems 或 orderItems）

配置与运行项目

启动后端服务

第一步：新建启动模块

新建一个类 Hello/Hello.Service.Startup/Runtime/WebapiStartupModule.cs：

csharp

public class WebapiStartupModule : HiMindModule { }

这个类代表这是启动的入口模块，框架会自动扫描并解析他们项目的依赖关系。

第二步：修改配置文件

在后端服务的启动项目 Hello.Service.Startup 找到配置文件 appsettings.json，修改内容如下：

json

{
  "AppSettings": {
    "loglevel": "debug"
  },
  "ConnectionStrings": {
    "redis": "10.11.5.52:6379,password=*****",
    "masterdb": "PostgreSQL://Server=***.cn;Port=55432;Database=***;User Id=***;Password=***;",
    "orclcdb": "Oracle.Managed://User Id=*****;Password=******;Data Source=10.***/ORCLCDB;"
  }
}

masterdb 是主数据库

第三步：修改 Program.cs

找到 Hello/Hello.Service.Startup/Program.cs 修改为如下内容：

csharp

public class Program
{
    public static async Task Main(string[] args)
    {
        await Task.CompletedTask;
        Trace.Listeners.Add(new ConsoleTraceListener());

        var builder = WebApplication.CreateBuilder(args);
        builder.InitializeModules<WebapiStartupModule>();
        builder.Services.AddEventBusPlus(builder.Configuration);
        builder.Services.AddHostedService<HmxHostedLifetimeService>();

        var services = builder.Services;
        services.AddControllers().AddJsonOptions(opt =>
        {
            opt.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
            opt.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles;
        });

        services.AddCors(options =>
            options.AddPolicy("AllowAllLocalhost", policy =>
            {
                policy.SetIsOriginAllowed(origin =>
                {
                    return new Uri(origin).Host == "localhost";
                })
                .AllowAnyMethod()
                .AllowAnyHeader()
                .AllowCredentials();
            }));

        var app = builder.Build();
        app.UseHmxStaticFiles();
        app.UseTcpRpcServer();
        app.UseWebSocketRpcServer();
        app.UseAutoUpdateServer();
        app.PostInitHiMindApplication();
        app.MapControllers();
        app.Run();
    }
}

第四步：安装数据库驱动

给后端项目安装对应的数据库驱动，比如 Npgsql：

xml

<PackageReference Include="Npgsql" Version="10.0.2" />

第五步：编译启动

好了，大功告成，你可以编译启动 Hello.Service.Startup 这个 WEB-API 项目了！

如果你无法访问地址，尝试修改 Hello/Hello.Service.Startup/Properties/launchSettings.json：

json

"applicationUrl": "http://*:5185"  // 这里监听 * 任意

启动 WinForm 界面

第一步：添加配置文件

在 Hello/Hello.Winform.Startup/Hello.Winform.Startup.csproj 项目中，新添加 appsettings.json 配置文件：

json

{
  "AppSettings": {
    "loglevel": "debug"
  },
  "ConnectionStrings": {
    "dataPortalUrl": "http://127.0.0.1:5185/api"
  }
}

将 appsettings.json 的属性改为 Copy Always 复制到生成目录

第二步：修改 Program.cs

找到 Hello/Hello.Winform.Startup/Program.cs 修改为：

csharp

using HmxWinForms.Forms;
using HmxWinForms.Runtime;

namespace Hello.Winform.Startup
{
    internal static class Program
    {
        static WaitDialog? wait;

        [STAThread]
        static void Main(params string[] args)
        {
            var builder = WinFormsApplication.CreateBuilder(args);
            wait = new WaitDialog("正在初始化系统，请稍候...");
            builder.PreInitializeHmxModules<HmxWinformCoreModule>();
            builder.AddHmxWinForms();
            var app = builder.Build();
            app.PostInitHmxModules();

            wait.RaiseBusy("启动登录界面...");
            var dlg = new HmxLoginForm();
            dlg.HandleCreated += (s, e) => wait.Dispose();

            if (DialogResult.OK == dlg.ShowDialog())
            {
                app.Run(new HmxMainLayoutForm());
            }
        }
    }
}

关于 DevExpress 控件的弹窗问题（请自行酌情食用）：

xml

<Target Name="DisableDevExpressDataGenerator" BeforeTargets="CoreCompile">
  <ItemGroup>
    <Analyzer Remove="@(Analyzer)" Condition="'%(Analyzer.Filename)' == 'DevExpress.Generator'" />
  </ItemGroup>
</Target>

启动 WEB 界面

第一步：下载前端代码库

去 https://cnb.cool/zhaxg/rv/hmx_tdweb 下载最新的前端代码库，解压到 Hello_web 文件夹下面，使用 VSCode 打开。

第二步：执行安装依赖

bash

pnpm install

第三步：修改配置文件

bash

# 打包路径 根据项目不同按需配置
VITE_BASE_URL = /
VITE_IS_REQUEST_PROXY = true
VITE_API_URL = http://localhost:3002
VITE_PROXY_TARGET = http://localhost:5185   # 代理转发目标（后端地址）
VITE_API_URL_PREFIX = /api

# 应用命名空间，用于缓存、store 等功能的前缀，确保隔离
VITE_APP_NAMESPACE=hmx-tdweb

# 对 store 进行加密的密钥，在将 store 持久化到 localStorage 时会使用该密钥进行加密
VITE_APP_STORE_SECURE_KEY=5432167890

# 路由命名空间，用于路由的命名，确保隔离
VITE_ROUTER_NAMESPACE=TDWEB

VITE_APP_NAME = "邢台铁特钢贸系统"
VITE_CUSTOMER = "邢台铁特新材料有限公司"
VITE_COPYRIGHT = "北京红谷软件技术有限公司"

第四步：运行 WEB

bash

pnpm dev

快速开始 ​

开发环境 ​

Node.js 环境配置 ​

VSCode 推荐安装扩展 ​

核心语言与框架支持（必装） ​

UI 开发增强（高频推荐） ​

项目效率与协作（团队通用） ​

编辑器美化与辅助（可选） ​

新建项目 ​

第一步：拉取 Admin 代码 ​

第二步：新建【启动】项目 ​

第三步：新建【业务】项目 ​

第四步：新建【前端】项目（WinForm） ​

第五步：添加 Admin 项目到解决方案 ​

验证最终的项目结构 ​

项目引用关系 ​

准备数据库 ​

配置与运行项目 ​

启动后端服务 ​

启动 WinForm 界面 ​

启动 WEB 界面 ​

快速开始

开发环境

Node.js 环境配置

VSCode 推荐安装扩展

核心语言与框架支持（必装）

UI 开发增强（高频推荐）

项目效率与协作（团队通用）

编辑器美化与辅助（可选）

新建项目

第一步：拉取 Admin 代码

第二步：新建【启动】项目

第三步：新建【业务】项目

第四步：新建【前端】项目（WinForm）

第五步：添加 Admin 项目到解决方案

验证最终的项目结构

项目引用关系

准备数据库

配置与运行项目

启动后端服务

启动 WinForm 界面

启动 WEB 界面