TodoList/SCRIPTS_README.md

# 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:5173
   Swagger 文档: http://localhost:5173/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:5173 查看服务
# 访问 http://localhost:5173/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 :5173` 检查端口占用情况

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 应用管理
- 添加参数支持和错误处理
- 彩色输出和友好提示