A:整体并简化代码
This commit is contained in:
jimmy committed
1 parent
2c83fc72e4
commit
2563288afe
26 files changed
+889
-566
No files matched your search
@@ -0,0 +1,486 @@
|
||||
# Sharp-Basic 配置指南
|
||||
|
||||
本文档说明 Sharp-Basic 框架的配置约定和最佳实践。
|
||||
|
||||
## 目录
|
||||
|
||||
- [配置文件模板](#配置文件模板)
|
||||
- [约定配置节名称](#约定配置节名称)
|
||||
- [环境变量覆盖](#环境变量覆盖)
|
||||
- [模块配置详解](#模块配置详解)
|
||||
- [最佳实践](#最佳实践)
|
||||
|
||||
---
|
||||
|
||||
## 配置文件模板
|
||||
|
||||
Sharp-Basic 提供了完整的配置文件模板：**`appsettings.template.json`**
|
||||
|
||||
### 使用方法
|
||||
|
||||
1. **复制模板文件**
|
||||
```bash
|
||||
cp appsettings.template.json appsettings.json
|
||||
```
|
||||
|
||||
2. **根据项目需要选择性保留配置**
|
||||
- 只使用数据库？保留 `Database` 节
|
||||
- 需要PLC通信？保留 `Plc:Siemens` 节
|
||||
- 不需要的配置可以删除
|
||||
|
||||
3. **修改配置值**
|
||||
```json
|
||||
{
|
||||
"Database": {
|
||||
"Provider": "SqlServer",
|
||||
"ConnectionString": "你的数据库连接字符串"
|
||||
},
|
||||
"Plc": {
|
||||
"Siemens": {
|
||||
"IpAddress": "你的PLC IP地址"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 约定配置节名称
|
||||
|
||||
Sharp-Basic 遵循 **"约定优于配置"** 原则，每个模块都有固定的配置节名称：
|
||||
|
||||
### 核心模块
|
||||
|
||||
| 模块 | 配置节名称 | 说明 | 必填字段 |
|
||||
|------|------------|------|----------|
|
||||
| **System** | `System` | 系统级HTTP配置 | `HTTPIp`, `HttpPort` |
|
||||
| **Database** | `Database` | 数据库连接配置 | `Provider`, `ConnectionString` |
|
||||
| **Logging** | `Logging` | 日志级别配置 | `LogLevel` |
|
||||
| **SharpLog** | `SharpLog` | Sharp日志扩展 | 无（全部可选） |
|
||||
|
||||
### 网络模块
|
||||
|
||||
| 模块 | 配置节名称 | 说明 | 必填字段 |
|
||||
|------|------------|------|----------|
|
||||
| **NetClient** | `NetClient` | HTTP客户端配置 | 无（可使用System默认值） |
|
||||
| **NetServer** | `NetServer` | HTTP服务端配置 | 无（可使用System默认值） |
|
||||
|
||||
### IoT模块
|
||||
|
||||
| 模块 | 配置节名称 | 说明 | 必填字段 |
|
||||
|------|------------|------|----------|
|
||||
| **Plc.Siemens** | `Plc:Siemens` | 西门子PLC配置 | `IpAddress`, `CpuType` |
|
||||
| **SerialPort** | `SerialPort` | 串口通信配置 | `PortName`, `BaudRate` |
|
||||
|
||||
### 工具模块
|
||||
|
||||
| 模块 | 配置节名称 | 说明 | 必填字段 |
|
||||
|------|------------|------|----------|
|
||||
| **Process** | `Process` | 进程执行配置 | 无（全部可选） |
|
||||
| **Python** | `Python` | Python脚本配置 | 无（全部可选） |
|
||||
| **Cache** | `Cache` | 缓存配置 | 无（全部可选） |
|
||||
| **EventBus** | `EventBus` | 事件总线配置 | 无（全部可选） |
|
||||
|
||||
---
|
||||
|
||||
## 环境变量覆盖
|
||||
|
||||
所有配置都可以通过环境变量覆盖，格式：`SHARP__{节名}__{键名}`
|
||||
|
||||
### 覆盖规则
|
||||
|
||||
- 使用双下划线 `__` 分隔层级
|
||||
- 所有字母必须大写（Windows不区分大小写，Linux区分）
|
||||
- 冒号 `:` 用双下划线 `__` 替代
|
||||
|
||||
### 示例
|
||||
|
||||
#### 覆盖数据库配置
|
||||
```bash
|
||||
# Windows (PowerShell)
|
||||
$env:SHARP__Database__Provider="Sqlite"
|
||||
$env:SHARP__Database__ConnectionString="Data Source=test.db"
|
||||
|
||||
# Linux/macOS
|
||||
export SHARP__Database__Provider=Sqlite
|
||||
export SHARP__Database__ConnectionString="Data Source=test.db"
|
||||
```
|
||||
|
||||
#### 覆盖PLC配置
|
||||
```bash
|
||||
# Windows (PowerShell)
|
||||
$env:SHARP__Plc__Siemens__IpAddress="192.168.1.200"
|
||||
$env:SHARP__Plc__Siemens__CpuType="S71500"
|
||||
|
||||
# Linux/macOS
|
||||
export SHARP__Plc__Siemens__IpAddress=192.168.1.200
|
||||
export SHARP__Plc__Siemens__CpuType=S71500
|
||||
```
|
||||
|
||||
#### 覆盖System配置
|
||||
```bash
|
||||
# Windows (PowerShell)
|
||||
$env:SHARP__System__HttpPort="9090"
|
||||
|
||||
# Linux/macOS
|
||||
export SHARP__System__HttpPort=9090
|
||||
```
|
||||
|
||||
### 优先级
|
||||
|
||||
配置优先级从高到低：
|
||||
1. **环境变量** - 最高优先级
|
||||
2. **appsettings.{Environment}.json** - 环境特定配置
|
||||
3. **appsettings.json** - 默认配置
|
||||
|
||||
---
|
||||
|
||||
## 模块配置详解
|
||||
|
||||
### 1. 数据库配置 (Database)
|
||||
|
||||
#### 最简配置
|
||||
```json
|
||||
{
|
||||
"Database": {
|
||||
"Provider": "Sqlite",
|
||||
"ConnectionString": "Data Source=app.db"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 代码中使用
|
||||
```csharp
|
||||
var config = ConfigBuilder.CreateDefault().Configuration;
|
||||
services.AddSharpDatabase<AppDbContext>(config); // 自动读取 Database 节
|
||||
```
|
||||
|
||||
#### 支持的数据库提供程序
|
||||
- `SqlServer` - Microsoft SQL Server
|
||||
- `Sqlite` - SQLite
|
||||
- `PostgreSQL` - PostgreSQL
|
||||
- `MySql` - MySQL/MariaDB
|
||||
- `InMemory` - 内存数据库（仅用于测试）
|
||||
|
||||
---
|
||||
|
||||
### 2. PLC配置 (Plc:Siemens)
|
||||
|
||||
#### 最简配置
|
||||
```json
|
||||
{
|
||||
"Plc": {
|
||||
"Siemens": {
|
||||
"IpAddress": "192.168.1.100",
|
||||
"CpuType": "S71200"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 代码中使用
|
||||
```csharp
|
||||
var config = ConfigBuilder.CreateDefault().Configuration;
|
||||
services.AddSiemensPlc(config.GetSection("Plc:Siemens"));
|
||||
```
|
||||
|
||||
#### 支持的CPU类型
|
||||
- `S71200` - S7-1200 系列
|
||||
- `S71500` - S7-1500 系列
|
||||
- `S7300` - S7-300 系列
|
||||
- `S7400` - S7-400 系列
|
||||
- `S7200` - S7-200 系列
|
||||
- `S7200Smart` - S7-200 Smart 系列
|
||||
|
||||
---
|
||||
|
||||
### 3. 日志配置 (Logging & SharpLog)
|
||||
|
||||
#### 最简配置
|
||||
```json
|
||||
{
|
||||
"Logging": {
|
||||
"LogLevel": {
|
||||
"Default": "Information"
|
||||
}
|
||||
},
|
||||
"SharpLog": {
|
||||
"LogFilePath": "logs/app-.log",
|
||||
"RollingInterval": "Day"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 代码中使用
|
||||
```csharp
|
||||
services.AddLogging(b => b.AddSharpLog()); // 自动读取 SharpLog 节
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. HTTP配置 (System, NetClient, NetServer)
|
||||
|
||||
#### System配置（共享默认值）
|
||||
```json
|
||||
{
|
||||
"System": {
|
||||
"HTTPIp": "127.0.0.1",
|
||||
"HttpPort": 8080,
|
||||
"TimeoutSeconds": 30,
|
||||
"Scheme": "http"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### NetClient配置（可选，留空则使用System默认值）
|
||||
```json
|
||||
{
|
||||
"NetClient": {
|
||||
"BaseAddress": "http://api.example.com",
|
||||
"Timeout": "00:00:30",
|
||||
"EnableLogging": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### NetServer配置（可选，留空则使用System默认值）
|
||||
```json
|
||||
{
|
||||
"NetServer": {
|
||||
"ListenUrls": [
|
||||
"http://localhost:8080/"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 按需配置
|
||||
|
||||
**只保留需要的配置节**，不要保留所有模板内容：
|
||||
|
||||
```json
|
||||
{
|
||||
// ❌ 不好：保留了不使用的配置
|
||||
"Database": { ... },
|
||||
"Plc": { ... },
|
||||
"SerialPort": { ... },
|
||||
"Python": { ... }
|
||||
}
|
||||
|
||||
{
|
||||
// ✅ 好：只保留需要的配置
|
||||
"Database": { ... },
|
||||
"Logging": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 使用环境特定配置
|
||||
|
||||
为不同环境创建不同的配置文件：
|
||||
|
||||
```
|
||||
appsettings.json # 默认配置
|
||||
appsettings.Development.json # 开发环境
|
||||
appsettings.Production.json # 生产环境
|
||||
appsettings.Testing.json # 测试环境
|
||||
```
|
||||
|
||||
### 3. 敏感信息使用环境变量
|
||||
|
||||
**不要在配置文件中存储敏感信息**（密码、密钥等）：
|
||||
|
||||
```bash
|
||||
# ✅ 好：使用环境变量
|
||||
export SHARP__Database__ConnectionString="Server=prod;User=sa;Password=SecretPass123"
|
||||
export SHARP__Plc__Siemens__IpAddress="192.168.1.100"
|
||||
```
|
||||
|
||||
```json
|
||||
// ❌ 不好：敏感信息写在配置文件
|
||||
{
|
||||
"Database": {
|
||||
"ConnectionString": "Server=prod;User=sa;Password=SecretPass123"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 添加注释说明
|
||||
|
||||
在配置文件中添加注释（JSON5格式，或删除注释后部署）：
|
||||
|
||||
```json
|
||||
{
|
||||
// 数据库配置 - 生产环境使用SQL Server
|
||||
"Database": {
|
||||
"Provider": "SqlServer",
|
||||
"ConnectionString": "Server=.;Database=MyApp;..."
|
||||
},
|
||||
|
||||
// PLC配置 - 车间1号PLC
|
||||
"Plc": {
|
||||
"Siemens": {
|
||||
"IpAddress": "192.168.1.100", // 车间1号PLC
|
||||
"CpuType": "S71200"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 配置验证
|
||||
|
||||
Sharp-Basic 会在启动时验证必填配置项：
|
||||
|
||||
```csharp
|
||||
// ✅ 好：配置缺失时会抛出清晰的异常
|
||||
services.AddSharpDatabase<AppDbContext>(config);
|
||||
// 异常：未找到数据库连接字符串配置: Database:ConnectionString
|
||||
|
||||
services.AddSiemensPlc(config.GetSection("Plc:Siemens"));
|
||||
// 异常：未配置PLC IP地址
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
### 典型WPF应用配置
|
||||
|
||||
```json
|
||||
{
|
||||
"System": {
|
||||
"HTTPIp": "127.0.0.1",
|
||||
"HttpPort": 8080
|
||||
},
|
||||
"Database": {
|
||||
"Provider": "Sqlite",
|
||||
"ConnectionString": "Data Source=app.db"
|
||||
},
|
||||
"Logging": {
|
||||
"LogLevel": {
|
||||
"Default": "Information"
|
||||
}
|
||||
},
|
||||
"SharpLog": {
|
||||
"LogFilePath": "logs/app-.log",
|
||||
"RollingInterval": "Day"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 工业IoT应用配置
|
||||
|
||||
```json
|
||||
{
|
||||
"System": {
|
||||
"HTTPIp": "0.0.0.0",
|
||||
"HttpPort": 8080
|
||||
},
|
||||
"Database": {
|
||||
"Provider": "SqlServer",
|
||||
"ConnectionString": "Server=.;Database=ScadaDB;Trusted_Connection=True;"
|
||||
},
|
||||
"Plc": {
|
||||
"Siemens": {
|
||||
"IpAddress": "192.168.1.100",
|
||||
"CpuType": "S71200",
|
||||
"MonitorInterval": 500,
|
||||
"AutoReconnect": true
|
||||
}
|
||||
},
|
||||
"SerialPort": {
|
||||
"PortName": "COM1",
|
||||
"BaudRate": 9600
|
||||
},
|
||||
"Logging": {
|
||||
"LogLevel": {
|
||||
"Default": "Information",
|
||||
"Plc.Siemens": "Debug"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Web服务应用配置
|
||||
|
||||
```json
|
||||
{
|
||||
"System": {
|
||||
"HTTPIp": "0.0.0.0",
|
||||
"HttpPort": 5000,
|
||||
"Scheme": "https"
|
||||
},
|
||||
"Database": {
|
||||
"Provider": "PostgreSQL",
|
||||
"ConnectionString": "Host=localhost;Database=myapi;Username=postgres;Password=***"
|
||||
},
|
||||
"NetServer": {
|
||||
"ListenUrls": [
|
||||
"https://0.0.0.0:5000/",
|
||||
"http://0.0.0.0:5001/"
|
||||
],
|
||||
"ShowDetailedErrors": false
|
||||
},
|
||||
"Cache": {
|
||||
"DefaultExpirationSeconds": 300,
|
||||
"SizeLimit": 10000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [appsettings.template.json](appsettings.template.json) - 完整配置模板
|
||||
- [Config模块README](src/Sharp/Config/README.md) - 配置管理详解
|
||||
- [Data模块README](src/Sharp/Data/README.md) - 数据库配置详解
|
||||
- [Plc.Siemens模块README](src/Sharp/Plc.Siemens/README.md) - PLC配置详解
|
||||
|
||||
---
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 问题：找不到配置节
|
||||
|
||||
**错误信息**：
|
||||
```
|
||||
未找到数据库连接字符串配置: Database:ConnectionString
|
||||
```
|
||||
|
||||
**解决方法**：
|
||||
1. 检查配置文件名是否为 `appsettings.json`
|
||||
2. 检查配置节名称是否正确（区分大小写）
|
||||
3. 检查配置文件是否在项目根目录
|
||||
4. 检查配置文件的 "复制到输出目录" 设置
|
||||
|
||||
### 问题：环境变量不生效
|
||||
|
||||
**原因**：环境变量格式错误
|
||||
|
||||
**正确格式**：
|
||||
```bash
|
||||
# ✅ 正确：双下划线分隔
|
||||
SHARP__Database__Provider=Sqlite
|
||||
|
||||
# ❌ 错误：单下划线
|
||||
SHARP_Database_Provider=Sqlite
|
||||
|
||||
# ❌ 错误：使用冒号
|
||||
SHARP:Database:Provider=Sqlite
|
||||
```
|
||||
|
||||
### 问题：配置被覆盖
|
||||
|
||||
**检查优先级**：
|
||||
1. 先检查环境变量
|
||||
2. 再检查 appsettings.{Environment}.json
|
||||
3. 最后检查 appsettings.json
|
||||
|
||||
---
|
||||
|
||||
**版本**: 1.0.0
|
||||
**更新日期**: 2025-12-22
|
||||
Reference in new issue
Block a user