PowerShell SQL脚本中SqlClient类成员用法及代码详解

这段脚本没有使用PowerShell专属的SQL相关cmdlet，而是直接调用.NET内置的System.Data.SqlClient托管组件实现SQL Server交互，你看到的带.的成员都是对应.NET类的原生属性、方法、事件绑定入口，不是自定义cmdlet。

逐行运行逻辑拆解 #

• $conn = New-Object System.Data.SqlClient.SqlConnection "Server = <server here> ;Database = <database here>;Integrated Security = SSPI;"
  实例化SQL Server连接对象，连接字符串配置为使用Windows集成认证（SSPI），连接指定实例下的目标数据库。
• $global:msg = ""
  定义全局作用域的字符串变量，用于存储SQL服务端返回的消息文本，规避事件处理程序的局部变量作用域限制，脚本执行完成后外部也可以读取到捕获的消息内容。
• $handler = [System.Data.SqlClient.SqlInfoMessageEventHandler] { param($sender, $event) $global:msg = $event.Message; Write-Host $global:msg }
  定义InfoMessage事件的处理委托：当连接收到SQL服务端返回的非严重错误消息（比如PRINT语句输出、低级别运行警告）时，自动执行大括号内的逻辑——将消息内容存入全局变量，同时直接打印到当前控制台。
• $conn.add_InfoMessage($handler)
  这是PowerShell中绑定.NET类事件的固定写法，作用是将刚才定义的处理程序注册到连接对象的InfoMessage事件上，后续事件触发时就会执行对应的处理逻辑。对应解绑事件的写法为$conn.remove_InfoMessage($handler)，这是.NET事件机制的通用访问规则，不是PowerShell独有的语法。
• $conn.FireInfoMessageEventOnUserErrors = $true
  这是SqlConnection类的布尔类型属性：默认配置下，SQL返回严重级别≥11的用户自定义错误会直接抛出异常终止执行，不会触发InfoMessage事件；将该属性设为$true后，即使用户自定义错误（比如RAISERROR抛出的、严重级别不超过16的错误）也会先触发InfoMessage事件传出消息，不会直接中断脚本。这段脚本里用PRINT输出消息即使不开启该属性也能正常捕获，开启后可以兼容更多自定义错误场景的消息采集。
• $conn.Open()
  建立和SQL Server实例的物理连接，连接成功后才可以执行数据库操作命令。
• $cmd = $conn.CreateCommand()
  基于当前已打开的连接，创建一个SQL命令对象，用于承载待执行的SQL语句与相关配置。
• $cmd.CommandTimeout=0
  设置命令执行超时时间为0，即无超时限制，适合执行长耗时SQL，不会触发默认30秒执行超时中断。
• $cmd.CommandText = "IF NOT EXISTS (SELECT * FROM TABLE WHERE COLUMN = '$variable') Print 'This is just a placeholder message'"
  为命令对象赋值待执行的SQL文本，逻辑为判断目标表中是否存在指定列匹配变量值的记录，不存在则打印预设提示文本。注意这里直接拼接PowerShell变量存在SQL注入风险，生产环境建议改用参数化查询写法。
• $res = $cmd.ExecuteNonQuery()
  执行已配置的SQL语句，该方法专门用于执行不返回结果集的SQL（增删改、流程控制、PRINT输出类语句），返回值为语句影响的行数，这段脚本的逻辑下返回值为-1。
• $conn.Close()
  关闭已打开的数据库连接，释放占用的连接资源。

类成员查询说明 #

你疑惑的这些类成员，都是System.Data.SqlClient命名空间下对应类的公开可访问成员：

所有add_<事件名>格式的方法，都是.NET事件在PowerShell中的标准绑定入口，对应C#中用+=绑定事件的写法，任意.NET类定义的公开事件，都可以在PowerShell中通过这个格式注册处理程序。
这段代码涉及的核心成员包括：

• SqlConnection类的InfoMessage事件：连接收到SQL服务端返回的提示类消息时触发
• SqlConnection类的FireInfoMessageEventOnUserErrors属性：控制用户自定义错误是否路由到InfoMessage事件
• SqlCommand类的CommandTimeout属性：控制命令执行的超时时长
• SqlCommand类的ExecuteNonQuery方法：执行无结果集返回的SQL语句
  所有这些成员的功能、参数、取值范围都可以在System.Data.SqlClient相关的官方类定义文档中查到。

内容的提问来源于stack exchange，提问作者Ebeeze