Set-CimInstance

通过调用 CIM 类的 ModifyInstance 方法修改 CIM 服务器上的 CIM 实例。

语法

Set-CimInstance
   [-ComputerName <String[]>]
   [-ResourceUri <Uri>]
   [-OperationTimeoutSec <UInt32>]
   [-InputObject] <CimInstance>
   [-Property <IDictionary>]
   [-PassThru]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Set-CimInstance
   -CimSession <CimSession[]>
   [-ResourceUri <Uri>]
   [-OperationTimeoutSec <UInt32>]
   [-InputObject] <CimInstance>
   [-Property <IDictionary>]
   [-PassThru]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Set-CimInstance
   -CimSession <CimSession[]>
   [-Namespace <String>]
   [-OperationTimeoutSec <UInt32>]
   [-Query] <String>
   [-QueryDialect <String>]
   -Property <IDictionary>
   [-PassThru]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Set-CimInstance
   [-ComputerName <String[]>]
   [-Namespace <String>]
   [-OperationTimeoutSec <UInt32>]
   [-Query] <String>
   [-QueryDialect <String>]
   -Property <IDictionary>
   [-PassThru]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

说明

此 cmdlet 仅在 Windows 平台上可用。

此 cmdlet 可修改 CIM 服务器上的 CIM 实例。

如果未指定 InputObject 参数,则 cmdlet 按以下其中一种方式工作:

  • 如果既未指定 ComputerName 参数,也未指定 CimSession 参数,则此 cmdlet 将使用组件对象模型 (COM) 会话来针对本地 Windows Management Instrumentation (WMI) 运行。
  • 如果指定了 ComputerName 参数或 CimSession 参数,则此 cmdlet 针对由 ComputerName 参数或 CimSession 参数指定的 CIM 服务器运行。

如果指定了 InputObject 参数,则 cmdlet 按以下其中一种方式工作:

  • 如果既未指定 ComputerName 参数,也没有指定 CimSession 参数,则此 cmdlet 将使用输入对象中的 CIM 会话或计算机名称。
  • 如果指定了 ComputerName 参数或CimSession 参数,则此 cmdlet 使用 CimSession 参数值或 ComputerName 参数值。 这不是很常见。

示例

示例 1:设置 CIM 实例

此示例使用 Query 参数将 VariableValue 属性的值设置为 abcd。 可以修改与 Windows Management Instrumentation 查询语言 (WQL) 查询匹配的实例。

Set-CimInstance -Query 'Select * from Win32_Environment where name LIKE "testvar%"' -Property @{VariableValue="abcd"}

示例 2:使用管道设置 CIM 实例属性

此示例使用 Get-CimInstance cmdlet 检索由 Query 参数筛选的 CIM 实例对象。 Set-CimInstance cmdlet 将 VariableValue 属性的值修改为 abcd。

Get-CimInstance -Query 'Select * from Win32_Environment where name LIKE "testvar%"' |
  Set-CimInstance -Property @{VariableValue="abcd"}

示例 3:使用输入对象设置 CIM 实例属性

$x = Get-CimInstance -Query 'Select * from Win32_Environment where Name="testvar"'
Set-CimInstance -InputObject $x -Property @{VariableValue="somevalue"} -PassThru

此示例使用 Get-CimInstance 将 Query 参数筛选的 CIM 实例对象检索到变量 $x 中,然后将变量的内容传递给 Set-CimInstance cmdlet。 然后,Set-CimInstance 将 VariableValue 属性修改为 somevalue。 由于使用了 Passthru 参数,此示例将返回修改后的 CIM 实例对象。

示例 4:设置 CIM 实例属性

此示例使用 Get-CimInstance cmdlet 将 Query 参数中指定的 CIM 实例对象检索到 $x 变量中,并更改要更改的对象的 VariableValue 属性值。 然后会使用 Set-CimInstance cmdlet 保存 CIM 实例对象。 由于使用了 Passthru 参数,此示例将返回修改后的 CIM 实例对象。

$x = Get-CimInstance -Query 'Select * from Win32_Environment where name="testvar"'
$x.VariableValue = "Change"
Set-CimInstance -CimInstance $x -PassThru

示例 5:使用 WhatIf 显示要修改的 CIM 实例列表

此示例使用通用参数 WhatIf 指定不应执行修改操作,但仅输出在执行修改操作后会发生的情况。

Set-CimInstance -Query 'Select * from Win32_Environment where name LIKE "testvar%"' -Property @{VariableValue="abcd"} -WhatIf

示例 6:在用户确认后设置 CIM 实例

此示例使用通用参数 Confirm 指定仅在用户确认后才能执行修改。

Set-CimInstance -Query 'Select * from Win32_Environment where name LIKE "testvar%"' -Property @{VariableValue="abcd"} -Confirm

示例 7:设置创建的 CIM 实例

此示例使用 New-CimInstance cmdlet 创建具有指定属性的 CIM 实例,并将其内容检索到 $x 变量中。 然后,变量将传递给 Set-CimInstance cmdlet,该 cmdlet 将 VariableValue 属性的值修改为 somevalue。 由于使用了 Passthru 参数,此示例将返回修改后的 CIM 实例对象。

$x = New-CimInstance -ClassName Win32_Environment -Property @{Name="testvar";UserName="domain\user"} -Key Name,UserName -ClientOnly
Set-CimInstance -CimInstance $x -Property @{VariableValue="somevalue"} -PassThru

参数

-CimSession

在远程计算机上运行 cmdlet。 输入计算机名或会话对象,例如 New-CimSessionGet-CimSession cmdlet 的输出。

类型:CimSession[]
Position:Named
默认值:None
必需:True
接受管道输入:True
接受通配符:False

-ComputerName

指定要在其中运行 CIM 操作的计算机的名称。 可以指定完全限定的域名 (FQDN),也可以指定 NetBIOS 名称。

如果未指定此参数,cmdlet 将使用组件对象模型 (COM) 在本地计算机上执行该操作。

如果指定此参数,cmdlet 将使用 WSMan 协议创建到指定计算机的临时会话。

如果在同一台计算机上执行了多个操作,则使用 CIM 会话进行连接可提供更好的性能。

类型:String[]
别名:CN, ServerName
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-Confirm

提示你在运行 cmdlet 之前进行确认。

类型:SwitchParameter
别名:cf
Position:Named
默认值:False
必需:False
接受管道输入:False
接受通配符:False

-InputObject

指定要用作输入的 CIM 实例对象。

InputObject 参数不枚举集合。 如果传递集合,则会引发错误。 使用集合时,通过管道传递输入来枚举值。

类型:CimInstance
别名:CimInstance
Position:0
默认值:None
必需:True
接受管道输入:True
接受通配符:False

-Namespace

指定 CIM 操作的命名空间。 默认命名空间为 root/cimv2。 可以使用 Tab 完成浏览命名空间列表,因为 PowerShell 从本地 WMI 服务器获取命名空间列表以提供命名空间列表。

类型:String
Position:Named
默认值:None
必需:False
接受管道输入:True
接受通配符:False

-OperationTimeoutSec

指定 cmdlet 等待计算机响应的时间量。 默认情况下,此参数的值为 0,这意味着 cmdlet 使用服务器的默认超时值。

如果 OperationTimeoutSec 参数设置为小于可靠连接重试超时 3 分钟的值,则超过 OperationTimeoutSec 参数的值的网络故障不可恢复,因为服务器上的操作在客户端重新连接之前超时。

类型:UInt32
别名:OT
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-PassThru

返回一个代表你所处理的项目的对象。 默认情况下,此 cmdlet 将不产生任何输出。

类型:SwitchParameter
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-Property

将 CIM 实例的属性指定为哈希表(使用名称/值对)。 只会更改使用此参数指定的属性。 CIM 实例的其他属性不会更改。

类型:IDictionary
别名:Arguments
Position:Named
默认值:None
必需:False
接受管道输入:True
接受通配符:False

-Query

指定要在 CIM 服务器上运行的查询,以检索运行该 cmdlet 的 CIM 实例。 可以使用 QueryDialect 参数指定查询方言。

如果指定的值包含双引号 (")、单引号 (') 或反斜杠 (\),则必须使用反斜杠 (\) 字符作为这些字符的前缀来对其进行转义。 如果指定的值使用 WQL LIKE 运算符,则必须将以下字符括在方括号 [] 中来对其进行转义:百分号 (%)、下划线 (_) 或左方括号 ([)。

类型:String
Position:0
默认值:None
必需:True
接受管道输入:True
接受通配符:False

-QueryDialect

指定用于 Query 参数的查询语言。 此参数可接受的值为:WQLCQL。 默认值为 WQL

类型:String
Position:Named
默认值:None
必需:False
接受管道输入:True
接受通配符:False

-ResourceUri

指定资源类或实例的资源统一资源标识符 (URI)。 URI 用于标识计算机上特定类型的资源,例如磁盘或进程。

URI 由前缀和指向资源的路径组成。 例如:

  • http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_LogicalDisk
  • http://intel.com/wbem/wscim/1/amt-schema/1/AMT_GeneralSettings

默认情况下,如果未指定此参数,则使用 DMTF 标准资源 URI http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/,并将类名追加到其中。

ResourceURI 只能与使用 WSMan 协议创建的 CIM 会话一起使用,或者在指定 ComputerName 参数时使用,该参数会使用 WSMan 创建 CIM 会话。 如果在未指定 ComputerName 参数的情况下指定此参数,或者指定使用 DCOM 协议创建的 CIM 会话,则会收到错误,因为 DCOM 协议不支持 ResourceURI 参数。

如果同时指定了 ResourceUri 参数和 Filter 参数,则会忽略 Filter 参数。

类型:Uri
Position:Named
默认值:None
必需:False
接受管道输入:True
接受通配符:False

-WhatIf

显示运行该 cmdlet 时会发生什么情况。 cmdlet 未运行。

类型:SwitchParameter
别名:wi
Position:Named
默认值:False
必需:False
接受管道输入:False
接受通配符:False

输入

CimInstance

输出

None

默认情况下,此 cmdlet 不返回任何输出。

CimInstance

使用 Passthru 参数时,此 cmdlet 将返回修改后的 CIM 实例对象。

备注

PowerShell 包含以下 Set-CimInstance 别名:

  • Windows:
    • scim

此 cmdlet 仅在 Windows 平台上可用。