TodoList/SCRIPTS_README.md

TodoList 服务管理脚本

本目录包含用于管理 TodoList 服务的 PowerShell 脚本。

脚本列表

1. start-service.ps1 - 启动服务

启动 TodoList.Api 服务和 TodoList.Maui 应用。

使用方法

# 启动 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 应用。

使用方法

# 正常关闭
.\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 - 重启服务

停止现有服务并重新启动。

使用方法

# 重启 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 安装包。

使用方法

# 在 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: 首次启动

# 启动 API 服务和 MAUI 应用（默认）
.\start-service.ps1

# 访问 http://localhost:5173 查看服务
# 访问 http://localhost:5173/swagger 查看 API 文档

场景 2: 只启动 API 服务

# 只启动 API 服务，不启动 MAUI 应用
.\start-service.ps1 -StartMaui:$false

场景 3: 开发调试

# 启动 API 和 MAUI 应用（默认行为）
.\start-service.ps1

# 使用 Alt+X 快捷键唤醒 MAUI 应用
# 在 MAUI 应用中测试快捷键功能

场景 4: 代码修改后重启

# 快速重启服务
.\restart-service.ps1

# 重启服务并启动 MAUI 应用
.\restart-service.ps1 -StartMaui

# 或者强制重启（如果进程卡住）
.\restart-service.ps1 -Force

场景 5: 完全关闭

# 关闭所有服务
.\stop-service.ps1

# 或者强制关闭
.\stop-service.ps1 -Force

场景 6: 构建安装包

# 在 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. 手动检查并修复版本号格式

---

快捷命令

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