tsai
/
abp-next-admin2
mirror of https://github.com/colinin/abp-next-admin.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

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

pull/1149/head
feijie 1 year ago
parent
4dea327cb7
commit
72b7d192c9
2 changed files with 168 additions and 172 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 170
      aspnet-core/templates/aio/content/README.md
  2. 170
      aspnet-core/templates/aio/content/README.zh-CN.md

170
aspnet-core/templates/aio/content/README.md
View File

@ -1,135 +1,133 @@
# LINGYUN.Abp.Templates # PackageName.CompanyName.ProjectName
[English](README.md) | [中文](README.zh-CN.md) [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. ### Prerequisites
2. **All-in-One Template**: A single-application template that combines all services into one project.
## 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) ```bash
- Database integration (multiple databases supported) # Navigate to the project root directory
- Unified configuration management cd /path/to/project
- Distributed event bus support
- Background job processing
### Microservice Template Features
- Complete microservice project structure # Restore dependencies
- Service discovery and registration dotnet restore
- Distributed deployment support
### All-in-One Template Features # Build the solution
dotnet build
```
- Simplified deployment ### Step 2: Create Database Schema
- Easier maintenance
- Lower resource requirements
## 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 # Run the migration script
dotnet tool install --global LINGYUN.Abp.Cli ./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 ```bash
# Install Microservice Template # Navigate to the DbMigrator project directory
dotnet new install LINGYUN.Abp.MicroService.Templates cd migrations/PackageName.CompanyName.ProjectName.AIO.DbMigrator
# Install All-in-One Template # Run the DbMigrator project
dotnet new install LINGYUN.Abp.AllInOne.Templates 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 ### Step 4: Launch the Application
# 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
```
#### For All-in-One Project After successfully setting up the database, you can run the host project:
```bash ```bash
# Short name: laa (LINGYUN Abp AllInOne) # Navigate to the host project directory
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 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 ### Step 1: Prepare Test Database
cd /path/to/output/host/YourPackageName.YourCompanyName.YourProjectName.HttpApi.Host
dotnet run --launch-profile "YourPackageName.YourCompanyName.YourProjectName.Development"
```
### 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 The default connection string is:
cd /path/to/output/host/YourPackageName.YourCompanyName.YourProjectName.AIO.Host
dotnet run --launch-profile "YourPackageName.YourCompanyName.YourProjectName.Development"
```
## 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 ### Step 2: Configure Test Environment
git clone <repository-url>
cd <repository-path>/aspnet-core/templates/content
```
2. Modify Version Modify the connection string in `ProjectNameEntityFrameworkCoreTestModule.cs` if needed:
Edit the project files to update versions:
- For Microservice: `../PackageName.CompanyName.ProjectName.csproj`
- For All-in-One: `../PackageName.CompanyName.ProjectName.AIO.csproj`
```xml ```csharp
<Version>8.3.0</Version> // 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 Run the Application.Tests project:
# Windows PowerShell
.\pack.ps1 ```bash
# Navigate to the test project directory
cd tests/PackageName.CompanyName.ProjectName.Application.Tests
# PowerShell Core (Windows/Linux/macOS) # Run the tests
pwsh pack.ps1 dotnet test
``` ```
The script will prompt you to choose which template to package: The test framework will:
1. Microservice Template 1. Create a clean test database environment
2. All-in-One Template 2. Run all unit tests
3. Both Templates 3. Report test results
## Supported Databases ## Note About Naming
- SqlServer 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:
- MySQL
- PostgreSQL
- Oracle
- SQLite
## 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 When creating a new project from this template, you'll specify these values and they'll be substituted throughout the entire solution.
- 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

170
aspnet-core/templates/aio/content/README.zh-CN.md
View File

@ -1,135 +1,133 @@
# LINGYUN.Abp.Templates # PackageName.CompanyName.ProjectName
[English](README.md) | [中文](README.zh-CN.md) [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 1. 检测项目中可用的 DbContext 类
dotnet new install LINGYUN.Abp.AllInOne.Templates 2. 要求您选择用于迁移的 DbContext
``` 3. 提示输入迁移名称
4. 创建迁移
5. 可选地为迁移生成 SQL 脚本
### 安装 labp 命令行工具 ### 第三步：初始化种子数据
运行 DbMigrator 项目来初始化种子数据：
```bash ```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 ```bash
# 简写名称：laa (LINGYUN Abp AllInOne) # 导航到 host 项目目录
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 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. 修改版本号 如需修改 `ProjectNameEntityFrameworkCoreTestModule.cs` 中的连接字符串：
编辑项目文件更新版本号：
- 微服务模板：`../PackageName.CompanyName.ProjectName.csproj`
- 单体应用模板：`../PackageName.CompanyName.ProjectName.AIO.csproj`
```xml ```csharp
<Version>8.3.0</Version> // 您也可以设置环境变量来覆盖默认连接字符串
var connectionString = Environment.GetEnvironmentVariable("TEST_CONNECTION_STRING") ??
DefaultPostgresConnectionString;
``` ```
3. 执行打包脚本 ### 第三步：运行测试
```powershell 运行 Application.Tests 项目：
# Windows PowerShell
.\pack.ps1 ```bash
# 导航到测试项目目录
cd tests/PackageName.CompanyName.ProjectName.Application.Tests
# PowerShell Core (Windows/Linux/macOS) # 运行测试
pwsh pack.ps1 dotnet test
``` ```
脚本会提示您选择要打包的模板： 测试框架将：
1. 微服务模板 1. 创建清洁的测试数据库环境
2. 单体应用模板 2. 运行所有单元测试
3. 两种模板都打包 3. 报告测试结果
## 支持的数据库 ## 关于命名的说明
- SqlServer 这是一个模板项目，所以所有项目名称包含的占位符在使用模板创建新项目时将被替换：
- MySQL
- PostgreSQL
- Oracle
- SQLite
## 注意事项 - `PackageName` 将被替换为您的包名
- `CompanyName` 将被替换为您的公司名
- `ProjectName` 将被替换为您的项目名
- 确保已安装 .NET SDK 8.0 或更高版本 当从此模板创建新项目时，您将指定这些值，它们将在整个解决方案中进行替换。
- 根据需求选择合适的模板：
- 微服务模板：适用于大规模分布式应用
- 单体应用模板：适用于小型应用或简单部署需求
- 打包时注意 NuGet 发布地址和密钥
- 发布前建议进行完整测试

Write Preview
Loading…
Cancel
Save