sharp-basic/CONFIGURATION.md

Sharp-Basic 配置指南

本文档说明 Sharp-Basic 框架的配置约定和最佳实践。

目录

• 配置文件模板
• 约定配置节名称
• 环境变量覆盖
• 模块配置详解
• 最佳实践

---

配置文件模板

Sharp-Basic 提供了完整的配置文件模板：appsettings.template.json

使用方法

1. 复制模板文件

   cp appsettings.template.json appsettings.json
   

2. 根据项目需要选择性保留配置

   • 只使用数据库？保留 Database 节
   • 需要PLC通信？保留 Plc:Siemens 节
   • 不需要的配置可以删除

3. 修改配置值

   {
     "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区分）
• 冒号 : 用双下划线 __ 替代

示例

覆盖数据库配置

# 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配置

# 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配置

# Windows (PowerShell)
$env:SHARP__System__HttpPort="9090"

# Linux/macOS
export SHARP__System__HttpPort=9090

优先级

配置优先级从高到低：

1. 环境变量 - 最高优先级
2. appsettings.{Environment}.json - 环境特定配置
3. appsettings.json - 默认配置

---

模块配置详解

1. 数据库配置 (Database)

最简配置

{
  "Database": {
    "Provider": "Sqlite",
    "ConnectionString": "Data Source=app.db"
  }
}

代码中使用

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)

最简配置

{
  "Plc": {
    "Siemens": {
      "IpAddress": "192.168.1.100",
      "CpuType": "S71200"
    }
  }
}

代码中使用

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)

最简配置

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  },
  "SharpLog": {
    "LogFilePath": "logs/app-.log",
    "RollingInterval": "Day"
  }
}

代码中使用

services.AddLogging(b => b.AddSharpLog());  // 自动读取 SharpLog 节

---

4. HTTP配置 (System, NetClient, NetServer)

System配置（共享默认值）

{
  "System": {
    "HTTPIp": "127.0.0.1",
    "HttpPort": 8080,
    "TimeoutSeconds": 30,
    "Scheme": "http"
  }
}

NetClient配置（可选，留空则使用System默认值）

{
  "NetClient": {
    "BaseAddress": "http://api.example.com",
    "Timeout": "00:00:30",
    "EnableLogging": true
  }
}

NetServer配置（可选，留空则使用System默认值）

{
  "NetServer": {
    "ListenUrls": [
      "http://localhost:8080/"
    ]
  }
}

---

最佳实践

1. 按需配置

只保留需要的配置节，不要保留所有模板内容：

{
  // ❌ 不好：保留了不使用的配置
  "Database": { ... },
  "Plc": { ... },
  "SerialPort": { ... },
  "Python": { ... }
}

{
  // ✅ 好：只保留需要的配置
  "Database": { ... },
  "Logging": { ... }
}

2. 使用环境特定配置

为不同环境创建不同的配置文件：

appsettings.json                  # 默认配置
appsettings.Development.json      # 开发环境
appsettings.Production.json       # 生产环境
appsettings.Testing.json          # 测试环境

3. 敏感信息使用环境变量

不要在配置文件中存储敏感信息（密码、密钥等）：

# ✅ 好：使用环境变量
export SHARP__Database__ConnectionString="Server=prod;User=sa;Password=SecretPass123"
export SHARP__Plc__Siemens__IpAddress="192.168.1.100"

// ❌ 不好：敏感信息写在配置文件
{
  "Database": {
    "ConnectionString": "Server=prod;User=sa;Password=SecretPass123"
  }
}

4. 添加注释说明

在配置文件中添加注释（JSON5格式，或删除注释后部署）：

{
  // 数据库配置 - 生产环境使用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 会在启动时验证必填配置项：

// ✅ 好：配置缺失时会抛出清晰的异常
services.AddSharpDatabase<AppDbContext>(config);
// 异常：未找到数据库连接字符串配置: Database:ConnectionString

services.AddSiemensPlc(config.GetSection("Plc:Siemens"));
// 异常：未配置PLC IP地址

---

快速参考

典型WPF应用配置

{
  "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应用配置

{
  "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服务应用配置

{
  "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 - 完整配置模板
• Config模块README - 配置管理详解
• Data模块README - 数据库配置详解
• Plc.Siemens模块README - PLC配置详解

---

故障排查

问题：找不到配置节

错误信息：

未找到数据库连接字符串配置: Database:ConnectionString

解决方法：

1. 检查配置文件名是否为 appsettings.json
2. 检查配置节名称是否正确（区分大小写）
3. 检查配置文件是否在项目根目录
4. 检查配置文件的 "复制到输出目录" 设置

问题：环境变量不生效

原因：环境变量格式错误

正确格式：

# ✅ 正确：双下划线分隔
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