为什么.NET调用存储过程时SQL参数映射与SqlParameter定义不一致导致报错？

本文共计1015个文字，预计阅读时间需要5分钟。

《SqlParameter 传参失败，90% 是方向没设对、类型不匹配或参数名拼写错，而不是存储过程本身有问题。》

SqlParameter 的 ParameterDirection 必须显式指定输出类参数

调用带 OUTPUT 或 RETURN 参数的存储过程时，SqlParameter 默认是 Input 方向，不改就会丢值甚至报错“必须声明标量变量”。

• Output 参数（如 @result INT OUTPUT）：必须设置 parameter.Direction = ParameterDirection.Output
• ReturnValue（对应存储过程的 RETURN 值）：需单独建一个 SqlParameter，Direction 设为 ParameterDirection.ReturnValue，且 ParameterName 必须是空字符串或 "RETURN_VALUE"（不同驱动行为略有差异）
• InputOutput 参数：既要传入初始值，又期望被存储过程修改，Direction 和 Value 都得配好

SQL Server 类型和 .NET 类型不严格对应，DbType 或 SqlDbType 写错会静默截断或报错

比如把 datetime2 列映射成 SqlDbType.DateTime，或把 varchar(max) 当作 SqlDbType.VarChar 却没设 Size = -1，都可能触发“无法将值转换为请求的类型”之类错误。

• 优先用 SqlDbType 枚举（比 DbType 更精确），例如 SqlDbType.NVarChar、SqlDbType.Int
• varchar(max) / nvarchar(max)：必须设 Size = -1，否则按默认长度（如 4000）截断
• decimal(p,s)：要同时指定 Precision 和 Scale 属性，否则可能精度丢失
• 空值传递：用 DBNull.Value，别用 null（C# 中 null 会被转成 NULL，但某些旧版驱动不识别）

参数名大小写和前缀必须和存储过程中定义的一致

SQL Server 默认不区分大小写，但 SqlParameter 的 ParameterName 字符串必须和存储过程中声明的完全一致——包括 @ 符号。漏写 @ 是最常见低级错误。

• 错：new SqlParameter("id", 123) → 存储过程收不到 @id
• 对：new SqlParameter("@id", 123)
• 如果存储过程定义的是 @ID（全大写），那 C# 里也得写 "@ID"，尤其在启用了区分标识符的数据库中
• 调用 EXEC 语句时，SQL 字符串里也要保持一致："EXEC dbo.TestPro @id"，不能写成 "EXEC dbo.TestPro id"

Microsoft.Data.SqlClient 和 System.Data.SqlClient 行为有细微差别

如果你从老项目迁移或混用两个包，SqlParameter 构造逻辑和默认行为可能不同，比如对 Size 的推断、对空字符串的处理、对 ReturnValue 的命名要求等。

• 新项目统一用 Microsoft.Data.SqlClient（v4.0.1+），它更活跃、支持 .NET 6+ 和 Azure SQL 新特性
• System.Data.SqlClient 已标记为“legacy”，.NET Core 3.1 后不再更新
• 检查项目引用的是哪个程序集：看 using 语句是 System.Data.SqlClient 还是 Microsoft.Data.SqlClient，别用错命名空间
• 同名类（如 SqlParameter）来自不同程序集时，编译器不会报错，但运行时行为可能出人意料

真正容易被忽略的是：参数顺序无关紧要，但名称和方向必须严丝合缝；类型匹配不是“差不多就行”，而是“字节级对齐”；还有，别信调试时看到的 Value 显示——它可能是格式化后的字符串，实际传到 SQL Server 的二进制值可能已变形。