第二章：环境配置与项目集成

1. 开发环境准备

1.1 必需的开发工具

要使用SqlSugar进行开发，需要准备以下工具：

工具	版本要求	说明
.NET SDK	.NET 6.0+ 或 .NET Framework 4.6.2+	运行时环境
Visual Studio	2019/2022	推荐的IDE
VS Code	最新版	轻量级编辑器
Rider	最新版	JetBrains的IDE
数据库	任意支持的数据库	测试和开发用数据库

1.2 .NET版本支持

SqlSugar支持的.NET版本：

.NET Framework：

.NET Framework 4.6.2
.NET Framework 4.7.x
.NET Framework 4.8

.NET Core / .NET：

.NET Core 3.1
.NET 5.0
.NET 6.0（推荐）
.NET 7.0
.NET 8.0（推荐）
.NET 9.0

1.3 数据库准备

根据你的项目需求，准备相应的数据库：

开发测试推荐：

SQLite：无需安装，适合快速开发和单元测试
MySQL：开源免费，社区支持好
SQL Server LocalDB：轻量级，VS自带

生产环境常用：

MySQL 8.0
SQL Server 2019/2022
PostgreSQL 14+
Oracle 19c
国产数据库（达梦、人大金仓等）

2. NuGet包安装与配置

2.1 核心包安装

安装SqlSugar核心包：

使用.NET CLI：

dotnet add package SqlSugar

使用Package Manager Console：

Install-Package SqlSugar

使用Visual Studio NuGet管理器：

右键项目 → 管理NuGet程序包
搜索”SqlSugar”
点击安装

2.2 数据库驱动包

根据使用的数据库，安装相应的驱动包：

MySQL：

# 推荐使用MySqlConnector（性能更好）
dotnet add package MySqlConnector

# 或使用官方驱动
dotnet add package MySql.Data

SQL Server：

# .NET Core/.NET 5+ 已包含，无需额外安装
# .NET Framework 可能需要
dotnet add package System.Data.SqlClient

PostgreSQL：

dotnet add package Npgsql

Oracle：

# 官方驱动
dotnet add package Oracle.ManagedDataAccess.Core

# 或使用免费驱动
dotnet add package Oracle.EntityFrameworkCore

SQLite：

dotnet add package System.Data.SQLite.Core
# 或
dotnet add package Microsoft.Data.Sqlite

国产数据库：

# 达梦
dotnet add package DmProvider

# 人大金仓
dotnet add package Kdbndp

# 神通
dotnet add package Oscar.Data.OscarClient

2.3 扩展包（可选）

根据需要安装扩展包：

# IOC容器扩展（用于依赖注入）
dotnet add package SqlSugar.IOC

# 雪花ID生成器
dotnet add package SqlSugar.SnowFlakeId

# 分布式锁
dotnet add package SqlSugar.DistributedLock

2.4 版本选择建议

<!-- 推荐的包版本 -->
<PackageReference Include="SqlSugar" Version="5.1.4.*" />

选择版本的建议：

生产环境：使用稳定版本（如5.1.4.x）
开发环境：可以尝试最新版本
大版本升级：先在测试环境验证
长期维护项目：锁定具体版本号

3. 连接字符串配置

3.1 各数据库连接字符串

MySQL：

// 基本连接
"server=localhost;port=3306;database=testdb;uid=root;pwd=123456;charset=utf8mb4;"

// 带连接池
"server=localhost;database=testdb;uid=root;pwd=123456;charset=utf8mb4;pooling=true;min pool size=5;max pool size=100;"

// SSL连接
"server=localhost;database=testdb;uid=root;pwd=123456;sslmode=Required;"

SQL Server：

// Windows身份验证
"Server=localhost;Database=TestDB;Integrated Security=True;"

// SQL身份验证
"Server=localhost;Database=TestDB;User Id=sa;Password=123456;Encrypt=False;"

// 带连接池
"Server=localhost;Database=TestDB;User Id=sa;Password=123456;Min Pool Size=5;Max Pool Size=100;"

PostgreSQL：

// 基本连接
"Host=localhost;Port=5432;Database=testdb;Username=postgres;Password=123456;"

// SSL连接
"Host=localhost;Database=testdb;Username=postgres;Password=123456;SSL Mode=Require;"

Oracle：

// 基本连接
"Data Source=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=ORCL)));User Id=system;Password=123456;"

// 简化连接（需配置tnsnames.ora）
"Data Source=ORCL;User Id=system;Password=123456;"

SQLite：

// 文件数据库
"Data Source=database.db;Version=3;"

// 内存数据库
"Data Source=:memory:;Version=3;"

// 带密码
"Data Source=database.db;Password=mypassword;Version=3;"

3.2 连接字符串最佳实践

1. 使用配置文件

// appsettings.json
{
  "ConnectionStrings": {
    "DefaultConnection": "server=localhost;database=testdb;uid=root;pwd=123456;"
  }
}

2. 使用环境变量

export DB_CONNECTION="server=localhost;database=testdb;uid=root;pwd=123456;"

3. 使用密钥管理

# 使用.NET Secret Manager
dotnet user-secrets set "ConnectionStrings:DefaultConnection" "server=..."

4. 生产环境加密

// 使用加密的连接字符串
var encryptedConnectionString = Configuration["ConnectionStrings:Encrypted"];
var connectionString = DecryptConnectionString(encryptedConnectionString);

3.3 连接字符串安全性

不要做的事：

// ❌ 不要在代码中硬编码
var connectionString = "server=localhost;database=prod;uid=root;pwd=ProductionPassword123;";

应该做的事：

// ✅ 从配置读取
var connectionString = Configuration.GetConnectionString("DefaultConnection");

// ✅ 使用环境变量
var connectionString = Environment.GetEnvironmentVariable("DB_CONNECTION");

// ✅ 使用Azure Key Vault等密钥管理服务
var connectionString = await keyVaultClient.GetSecretAsync("db-connection");

4. 依赖注入集成

4.1 原生依赖注入

在Startup.cs或Program.cs中配置：

// .NET 6+ Program.cs
using SqlSugar;

var builder = WebApplication.CreateBuilder(args);

// 注册SqlSugarClient
builder.Services.AddScoped<ISqlSugarClient>(s =>
{
    return new SqlSugarClient(new ConnectionConfig
    {
        ConnectionString = builder.Configuration.GetConnectionString("DefaultConnection"),
        DbType = DbType.MySql,
        IsAutoCloseConnection = true,
        InitKeyType = InitKeyType.Attribute
    });
});

var app = builder.Build();

4.2 使用SqlSugar.IOC扩展

安装扩展包后：

using SqlSugar;
using SqlSugar.IOC;

var builder = WebApplication.CreateBuilder(args);

// 使用IOC扩展配置
builder.Services.AddSqlSugar(new IocConfig()
{
    ConnectionString = builder.Configuration.GetConnectionString("DefaultConnection"),
    DbType = IocDbType.MySql,
    IsAutoCloseConnection = true
});

var app = builder.Build();

4.3 多数据库配置

配置多个数据库连接：

builder.Services.AddSqlSugar(new List<IocConfig>
{
    new IocConfig
    {
        ConfigId = "db1",
        ConnectionString = builder.Configuration.GetConnectionString("Db1"),
        DbType = IocDbType.MySql,
        IsAutoCloseConnection = true
    },
    new IocConfig
    {
        ConfigId = "db2",
        ConnectionString = builder.Configuration.GetConnectionString("Db2"),
        DbType = IocDbType.SqlServer,
        IsAutoCloseConnection = true
    }
});

4.4 在控制器中使用

[ApiController]
[Route("api/[controller]")]
public class UserController : ControllerBase
{
    private readonly ISqlSugarClient _db;

    public UserController(ISqlSugarClient db)
    {
        _db = db;
    }

    [HttpGet]
    public async Task<IActionResult> GetUsers()
    {
        var users = await _db.Queryable<User>().ToListAsync();
        return Ok(users);
    }
}

5. ASP.NET Core项目集成

5.1 完整的项目配置

1. appsettings.json配置：

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  },
  "ConnectionStrings": {
    "DefaultConnection": "server=localhost;database=myapp;uid=root;pwd=123456;charset=utf8mb4;"
  },
  "SqlSugar": {
    "IsAutoCloseConnection": true,
    "InitKeyType": "Attribute",
    "AopLogEnabled": true
  }
}

2. Program.cs配置：

using SqlSugar;

var builder = WebApplication.CreateBuilder(args);

// 添加SqlSugar服务
builder.Services.AddScoped<ISqlSugarClient>(s =>
{
    var config = builder.Configuration;
    var db = new SqlSugarClient(new ConnectionConfig
    {
        ConnectionString = config.GetConnectionString("DefaultConnection"),
        DbType = DbType.MySql,
        IsAutoCloseConnection = config.GetValue<bool>("SqlSugar:IsAutoCloseConnection"),
        InitKeyType = InitKeyType.Attribute
    });

    // 配置AOP
    if (config.GetValue<bool>("SqlSugar:AopLogEnabled"))
    {
        db.Aop.OnLogExecuting = (sql, pars) =>
        {
            Console.WriteLine($"SQL: {sql}");
        };
    }

    return db;
});

// 添加控制器
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// 中间件配置
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseAuthorization();
app.MapControllers();
app.Run();

5.2 仓储模式集成

1. 定义仓储接口：

public interface IRepository<T> where T : class, new()
{
    Task<T> GetByIdAsync(object id);
    Task<List<T>> GetAllAsync();
    Task<int> InsertAsync(T entity);
    Task<bool> UpdateAsync(T entity);
    Task<bool> DeleteAsync(object id);
}

2. 实现仓储类：

public class Repository<T> : IRepository<T> where T : class, new()
{
    private readonly ISqlSugarClient _db;

    public Repository(ISqlSugarClient db)
    {
        _db = db;
    }

    public async Task<T> GetByIdAsync(object id)
    {
        return await _db.Queryable<T>().InSingleAsync(id);
    }

    public async Task<List<T>> GetAllAsync()
    {
        return await _db.Queryable<T>().ToListAsync();
    }

    public async Task<int> InsertAsync(T entity)
    {
        return await _db.Insertable(entity).ExecuteReturnIdentityAsync();
    }

    public async Task<bool> UpdateAsync(T entity)
    {
        return await _db.Updateable(entity).ExecuteCommandHasChangeAsync();
    }

    public async Task<bool> DeleteAsync(object id)
    {
        return await _db.Deleteable<T>().In(id).ExecuteCommandHasChangeAsync();
    }
}

3. 注册仓储：

builder.Services.AddScoped(typeof(IRepository<>), typeof(Repository<>));

5.3 工作单元模式

public interface IUnitOfWork
{
    void BeginTran();
    void CommitTran();
    void RollbackTran();
    ISqlSugarClient GetDbClient();
}

public class UnitOfWork : IUnitOfWork
{
    private readonly ISqlSugarClient _db;

    public UnitOfWork(ISqlSugarClient db)
    {
        _db = db;
    }

    public void BeginTran() => _db.Ado.BeginTran();
    public void CommitTran() => _db.Ado.CommitTran();
    public void RollbackTran() => _db.Ado.RollbackTran();
    public ISqlSugarClient GetDbClient() => _db;
}

6. 配置文件管理

6.1 appsettings.json配置

基础配置：

{
  "SqlSugar": {
    "ConnectionString": "server=localhost;database=myapp;uid=root;pwd=123456;",
    "DbType": "MySql",
    "IsAutoCloseConnection": true,
    "InitKeyType": "Attribute",
    "AopConfig": {
      "IsLogSql": true,
      "IsLogError": true,
      "IsLogSlowSql": true,
      "SlowSqlMilliseconds": 1000
    }
  }
}

多数据库配置：

{
  "SqlSugar": {
    "Connections": [
      {
        "ConfigId": "Main",
        "ConnectionString": "server=localhost;database=main;uid=root;pwd=123456;",
        "DbType": "MySql",
        "IsAutoCloseConnection": true
      },
      {
        "ConfigId": "Log",
        "ConnectionString": "server=localhost;database=log;uid=root;pwd=123456;",
        "DbType": "MySql",
        "IsAutoCloseConnection": true
      }
    ]
  }
}

6.2 读取配置的辅助类

public class SqlSugarConfig
{
    public string ConnectionString { get; set; }
    public string DbType { get; set; }
    public bool IsAutoCloseConnection { get; set; }
    public string InitKeyType { get; set; }
    public AopConfig AopConfig { get; set; }
}

public class AopConfig
{
    public bool IsLogSql { get; set; }
    public bool IsLogError { get; set; }
    public bool IsLogSlowSql { get; set; }
    public int SlowSqlMilliseconds { get; set; }
}

6.3 使用配置类

var sqlSugarConfig = builder.Configuration.GetSection("SqlSugar").Get<SqlSugarConfig>();

builder.Services.AddScoped<ISqlSugarClient>(s =>
{
    var db = new SqlSugarClient(new ConnectionConfig
    {
        ConnectionString = sqlSugarConfig.ConnectionString,
        DbType = Enum.Parse<DbType>(sqlSugarConfig.DbType),
        IsAutoCloseConnection = sqlSugarConfig.IsAutoCloseConnection,
        InitKeyType = Enum.Parse<InitKeyType>(sqlSugarConfig.InitKeyType)
    });

    // 配置AOP
    if (sqlSugarConfig.AopConfig.IsLogSql)
    {
        db.Aop.OnLogExecuting = (sql, pars) =>
        {
            // 记录SQL日志
        };
    }

    return db;
});

7. 多环境配置

7.1 环境配置文件

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

appsettings.json              # 基础配置
appsettings.Development.json  # 开发环境
appsettings.Staging.json      # 测试环境
appsettings.Production.json   # 生产环境

appsettings.Development.json：

{
  "ConnectionStrings": {
    "DefaultConnection": "server=localhost;database=myapp_dev;uid=root;pwd=dev123;"
  },
  "SqlSugar": {
    "AopConfig": {
      "IsLogSql": true
    }
  }
}

appsettings.Production.json：

{
  "ConnectionStrings": {
    "DefaultConnection": "server=prod-server;database=myapp;uid=produser;pwd=***;"
  },
  "SqlSugar": {
    "AopConfig": {
      "IsLogSql": false
    }
  }
}

7.2 环境切换

1. 通过环境变量：

# Windows
set ASPNETCORE_ENVIRONMENT=Production

# Linux/Mac
export ASPNETCORE_ENVIRONMENT=Production

2. launchSettings.json：

{
  "profiles": {
    "Development": {
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "Production": {
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    }
  }
}

7.3 根据环境动态配置

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsDevelopment())
{
    // 开发环境特殊配置
    builder.Services.AddScoped<ISqlSugarClient>(s =>
    {
        var db = new SqlSugarClient(new ConnectionConfig
        {
            ConnectionString = builder.Configuration.GetConnectionString("DefaultConnection"),
            DbType = DbType.MySql,
            IsAutoCloseConnection = true
        });

        // 开发环境启用SQL日志
        db.Aop.OnLogExecuting = (sql, pars) =>
        {
            Console.WriteLine($"[SQL] {sql}");
        };

        return db;
    });
}
else
{
    // 生产环境配置
    builder.Services.AddScoped<ISqlSugarClient>(s =>
    {
        var db = new SqlSugarClient(new ConnectionConfig
        {
            ConnectionString = builder.Configuration.GetConnectionString("DefaultConnection"),
            DbType = DbType.MySql,
            IsAutoCloseConnection = true
        });

        // 生产环境只记录慢SQL
        db.Aop.OnLogExecuting = (sql, pars) =>
        {
            // 记录到日志系统
        };

        return db;
    });
}

8. 常见问题与解决方案

8.1 连接失败问题

问题1：连接字符串错误

错误：Unable to connect to any of the specified MySQL hosts

解决方案：

// 检查连接字符串格式
// ✅ 正确
"server=localhost;database=test;uid=root;pwd=123;"

// ❌ 错误（多余分号）
"server=localhost;database=test;uid=root;pwd=123;;"

问题2：数据库驱动未安装

错误：Could not load file or assembly 'MySqlConnector'

解决方案：

dotnet add package MySqlConnector

8.2 依赖注入问题

问题：SqlSugarClient生命周期不正确

错误：Cannot access a disposed object

解决方案：

// ❌ 错误（Singleton会导致问题）
builder.Services.AddSingleton<ISqlSugarClient>(...);

// ✅ 正确（使用Scoped）
builder.Services.AddScoped<ISqlSugarClient>(...);

8.3 CodeFirst问题

问题：表未创建

// 确保调用InitTables
db.CodeFirst.InitTables(typeof(User), typeof(Order));

8.4 性能问题

问题：大量数据查询慢

解决方案：

// ❌ 避免使用ToList()加载全部数据
var all = db.Queryable<User>().ToList(); // 可能有数百万条

// ✅ 使用分页
var page = db.Queryable<User>().ToPageList(1, 100);

// ✅ 使用游标
await db.Queryable<User>().ForEachAsync(user =>
{
    // 处理每条数据
});

8.5 中文乱码问题

MySQL中文乱码：

// 在连接字符串中添加charset
"server=localhost;database=test;uid=root;pwd=123;charset=utf8mb4;"

8.6 时区问题

MySQL时区问题：

// 方法1：连接字符串设置
"server=localhost;database=test;uid=root;pwd=123;Convert Zero Datetime=True;"

// 方法2：全局配置
db.Ado.IsEnableLogEvent = true;
db.Ado.SqlExecutingTime = DateTime.Now;

本章小结

本章详细介绍了SqlSugar的环境配置和项目集成：

开发环境：准备必要的工具和数据库
NuGet安装：安装核心包和数据库驱动
连接配置：各种数据库的连接字符串
依赖注入：在ASP.NET Core中集成SqlSugar
项目集成：完整的项目配置示例
配置管理：使用appsettings.json管理配置
多环境：开发、测试、生产环境的配置
问题解决：常见问题的解决方案

掌握这些配置知识后，你就可以在任何.NET项目中轻松使用SqlSugar了。

在下一章，我们将深入学习数据库连接的高级配置和管理。

下一章：第三章：数据库连接与配置

第二章：环境配置与项目集成

目录

1. 开发环境准备

1.1 必需的开发工具

1.2 .NET版本支持

1.3 数据库准备

2. NuGet包安装与配置

2.1 核心包安装

2.2 数据库驱动包

2.3 扩展包（可选）

2.4 版本选择建议

3. 连接字符串配置

3.1 各数据库连接字符串

3.2 连接字符串最佳实践

3.3 连接字符串安全性

4. 依赖注入集成

4.1 原生依赖注入

4.2 使用SqlSugar.IOC扩展

4.3 多数据库配置

4.4 在控制器中使用

5. ASP.NET Core项目集成

5.1 完整的项目配置

5.2 仓储模式集成

5.3 工作单元模式

6. 配置文件管理

6.1 appsettings.json配置

6.2 读取配置的辅助类

6.3 使用配置类

7. 多环境配置

7.1 环境配置文件

7.2 环境切换

7.3 根据环境动态配置

8. 常见问题与解决方案

8.1 连接失败问题

8.2 依赖注入问题

8.3 CodeFirst问题

8.4 性能问题

8.5 中文乱码问题

8.6 时区问题

本章小结