docs(README.md): 更新 README，提供更清晰的快速启动指南和单元测试说明

11 months ago · 72b7d192c9
2 changed files with 168 additions and 172 deletions
--- a/aspnet-core/templates/aio/content/README.md
+++ b/aspnet-core/templates/aio/content/README.md
@ -1,135 +1,133 @@
-# LINGYUN.Abp.Templates
+# PackageName.CompanyName.ProjectName

 [English](README.md) | [中文](README.zh-CN.md)

-## Introduction
+## Quick Start Guide

-LINGYUN.Abp.Templates provides two types of project templates based on ABP Framework:
+This guide will help you quickly set up and run the project. Follow these steps to get started.

-1. **Microservice Template**: A complete microservice architecture template with distributed services.
-2. **All-in-One Template**: A single-application template that combines all services into one project.
+### Prerequisites

-## Features
+- .NET SDK 9.0 or higher
+- A supported database (SQL Server, MySQL, PostgreSQL, Oracle, or SQLite)
+- PowerShell 7.0+ (recommended for running migration scripts)

-### Common Features
+### Step 1: Restore and Build the Project

- Integrated authentication (IdentityServer4/OpenIddict)
- Database integration (multiple databases supported)
- Unified configuration management
- Distributed event bus support
- Background job processing
-
-### Microservice Template Features
+```bash
+# Navigate to the project root directory
+cd /path/to/project

- Complete microservice project structure
- Service discovery and registration
- Distributed deployment support
+# Restore dependencies
+dotnet restore

-### All-in-One Template Features
+# Build the solution
+dotnet build
+```

- Simplified deployment
- Easier maintenance
- Lower resource requirements
+### Step 2: Create Database Schema

-## How to Use
+Use the Migrate.ps1 script to create the database tables structure:

-### Install labp CLI Tool
+```powershell
+# Navigate to the migrations directory
+cd migrations

-```bash
-dotnet tool install --global LINGYUN.Abp.Cli
+# Run the migration script
+./Migrate.ps1
 ```

-### Install Templates
+The script will:
+
+1. Detect available DbContext classes in the project
+2. Ask you to select which DbContext to use for migration
+3. Prompt for a migration name
+4. Create the migration
+5. Optionally generate SQL scripts for the migration
+
+### Step 3: Initialize Seed Data
+
+Run the DbMigrator project to initialize seed data:

 ```bash
-# Install Microservice Template
-dotnet new install LINGYUN.Abp.MicroService.Templates
+# Navigate to the DbMigrator project directory
+cd migrations/PackageName.CompanyName.ProjectName.AIO.DbMigrator

-# Install All-in-One Template
-dotnet new install LINGYUN.Abp.AllInOne.Templates
+# Run the DbMigrator project
+dotnet run
 ```

-### Create New Project
+The DbMigrator will:

-#### For Microservice Project
+1. Apply all database migrations
+2. Seed initial data (users, roles, etc.)
+3. Set up tenant configurations if applicable

-```bash
-# Short name: lam (LINGYUN Abp Microservice)
-labp create YourCompanyName.YourProjectName -pk YourPackageName -t lam -o /path/to/output --dbms MySql --cs "Server=127.0.0.1;Database=Platform-V70;User Id=root;Password=123456;SslMode=None" --no-random-port
-```
+### Step 4: Launch the Application

-#### For All-in-One Project
+After successfully setting up the database, you can run the host project:

 ```bash
-# Short name: laa (LINGYUN Abp AllInOne)
-labp create YourCompanyName.YourProjectName -pk YourPackageName -t laa -o /path/to/output --dbms MySql --cs "Server=127.0.0.1;Database=Platform-V70;User Id=root;Password=123456;SslMode=None" --no-random-port
+# Navigate to the host project directory
+cd host/PackageName.CompanyName.ProjectName.AIO.Host
+
+# Run the host project
+dotnet run --launch-profile "PackageName.CompanyName.ProjectName.Development"
 ```

-## How to Run
+The application will start and be accessible at the configured URL (typically [https://localhost:44300](https://localhost:44300)).

-After creating your project, you can run it using the following command:
+## Database-based Unit Testing

-### For Microservice Project
+To run database-based unit tests, follow these steps:

-```bash
-cd /path/to/output/host/YourPackageName.YourCompanyName.YourProjectName.HttpApi.Host
-dotnet run --launch-profile "YourPackageName.YourCompanyName.YourProjectName.Development"
-```
+### Step 1: Prepare Test Database

-### For All-in-One Project
+Before running tests, make sure the test database exists. The test database connection string is defined in the `ProjectNameEntityFrameworkCoreTestModule.cs` file.

-```bash
-cd /path/to/output/host/YourPackageName.YourCompanyName.YourProjectName.AIO.Host
-dotnet run --launch-profile "YourPackageName.YourCompanyName.YourProjectName.Development"
-```
+The default connection string is:

-## How to Package and Publish
+```csharp
+private const string DefaultPostgresConnectionString =
+    "Host=127.0.0.1;Port=5432;Database=test_db;User Id=postgres;Password=postgres;";
+```

-1. Clone the Project
+You can either create this database manually or modify the connection string to use an existing database.

-```bash
-git clone <repository-url>
-cd <repository-path>/aspnet-core/templates/content
-```
+### Step 2: Configure Test Environment

-2. Modify Version
-   Edit the project files to update versions:
-   - For Microservice: `../PackageName.CompanyName.ProjectName.csproj`
-   - For All-in-One: `../PackageName.CompanyName.ProjectName.AIO.csproj`
+Modify the connection string in `ProjectNameEntityFrameworkCoreTestModule.cs` if needed:

-```xml
-<Version>8.3.0</Version>
+```csharp
+// You can also set an environment variable to override the default connection string
+var connectionString = Environment.GetEnvironmentVariable("TEST_CONNECTION_STRING") ??
+                       DefaultPostgresConnectionString;
 ```

-3. Execute Packaging Script
+### Step 3: Run Tests

-```powershell
-# Windows PowerShell
-.\pack.ps1
+Run the Application.Tests project:
+
+```bash
+# Navigate to the test project directory
+cd tests/PackageName.CompanyName.ProjectName.Application.Tests

-# PowerShell Core (Windows/Linux/macOS)
-pwsh pack.ps1
+# Run the tests
+dotnet test
 ```

-The script will prompt you to choose which template to package:
+The test framework will:

-1. Microservice Template
-2. All-in-One Template
-3. Both Templates
+1. Create a clean test database environment
+2. Run all unit tests
+3. Report test results

-## Supported Databases
+## Note About Naming

- SqlServer
- MySQL
- PostgreSQL
- Oracle
- SQLite
+This is a template project, so all project names contain placeholders that will be replaced when the template is used to create a new project:

-## Notes
+- `PackageName` will be replaced with your package name
+- `CompanyName` will be replaced with your company name
+- `ProjectName` will be replaced with your project name

- Ensure .NET SDK 8.0 or higher is installed
- Choose the appropriate template based on your needs:
-  - Microservice Template: For large-scale distributed applications
-  - All-in-One Template: For smaller applications or simpler deployment requirements
- Pay attention to NuGet publish address and key when packaging
- Complete testing is recommended before publishing
+When creating a new project from this template, you'll specify these values and they'll be substituted throughout the entire solution.
--- a/aspnet-core/templates/aio/content/README.zh-CN.md
+++ b/aspnet-core/templates/aio/content/README.zh-CN.md
@ -1,135 +1,133 @@
-# LINGYUN.Abp.Templates
+# PackageName.CompanyName.ProjectName

 [English](README.md) | [中文](README.zh-CN.md)

-## 简介
+## 快速启动指南

-LINGYUN.Abp.Templates 基于 ABP Framework 提供两种项目模板：
+本指南将帮助您快速设置和运行项目。请按照以下步骤开始。

-1. **微服务模板**：完整的分布式微服务架构模板
-2. **单体应用模板**：将所有服务集成到一个项目中的单体应用模板
+### 前提条件

-## 特性
+- .NET SDK 9.0 或更高版本
+- 支持的数据库（SQL Server、MySQL、PostgreSQL、Oracle 或 SQLite）
+- PowerShell 7.0+（推荐用于运行迁移脚本）

-### 共同特性
+### 第一步：还原和构建项目

- 集成身份认证（支持 IdentityServer4/OpenIddict）
- 数据库集成（支持多种数据库）
- 统一配置管理
- 分布式事件总线支持
- 后台作业处理
+```bash
+# 导航到项目根目录
+cd /path/to/project

-### 微服务模板特性
+# 还原依赖项
+dotnet restore

- 完整的微服务项目结构
- 服务发现与注册
- 支持分布式部署
+# 构建解决方案
+dotnet build
+```

-### 单体应用模板特性
+### 第二步：创建数据库结构

- 简化的部署流程
- 更容易的维护
- 更低的资源需求
+使用 Migrate.ps1 脚本创建数据库表结构：

-## 使用方法
+```powershell
+# 导航到 migrations 目录
+cd migrations

-### 安装模板
+# 运行迁移脚本
+./Migrate.ps1
+```

-```bash
-# 安装微服务模板:lam
-dotnet new install LINGYUN.Abp.MicroService.Templates
+该脚本将：

-# 安装单体应用模板:laa
-dotnet new install LINGYUN.Abp.AllInOne.Templates
-```
+1. 检测项目中可用的 DbContext 类
+2. 要求您选择用于迁移的 DbContext
+3. 提示输入迁移名称
+4. 创建迁移
+5. 可选地为迁移生成 SQL 脚本

-### 安装 labp 命令行工具
+### 第三步：初始化种子数据
+
+运行 DbMigrator 项目来初始化种子数据：

 ```bash
-  dotnet tool install --global LINGYUN.Abp.Cli
+# 导航到 DbMigrator 项目目录
+cd migrations/PackageName.CompanyName.ProjectName.AIO.DbMigrator
+
+# 运行 DbMigrator 项目
+dotnet run
 ```

-### 创建新项目
+DbMigrator 将：

-#### 创建微服务项目
+1. 应用所有数据库迁移
+2. 初始化种子数据（用户、角色等）
+3. 如适用，设置租户配置

-```bash
-# 简写名称：lam (LINGYUN Abp Microservice)
-labp create YourCompanyName.YourProjectName -pk YourPackageName -t lam -o /path/to/output --dbms MySql --cs "Server=127.0.0.1;Database=Platform-V70;User Id=root;Password=123456;SslMode=None" --no-random-port
-```
+### 第四步：启动应用程序

-#### 创建单体应用项目
+成功设置数据库后，您可以运行 host 项目：

 ```bash
-# 简写名称：laa (LINGYUN Abp AllInOne)
-labp create YourCompanyName.YourProjectName -pk YourPackageName -t laa -o /path/to/output --dbms MySql --cs "Server=127.0.0.1;Database=Platform-V70;User Id=root;Password=123456;SslMode=None" --no-random-port
+# 导航到 host 项目目录
+cd host/PackageName.CompanyName.ProjectName.AIO.Host
+
+# 运行 host 项目
+dotnet run --launch-profile "PackageName.CompanyName.ProjectName.Development"
 ```

-## 运行项目
+应用程序将启动并可通过配置的 URL 访问（通常是 [https://localhost:44300](https://localhost:44300)）。

-创建项目后，可以使用以下命令运行：
+## 基于数据库的单元测试

-### 运行微服务项目
+要运行基于数据库的单元测试，请按照以下步骤操作：

-```bash
-cd /path/to/output/host/YourPackageName.YourCompanyName.YourProjectName.HttpApi.Host
-dotnet run --launch-profile "YourPackageName.YourCompanyName.YourProjectName.Development"
-```
+### 第一步：准备测试数据库

-### 运行单体应用项目
+在运行测试之前，确保测试数据库存在。测试数据库连接字符串在 `ProjectNameEntityFrameworkCoreTestModule.cs` 文件中定义。

-```bash
-cd /path/to/output/host/YourPackageName.YourCompanyName.YourProjectName.AIO.Host
-dotnet run --launch-profile "YourPackageName.YourCompanyName.YourProjectName.Development"
-```
+默认连接字符串是：

-## 打包与发布
+```csharp
+private const string DefaultPostgresConnectionString =
+    "Host=127.0.0.1;Port=5432;Database=test_db;User Id=postgres;Password=postgres;";
+```

-1. 克隆项目
+您可以手动创建此数据库或修改连接字符串以使用现有数据库。

-```bash
-git clone <repository-url>
-cd <repository-path>/aspnet-core/templates/content
-```
+### 第二步：配置测试环境

-2. 修改版本号
-   编辑项目文件更新版本号：
-   - 微服务模板：`../PackageName.CompanyName.ProjectName.csproj`
-   - 单体应用模板：`../PackageName.CompanyName.ProjectName.AIO.csproj`
+如需修改 `ProjectNameEntityFrameworkCoreTestModule.cs` 中的连接字符串：

-```xml
-<Version>8.3.0</Version>
+```csharp
+// 您也可以设置环境变量来覆盖默认连接字符串
+var connectionString = Environment.GetEnvironmentVariable("TEST_CONNECTION_STRING") ??
+                       DefaultPostgresConnectionString;
 ```

-3. 执行打包脚本
+### 第三步：运行测试

-```powershell
-# Windows PowerShell
-.\pack.ps1
+运行 Application.Tests 项目：
+
+```bash
+# 导航到测试项目目录
+cd tests/PackageName.CompanyName.ProjectName.Application.Tests

-# PowerShell Core (Windows/Linux/macOS)
-pwsh pack.ps1
+# 运行测试
+dotnet test
 ```

-脚本会提示您选择要打包的模板：
+测试框架将：

-1. 微服务模板
-2. 单体应用模板
-3. 两种模板都打包
+1. 创建清洁的测试数据库环境
+2. 运行所有单元测试
+3. 报告测试结果

-## 支持的数据库
+## 关于命名的说明

- SqlServer
- MySQL
- PostgreSQL
- Oracle
- SQLite
+这是一个模板项目，所以所有项目名称包含的占位符在使用模板创建新项目时将被替换：

-## 注意事项
+- `PackageName` 将被替换为您的包名
+- `CompanyName` 将被替换为您的公司名
+- `ProjectName` 将被替换为您的项目名

- 确保已安装 .NET SDK 8.0 或更高版本
- 根据需求选择合适的模板：
-  - 微服务模板：适用于大规模分布式应用
-  - 单体应用模板：适用于小型应用或简单部署需求
- 打包时注意 NuGet 发布地址和密钥
- 发布前建议进行完整测试
+当从此模板创建新项目时，您将指定这些值，它们将在整个解决方案中进行替换。