New-CimInstance

  • Referenz
Modul:
CimCmdlets

Erstellt eine CIM-Instanz.

Syntax

New-CimInstance
   [-ClassName] <String>
   [-Key <String[]>]
   [[-Property] <IDictionary>]
   [-Namespace <String>]
   [-OperationTimeoutSec <UInt32>]
   [-ComputerName <String[]>]
   [-ClientOnly]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
New-CimInstance
   [-ClassName] <String>
   [-Key <String[]>]
   [[-Property] <IDictionary>]
   [-Namespace <String>]
   [-OperationTimeoutSec <UInt32>]
   -CimSession <CimSession[]>
   [-ClientOnly]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
New-CimInstance
   -ResourceUri <Uri>
   [-Key <String[]>]
   [[-Property] <IDictionary>]
   [-Namespace <String>]
   [-OperationTimeoutSec <UInt32>]
   -CimSession <CimSession[]>
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
New-CimInstance
   -ResourceUri <Uri>
   [-Key <String[]>]
   [[-Property] <IDictionary>]
   [-Namespace <String>]
   [-OperationTimeoutSec <UInt32>]
   [-ComputerName <String[]>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
New-CimInstance
   [-CimClass] <CimClass>
   [[-Property] <IDictionary>]
   [-OperationTimeoutSec <UInt32>]
   -CimSession <CimSession[]>
   [-ClientOnly]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
New-CimInstance
   [-CimClass] <CimClass>
   [[-Property] <IDictionary>]
   [-OperationTimeoutSec <UInt32>]
   [-ComputerName <String[]>]
   [-ClientOnly]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Beschreibung

Das New-CimInstance Cmdlet erstellt eine Instanz einer CIM-Klasse basierend auf der Klassendefinition auf dem lokalen Computer oder einem Remotecomputer. Standardmäßig erstellt das New-CimInstance Cmdlet eine Instanz auf dem lokalen Computer.

Beispiele

Beispiel 1: Erstellen einer Instanz einer CIM-Klasse

In diesem Beispiel wird eine Instanz einer CIM-Klasse namens win32_environment im Root/cimv2-Namespace auf dem Computer erstellt.

New-CimInstance -ClassName Win32_Environment -Property @{Name="testvar";VariableValue="testvalue";UserName="domain\user"}

Es wird keine clientseitige Überprüfung ausgeführt, wenn die Klasse nicht vorhanden ist, die Eigenschaften falsch sind oder der Server den Aufruf ablehnt. Wenn die Instanz erfolgreich erstellt wird, gibt das Cmdlet die neu erstellte Instanz aus.

Beispiel 2: Erstellen einer Instanz einer CIM-Klasse mithilfe eines Klassenschemas

In diesem Beispiel wird ein CIM-Klassenobjekt abgerufen und in einer Variablen mit dem Namen $classgespeichert. Der Inhalt der Variablen wird dann an das New-CimInstance Cmdlet übergeben.

$class = Get-CimClass -ClassName Win32_Environment
New-CimInstance -CimClass $class -Property @{Name="testvar";VariableValue="testvalue";UserName="Contoso\User1"}

Beispiel 3: Erstellen einer dynamischen Instanz auf dem Client

In diesem Beispiel wird eine dynamische Instanz einer CIM-Klasse namens Win32_Process auf dem Clientcomputer erstellt, ohne die Instanz vom Server zu erhalten. Die neue Instanz wird in der Variablen $agespeichert. Diese dynamische Instanz kann verwendet werden, um Vorgänge auszuführen, wenn die Instanz mit diesem Schlüssel auf dem Server vorhanden ist.

$a = New-CimInstance -ClassName Win32_Process -Property @{Handle=0} -Key Handle -ClientOnly
Get-CimInstance -CimInstance $a
Invoke-CimMethod -CimInstance $a -MethodName GetOwner

ProcessId Name                HandleCount WorkingSetSize VirtualSize
--------- ----                ----------- -------------- -----------
0         System Idle Process 0           8192           8192

Domain         :
ReturnValue    : 2
User           :
PSComputerName :

Das Get-CimInstance Cmdlet ruft dann eine bestimmte einzelne Instanz ab. Das Invoke-CimMethod Cmdlet ruft die GetOwner-Methode für die abgerufene Instanz auf.

Beispiel 4: Erstellen einer Instanz für eine CIM-Klasse eines bestimmten Namespaces

In diesem Beispiel wird eine Instanz einer CIM-Klasse mit dem Namen MSFT_Something im Namespacestamm /an einer beliebigen Stelle und in einer Variablen namens $classgespeichert. Die Variable wird an das New-CimInstance Cmdlet übergeben, um eine neue CIM-Instanz zu erstellen und clientseitige Überprüfungen für die neue Instanz auszuführen.

$class = Get-CimClass -ClassName MSFT_Something -Namespace root/somewhere
New-CimInstance -CimClass $class -Property @{"Prop1"=1;"Prop2"="value"} -ClientOnly

In diesem Beispiel wird durch Verwenden des CimClass-Parameters anstelle des Parameters "ClassName" überprüft, ob Prop1 und Prop2 tatsächlich vorhanden sind und dass die Schlüssel richtig gekennzeichnet sind.

Sie können den Parameter ComputerName oder CimSession nicht mit dem Parameter "ClientOnly " verwenden.

Parameter

-CimClass

Gibt ein CIM-Klassenobjekt an, das den Typ der Instanz darstellt. Verwenden Sie das Get-CimClass Cmdlet, um die Klassendeklaration von einem Computer abzurufen. Die Verwendung dieses Parameters führt zu besseren clientseitigen Schemaüberprüfungen.

Type:CimClass
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-CimSession

Führt den Befehl mithilfe der angegebenen CIM-Sitzung aus. Geben Sie eine Variable ein, die die CIM-Sitzung enthält, oder einen Befehl, der die CIM-Sitzung erstellt oder abruft, z. B. die New-CimSession Oder Get-CimSession Cmdlets. Weitere Informationen finden Sie unter about_CimSession.

Type:CimSession[]
Position:Named
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-ClassName

Gibt den Namen der CIM-Klasse an, von der der Vorgang eine Instanz erstellt. HINWEIS: Sie können den Tabstoppabschluss verwenden, um die Liste der Klassen zu durchsuchen, da PowerShell eine Liste von Klassen vom lokalen WMI-Server abruft, um eine Liste der Klassennamen bereitzustellen.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-ClientOnly

Gibt an, dass die Instanz nur in PowerShell erstellt wird, ohne zum CIM-Server zu wechseln. Sie können diesen Parameter verwenden, um eine CIM-Instanz im Arbeitsspeicher für die Verwendung in nachfolgenden PowerShell-Vorgängen zu erstellen.

Type:SwitchParameter
Aliases:Local
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ComputerName

Gibt den Namen des Computers an, auf dem Der CIM-Vorgang ausgeführt werden soll. Sie können einen vollqualifizierten Do Standard namen (FQDN), einen NetBIOS-Namen oder eine IP-Adresse angeben.

Wenn Sie diesen Parameter angeben, erstellt das Cmdlet mithilfe des WSMan-Protokolls eine temporäre Sitzung auf dem angegebenen Computer.

Wenn Sie diesen Parameter nicht angeben, führt das Cmdlet den Vorgang auf dem lokalen Computer mithilfe des Component Object Model (COM) aus.

Wenn mehrere Vorgänge auf demselben Computer ausgeführt werden, bietet die Verbindung mit einer CIM-Sitzung eine bessere Leistung.

Type:String[]
Aliases:CN, ServerName
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Confirm

Hiermit werden Sie vor der Ausführung des Cmdlets zur Bestätigung aufgefordert.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Key

Gibt die Eigenschaften an, die als Schlüssel verwendet werden. CimSession und ComputerName können nicht verwendet werden, wenn Key angegeben wird.

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Namespace

Gibt den Namespace der Klasse für die neue Instanz an. Der Standardnamespace ist root/cimv2. Sie können die Registerkartenabschluss verwenden, um die Liste der Namespaces zu durchsuchen, da PowerShell eine Liste von Namespaces vom lokalen WMI-Server abruft, um die Liste der Namespaces bereitzustellen.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-OperationTimeoutSec

Gibt die Zeitspanne an, die das Cmdlet auf eine Antwort vom CIM-Server wartet. Standardmäßig ist der Wert dieses Parameters 0, was bedeutet, dass das Cmdlet den Standardtimeoutwert für den Server verwendet. Wenn der Parameter OperationTimeoutSec auf einen Wert festgelegt ist, der kleiner als das robuste Verbindungsretrytimeout von 3 Minuten ist, können Netzwerkfehler, die mehr als der Wert des OperationTimeoutSec-Parameters dauern, nicht wiederhergestellt werden, da der Vorgang auf dem Server zu einem Timeout vor dem erneuten Herstellen der Verbindung führen kann.

Type:UInt32
Aliases:OT
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Property

Gibt die Eigenschaften der CIM-Instanz mithilfe einer Hashtabelle (Name-Wert-Paare) an.

Wenn Sie den CimClass-Parameter angeben, führt das New-CimInstance Cmdlet eine Eigenschaftsprüfung auf dem Client aus, um sicherzustellen, dass die angegebenen Eigenschaften mit der Klassendeklaration auf dem Server konsistent sind. Wenn der CimClass-Parameter nicht angegeben ist, erfolgt die Eigenschaftenüberprüfung auf dem Server.

Type:IDictionary
Aliases:Arguments
Position:1
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-ResourceUri

Gibt den URI (Uniform Resource Identifier) der Ressourcenklasse oder -instanz an. Der URI wird verwendet, um einen bestimmten Ressourcentyp auf einem Computer zu identifizieren, z. B. Datenträger oder Prozesse.

Ein URI besteht aus einem Präfix und einem Pfad zu einer Ressource. Zum Beispiel:

http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_LogicalDisk

http://intel.com/wbem/wscim/1/amt-schema/1/AMT_GeneralSettings

Wenn Sie diesen Parameter nicht angeben, wird standardmäßig der DMTF-Standardressourcen-URI http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/ verwendet, und der Klassenname wird an ihn angefügt.

ResourceURI kann nur mit CIM-Sitzungen verwendet werden, die mit dem WSMan-Protokoll erstellt wurden, oder beim Angeben des ComputerName-Parameters , der eine CIM-Sitzung mit WSMan erstellt. Wenn Sie diesen Parameter ohne Angabe des ComputersName-Parameters angeben oder eine MIT DCOM-Protokoll erstellte CIM-Sitzung angeben, wird ein Fehler angezeigt, da das DCOM-Protokoll den ResourceURI-Parameter nicht unterstützt.

Wenn sowohl der Parameter "ResourceUri" als auch der Parameter "Filter" angegeben werden, wird der Parameter "Filter" ignoriert.

Type:Uri
Position:Named
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-WhatIf

Zeigt, was geschieht, wenn das Cmdlet ausgeführt wird. Das Cmdlet wird nicht ausgeführt.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Eingaben

None

Sie können keine Objekte an dieses Cmdlet weiterleiten.

Ausgaben

Object

Dieses Cmdlet gibt ein Objekt zurück, das die CIM-Instanzinformationen enthält.