Partager via


New-CimInstance

Crée une instance CIM.

Syntaxe

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>]

Description

Cette applet de commande est disponible uniquement sur la plateforme Windows.

L’applet de commande New-CimInstance crée une instance d’une classe CIM en fonction de la définition de classe sur l’ordinateur local ou un ordinateur distant. Par défaut, l’applet de commande New-CimInstance crée une instance sur l’ordinateur local.

Exemples

Exemple 1 : Créer une instance d’une classe CIM

Cet exemple crée une instance d’une classe CIM nommée win32_environment dans l’espace de noms racine/cimv2 sur l’ordinateur.

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

Aucune validation côté client n’est effectuée si la classe n’existe pas, les propriétés sont incorrectes ou si le serveur rejette l’appel. Si l’instance est créée avec succès, l’applet de commande génère l’instance nouvellement créée.

Exemple 2 : Créer une instance d’une classe CIM à l’aide d’un schéma de classe

Cet exemple récupère un objet de classe CIM et le stocke dans une variable nommée $class. Le contenu de la variable est ensuite transmis à l’applet de commande New-CimInstance.

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

Exemple 3 : Créer une instance dynamique sur le client

Cet exemple crée une instance dynamique d’une classe CIM nommée Win32_Process sur l’ordinateur client sans obtenir l’instance à partir du serveur. La nouvelle instance est stockée dans la variable $a. Cette instance dynamique peut être utilisée pour effectuer des opérations si l’instance avec cette clé existe sur le serveur.

$instance = @{
    ClassName = 'Win32_Process'
    Property = @{
        Handle = 0
    }
    Key = 'Handle'
    ClientOnly = $true
}
$a = New-CimInstance @instance

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 :

L’applet de commande Get-CimInstance récupère ensuite une instance unique particulière. L’applet de commande Invoke-CimMethod appelle la méthode GetOwner sur l’instance récupérée.

Exemple 4 : Créer une instance pour une classe CIM d’un espace de noms spécifique

Cet exemple obtient une instance d’une classe CIM nommée MSFT_Something dans l’espace de noms racine/quelque part et la stocke dans une variable nommée $class. La variable est transmise à l’applet de commande New-CimInstance pour créer une instance CIM et effectuer des validations côté client sur la nouvelle instance.

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

Dans cet exemple, l’utilisation du paramètre CimClass au lieu du paramètre ClassName valide que Prop1 et Prop2 existent réellement et que les clés sont marquées correctement.

Vous ne pouvez pas utiliser le paramètre ComputerName ou CimSession avec le paramètre ClientOnly.

Paramètres

-CimClass

Spécifie un objet de classe CIM qui représente le type de l’instance. Utilisez l’applet de commande Get-CimClass pour récupérer la déclaration de classe à partir d’un ordinateur. L’utilisation de ce paramètre entraîne de meilleures validations de schéma côté client.

Type:CimClass
Position:0
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:True
Accepter les caractères génériques:False

-CimSession

Exécute la commande à l’aide de la session CIM spécifiée. Entrez une variable qui contient la session CIM, ou une commande qui crée ou obtient la session CIM, telle que les applets de commande New-CimSession ou Get-CimSession. Pour plus d’informations, consultez about_CimSession.

Type:CimSession[]
Position:Named
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:True
Accepter les caractères génériques:False

-ClassName

Spécifie le nom de la classe CIM dont l’opération crée une instance. REMARQUE : Vous pouvez utiliser l’auto-complétion par tabulation pour parcourir la liste des classes, car PowerShell obtient une liste de classes à partir du serveur WMI local pour fournir une liste de noms de classes.

Type:String
Position:0
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:True
Accepter les caractères génériques:False

-ClientOnly

Indique que l’instance est créée uniquement dans PowerShell sans accéder au serveur CIM. Vous pouvez utiliser ce paramètre pour créer une instance CIM en mémoire à utiliser dans les opérations PowerShell suivantes.

Type:SwitchParameter
Alias:Local
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-ComputerName

Spécifie le nom de l’ordinateur sur lequel vous souhaitez exécuter l’opération CIM. Vous pouvez spécifier un nom de domaine complet (FQDN), un nom NetBIOS ou une adresse IP.

Si vous spécifiez ce paramètre, l’applet de commande crée une session temporaire sur l’ordinateur spécifié à l’aide du protocole WSMan.

Si vous ne spécifiez pas ce paramètre, l’applet de commande effectue l’opération sur l’ordinateur local à l’aide du modèle objet de composant (COM).

Si plusieurs opérations sont effectuées sur le même ordinateur, la connexion à l’aide d’une session CIM offre de meilleures performances.

Type:String[]
Alias:CN, ServerName
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:True
Accepter les caractères génériques:False

-Confirm

Vous invite à confirmer avant d’exécuter l’applet de commande.

Type:SwitchParameter
Alias:cf
Position:Named
Valeur par défaut:False
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Key

Spécifie les propriétés utilisées en tant que clés. CimSession et ComputerName ne peuvent pas être utilisés lorsque Key est spécifié.

Type:String[]
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:True
Accepter les caractères génériques:False

-Namespace

Spécifie l’espace de noms de la classe pour la nouvelle instance. L’espace de noms par défaut est root/cimv2. Vous pouvez utiliser la complétion par tabulation pour parcourir la liste des namespaces, car PowerShell récupère la liste des namespaces depuis le serveur WMI local pour la fournir.

Type:String
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:True
Accepter les caractères génériques:False

-OperationTimeoutSec

Spécifie la durée pendant laquelle l’applet de commande attend une réponse du serveur CIM. Par défaut, la valeur de ce paramètre est 0, ce qui signifie que l’applet de commande utilise la valeur de délai d’expiration par défaut pour le serveur. Si le paramètre OperationTimeoutSec est défini sur une valeur inférieure au délai d’attente de nouvelle tentative de connexion robuste de 3 minutes, les échecs réseau qui durent plus que la valeur du paramètre OperationTimeoutSec ne sont pas récupérables, car l’opération sur le serveur expire avant que le client ne puisse se reconnecter.

Type:UInt32
Alias:OT
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Property

Spécifie les propriétés de l’instance CIM à l’aide d’une table de hachage (paires nom-valeur).

Si vous spécifiez le paramètre CimClass , l’applet de commande effectue une validation de propriété sur le client pour vous assurer que les propriétés spécifiées sont cohérentes avec la déclaration de classe sur le serveur. Si le paramètre cimClass n’est pas spécifié, la validation des propriétés est effectuée sur le serveur.

Type:IDictionary
Alias:Arguments
Position:1
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:True
Accepter les caractères génériques:False

-ResourceUri

Spécifie l’URI (Uniform Resource Identifier) de la classe de ressource ou de l’instance. L’URI est utilisé pour identifier un type spécifique de ressource, tel que des disques ou des processus, sur un ordinateur.

Un URI se compose d’un préfixe et d’un chemin d’accès à une ressource. Par exemple:

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

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

Par défaut, si vous ne spécifiez pas ce paramètre, l’URI de ressource standard DMTF http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/ est utilisé et le nom de la classe est ajouté à celui-ci.

ResourceURI ne peut être utilisé qu’avec des sessions CIM créées à l’aide du protocole WSMan ou lors de la spécification du paramètre ComputerName , qui crée une session CIM à l’aide de WSMan. Si vous spécifiez ce paramètre sans spécifier le paramètre ComputerName, ou si vous spécifiez une session CIM créée à l’aide du protocole DCOM, vous obtiendrez une erreur, car le protocole DCOM ne prend pas en charge le paramètre ResourceURI.

Si le paramètre ResourceUri et le paramètre Filter sont spécifiés, le paramètre Filter est ignoré.

Type:Uri
Position:Named
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:True
Accepter les caractères génériques:False

-WhatIf

Affiche ce qui se passerait si l’applet de commande s’exécute. L’applet de commande n’est pas exécutée.

Type:SwitchParameter
Alias:wi
Position:Named
Valeur par défaut:False
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

Entrées

None

Vous ne pouvez pas diriger les objets vers cette applet de commande.

Sorties

CimInstance

Cette applet de commande retourne un objet qui contient les informations d’instance CIM.

Notes

PowerShell inclut les alias suivants pour New-CimInstance:

  • Windows:
    • ncim

Cette applet de commande est disponible uniquement sur les plateformes Windows.