ShaoHua
388 lines
9.6 KiB
Markdown
388 lines
9.6 KiB
Markdown
# TodoList 服务管理脚本
|
||
|
||
本目录包含用于管理 TodoList 服务的 PowerShell 脚本。
|
||
|
||
## 脚本列表
|
||
|
||
### 1. `start-service.ps1` - 启动服务
|
||
启动 TodoList.Api 服务和 TodoList.Maui 应用。
|
||
|
||
#### 使用方法
|
||
```powershell
|
||
# 启动 API 服务和 MAUI 应用（默认）
|
||
.\start-service.ps1
|
||
|
||
# 只启动 API 服务
|
||
.\start-service.ps1 -StartMaui:$false
|
||
```
|
||
|
||
#### 功能
|
||
- 检查 TodoList.Api 服务是否已在运行
|
||
- 如果未运行，启动 TodoList.Api 服务
|
||
- 默认启动 TodoList.Maui 应用（可通过 `-StartMaui:$false` 禁用）
|
||
- 显示服务访问地址和 Swagger 文档链接
|
||
|
||
#### 输出示例
|
||
```
|
||
====================================
|
||
TodoList 服务启动脚本
|
||
====================================
|
||
|
||
[1/2] 检查 TodoList.Api 服务...
|
||
✓ TodoList.Api 服务未运行
|
||
|
||
[2/2] 启动 TodoList.Api 服务...
|
||
📂 工作目录: D:\Proj\TodoList\src\TodoList.Api
|
||
🚀 启动服务...
|
||
✅ TodoList.Api 服务已启动
|
||
进程 ID: 65992
|
||
访问地址: http://localhost:5057
|
||
Swagger 文档: http://localhost:5057/swagger
|
||
|
||
[3/3] 启动 TodoList.Maui 应用...
|
||
🚀 启动 TodoList.Maui...
|
||
✅ TodoList.Maui 已启动
|
||
|
||
====================================
|
||
启动完成
|
||
====================================
|
||
|
||
💡 提示:
|
||
- 按 Ctrl+C 可以停止服务
|
||
- 运行 stop-service.ps1 可以关闭服务
|
||
- 运行 restart-service.ps1 可以重启服务
|
||
```
|
||
|
||
---
|
||
|
||
### 2. `stop-service.ps1` - 关闭服务
|
||
停止所有正在运行的 TodoList.Api 服务和 TodoList.Maui 应用。
|
||
|
||
#### 使用方法
|
||
```powershell
|
||
# 正常关闭
|
||
.\stop-service.ps1
|
||
|
||
# 强制关闭
|
||
.\stop-service.ps1 -Force
|
||
```
|
||
|
||
#### 功能
|
||
- 查找并停止所有 TodoList.Api 进程
|
||
- 查找并停止所有 TodoList.Maui 进程
|
||
- 显示停止的进程数量和状态
|
||
|
||
#### 输出示例
|
||
```
|
||
====================================
|
||
TodoList 服务关闭脚本
|
||
====================================
|
||
|
||
[1/2] 查找 TodoList.Api 服务...
|
||
🔍 找到 1 个 TodoList.Api 进程
|
||
正在停止进程 ID: 65992...
|
||
✅ 进程 65992 已停止
|
||
|
||
[2/2] 查找 TodoList.Maui 应用...
|
||
✓ TodoList.Maui 应用未运行
|
||
|
||
====================================
|
||
关闭完成
|
||
已停止 1 个进程
|
||
====================================
|
||
|
||
💡 提示:
|
||
- 运行 start-service.ps1 可以启动服务
|
||
- 运行 restart-service.ps1 可以重启服务
|
||
```
|
||
|
||
---
|
||
|
||
### 3. `restart-service.ps1` - 重启服务
|
||
停止现有服务并重新启动。
|
||
|
||
#### 使用方法
|
||
```powershell
|
||
# 重启 API 服务
|
||
.\restart-service.ps1
|
||
|
||
# 重启 API 和 MAUI 应用
|
||
.\restart-service.ps1 -StartMaui
|
||
|
||
# 强制重启
|
||
.\restart-service.ps1 -Force
|
||
```
|
||
|
||
#### 功能
|
||
- 调用 stop-service.ps1 停止现有服务
|
||
- 等待进程完全关闭（最多 10 秒）
|
||
- 调用 start-service.ps1 启动服务
|
||
- 显示重启进度和状态
|
||
|
||
#### 输出示例
|
||
```
|
||
====================================
|
||
TodoList 服务重启脚本
|
||
====================================
|
||
|
||
[1/3] 停止现有服务...
|
||
✅ 服务已停止
|
||
|
||
[2/3] 等待进程完全关闭...
|
||
✅ 所有进程已关闭
|
||
|
||
[3/3] 启动服务...
|
||
✅ 服务已启动
|
||
|
||
====================================
|
||
重启完成
|
||
====================================
|
||
|
||
💡 提示:
|
||
- 按 Ctrl+C 可以停止服务
|
||
- 运行 stop-service.ps1 可以关闭服务
|
||
- 运行 restart-service.ps1 可以重启服务
|
||
```
|
||
|
||
---
|
||
|
||
### 4. `BuildSetup.ps1` - 构建安装包
|
||
构建 TodoList.Maui 项目的 Release 版本并创建 Inno Setup 安装包。
|
||
|
||
#### 使用方法
|
||
```powershell
|
||
# 在 TodoList 目录下运行
|
||
.\TodoList\BuildSetup.ps1
|
||
```
|
||
|
||
#### 功能
|
||
- 自动读取项目版本号
|
||
- 自动递增补丁版本号（例如 1.0.0 → 1.0.1）
|
||
- 更新 .csproj 文件中的版本号
|
||
- 更新 setup.iss 文件中的版本号
|
||
- 构建 Release 版本（win-x64）
|
||
- 使用 Inno Setup 编译器创建安装包
|
||
|
||
#### 输出示例
|
||
```
|
||
Setup package created successfully!
|
||
```
|
||
|
||
#### 依赖项
|
||
- .NET SDK
|
||
- Inno Setup 6（默认路径：`C:\Program Files (x86)\Inno Setup 6\ISCC.exe`）
|
||
|
||
---
|
||
|
||
## 参数说明
|
||
|
||
### `start-service.ps1`
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|----------|------|
|
||
| `-StartMaui` | Switch | `$true` | 是否启动 TodoList.Maui 应用（默认启用） |
|
||
| `-ServicePath` | String | `"src\TodoList.Api"` | API 服务相对路径 |
|
||
| `-MauiPath` | String | `"src\TodoList.Maui"` | MAUI 应用相对路径 |
|
||
|
||
### `stop-service.ps1`
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|----------|------|
|
||
| `-Force` | Switch | `$false` | 是否强制关闭进程 |
|
||
|
||
### `restart-service.ps1`
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|----------|------|
|
||
| `-StartMaui` | Switch | `$false` | 是否同时启动 TodoList.Maui 应用 |
|
||
| `-Force` | Switch | `$false` | 是否强制关闭进程 |
|
||
|
||
### `BuildSetup.ps1`
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|----------|------|
|
||
| 无 | - | - | 脚本自动检测项目文件并处理 |
|
||
|
||
---
|
||
|
||
## 使用场景
|
||
|
||
### 场景 1: 首次启动
|
||
```powershell
|
||
# 启动 API 服务和 MAUI 应用（默认）
|
||
.\start-service.ps1
|
||
|
||
# 访问 http://localhost:5057 查看服务
|
||
# 访问 http://localhost:5057/swagger 查看 API 文档
|
||
```
|
||
|
||
### 场景 2: 只启动 API 服务
|
||
```powershell
|
||
# 只启动 API 服务，不启动 MAUI 应用
|
||
.\start-service.ps1 -StartMaui:$false
|
||
```
|
||
|
||
### 场景 3: 开发调试
|
||
```powershell
|
||
# 启动 API 和 MAUI 应用（默认行为）
|
||
.\start-service.ps1
|
||
|
||
# 使用 Alt+X 快捷键唤醒 MAUI 应用
|
||
# 在 MAUI 应用中测试快捷键功能
|
||
```
|
||
|
||
### 场景 4: 代码修改后重启
|
||
```powershell
|
||
# 快速重启服务
|
||
.\restart-service.ps1
|
||
|
||
# 重启服务并启动 MAUI 应用
|
||
.\restart-service.ps1 -StartMaui
|
||
|
||
# 或者强制重启（如果进程卡住）
|
||
.\restart-service.ps1 -Force
|
||
```
|
||
|
||
### 场景 5: 完全关闭
|
||
```powershell
|
||
# 关闭所有服务
|
||
.\stop-service.ps1
|
||
|
||
# 或者强制关闭
|
||
.\stop-service.ps1 -Force
|
||
```
|
||
|
||
### 场景 6: 构建安装包
|
||
```powershell
|
||
# 在 TodoList 目录下构建安装包
|
||
.\TodoList\BuildSetup.ps1
|
||
|
||
# 脚本会自动：
|
||
# 1. 递增版本号
|
||
# 2. 构建 Release 版本
|
||
# 3. 创建 Inno Setup 安装包
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **PowerShell 执行策略**
|
||
- 如果遇到执行策略错误，运行：`Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
|
||
- 或者临时绕过：`powershell -ExecutionPolicy Bypass -File .\start-service.ps1`
|
||
|
||
2. **进程检测**
|
||
- 脚本通过进程名称和窗口标题检测 TodoList.Api 服务
|
||
- 脚本通过进程名称检测 TodoList.Maui 应用
|
||
|
||
3. **端口占用**
|
||
- 如果端口 5057 被占用，启动会失败
|
||
- 使用 `netstat -ano | findstr :5057` 检查端口占用情况
|
||
|
||
4. **MAUI 应用构建**
|
||
- 如果 MAUI 应用不存在，需要先构建：`dotnet build src\TodoList.Maui\TodoList.Maui.csproj`
|
||
- 默认路径：`src\TodoList.Maui\bin\Debug\net10.0-windows10.0.19041.0\win-x64\TodoList.Maui.exe`
|
||
|
||
5. **快捷键功能**
|
||
- MAUI 应用启动后，默认快捷键为 `Alt + X`
|
||
- 可以在应用设置中自定义快捷键
|
||
|
||
---
|
||
|
||
## 故障排除
|
||
|
||
### 问题 1: 无法启动服务
|
||
**症状**: 运行 `start-service.ps1` 后服务未启动
|
||
|
||
**解决方案**:
|
||
1. 检查 .NET SDK 是否安装：`dotnet --version`
|
||
2. 检查项目路径是否正确
|
||
3. 查看错误信息：`dotnet run src\TodoList.Api\TodoList.Api.csproj`
|
||
|
||
### 问题 2: 无法停止服务
|
||
**症状**: 运行 `stop-service.ps1` 后进程仍在运行
|
||
|
||
**解决方案**:
|
||
1. 使用强制关闭：`.\stop-service.ps1 -Force`
|
||
2. 手动结束进程：`taskkill /F /IM dotnet.exe`
|
||
3. 检查是否有其他 dotnet 进程占用
|
||
|
||
### 问题 3: MAUI 应用无法启动
|
||
**症状**: 运行 `start-service.ps1` 后 MAUI 应用未启动
|
||
|
||
**解决方案**:
|
||
1. 先构建 MAUI 项目：`dotnet build src\TodoList.Maui\TodoList.Maui.csproj`
|
||
2. 检查可执行文件是否存在
|
||
3. 查看构建错误信息
|
||
|
||
### 问题 4: BuildSetup.ps1 无法构建安装包
|
||
**症状**: 运行 `.\TodoList\BuildSetup.ps1` 后构建失败
|
||
|
||
**解决方案**:
|
||
1. 检查 Inno Setup 是否已安装：`Test-Path "${env:ProgramFiles(x86)}\Inno Setup 6\ISCC.exe"`
|
||
2. 如果未安装，请从 https://jrsoftware.org/isdl.php 下载安装
|
||
3. 检查 .NET SDK 是否安装：`dotnet --version`
|
||
4. 检查项目文件是否存在：`Test-Path .\TodoList\TodoList.csproj`
|
||
5. 检查 setup.iss 文件是否存在：`Test-Path .\TodoList\setup.iss`
|
||
|
||
### 问题 5: 版本号未正确递增
|
||
**症状**: 运行 BuildSetup.ps1 后版本号未变化
|
||
|
||
**解决方案**:
|
||
1. 检查 .csproj 文件中是否有 `<Version>` 标签
|
||
2. 确保版本号格式为 `X.Y.Z`（三个数字用点分隔）
|
||
3. 手动检查并修复版本号格式
|
||
|
||
---
|
||
|
||
## 快捷命令
|
||
|
||
```powershell
|
||
# 启动服务（API + MAUI，默认）
|
||
.\start-service.ps1
|
||
|
||
# 只启动 API 服务
|
||
.\start-service.ps1 -StartMaui:$false
|
||
|
||
# 关闭服务
|
||
.\stop-service.ps1
|
||
|
||
# 重启服务
|
||
.\restart-service.ps1
|
||
|
||
# 重启服务并启动 MAUI 应用
|
||
.\restart-service.ps1 -StartMaui
|
||
|
||
# 强制关闭
|
||
.\stop-service.ps1 -Force
|
||
|
||
# 强制重启
|
||
.\restart-service.ps1 -Force
|
||
|
||
# 构建安装包
|
||
.\TodoList\BuildSetup.ps1
|
||
```
|
||
|
||
---
|
||
|
||
## 技术细节
|
||
|
||
- **脚本语言**: PowerShell 5.1+
|
||
- **目标平台**: Windows
|
||
- **依赖**: .NET SDK, dotnet CLI
|
||
- **错误处理**: 支持错误捕获和友好提示
|
||
- **日志输出**: 彩色输出，易于阅读
|
||
|
||
---
|
||
|
||
## 更新日志
|
||
|
||
### v1.1.0 (2026-03-18)
|
||
- 新增 `BuildSetup.ps1` 脚本，支持自动构建安装包
|
||
- 更新 `start-service.ps1`，默认启动 MAUI 应用（`-StartMaui` 默认值为 `$true`）
|
||
- 优化所有脚本的输出格式，添加提示信息
|
||
- 更新文档，修正参数默认值说明
|
||
- 添加 BuildSetup.ps1 相关故障排除指南
|
||
|
||
### v1.0.0 (2026-03-13)
|
||
- 初始版本
|
||
- 实现启动、关闭、重启服务功能
|
||
- 支持 TodoList.Api 和 TodoList.Maui 应用管理
|
||
- 添加参数支持和错误处理
|
||
- 彩色输出和友好提示 |