Partager via


SWbemServices, objet

Vous pouvez utiliser les méthodes d’un objet SWbemServices pour effectuer des opérations sur un espace de noms se trouvant sur un hôte local ou sur un hôte distant. Cet objet ne peut pas être créé par l’appel VBScript CreateObject.

Membres

L’objet SWbemServices est doté des types de membres suivants :

Méthodes

L’objet SWbemServices est doté des méthodes suivantes.

Méthode Description
AssociatorsOf Récupère les instances de ressources managées associées à une ressource spécifiée par le biais d’une ou de plusieurs classes d’association. Vous fournissez le chemin de l’objet pour le point de terminaison d’origine, et AssociatorsOf retourne les ressources managées au point de terminaison opposé. La méthode AssociatorsOf exécute la même fonction que la requête WQL « ASSOCIATORS OF ».
AssociatorsOfAsync Retourne de manière asynchrone une collection d’objets (classes ou instances) qui sont associés à un objet spécifié.
Supprimer Supprime une instance d’une ressource managée (ou une définition de classe de l’espace de stockage CIM).
DeleteAsync Supprime de manière asynchrone la classe ou l’instance spécifiées dans le chemin de l’objet.
ExecMethod Fournit un autre moyen d’exécuter une méthode définie par une définition de classe de ressource managée. Principalement utilisée dans des situations où le langage de script ne prend pas en charge les paramètres sortants. Par exemple, JScript ne prend pas en charge les paramètres de sortie.
ExecMethodAsync Exécute de manière asynchrone une méthode qui est exportée par un fournisseur de méthode.
ExecNotificationQuery Exécute une requête d’abonnement aux événements pour recevoir des événements. Une requête d’abonnement aux événements est une requête qui définit un changement apporté à l’environnement géré que vous voulez superviser. Lorsque le changement se produit, l’infrastructure WMI fournit un événement décrivant le changement apporté au script appelant.
ExecNotificationQueryAsync Exécute de manière asynchrone une requête pour recevoir des événements.
ExecQuery Exécute une requête pour récupérer une collection d’instances de ressources (ou de définitions de classe) gérées par WMI. ExecQuery peut être utilisée pour récupérer une collection filtrée d’instances qui correspondent aux critères que vous définissez dans la requête passée à ExecQuery.
ExecQueryAsync Exécute de manière asynchrone une requête pour récupérer des objets.
Obtenir Récupère une seule instance d’une ressource (ou d’une définition de classe) managée en fonction du chemin d’un objet.
GetAsync Récupère de manière asynchrone un objet, qui est une définition de classe ou une instance, en fonction du chemin de l’objet.
InstancesOf Récupère toutes les instances d’une ressource managée en fonction d’un nom de classe. Par défaut, InstancesOf effectue une importante récupération. Autrement dit, InstancesOf récupère les instances de la ressource identifiée par le nom de classe passé à la méthode et récupère également toutes les instances de toutes les ressources qui sont des sous-classes (définies en dessous) de la classe cible.
InstancesOfAsync Retourne de manière asynchrone les instances d’une classe spécifiée en fonction des critères de sélection spécifiés par l’utilisateur.
ReferencesTo Retourne toutes les associations qui font référence à une ressource spécifiée. La meilleure façon de comprendre ReferencesTo consiste à le comparer à la méthode AssociatorsOf. AssociatorsOf retourne les ressources dynamiques qui se trouvent à l’autre extrémité d’une association. ReferencesTo retourne l’association elle-même. La méthode ReferencesTo remplit la même fonction que la requête WQL « REFERENCES OF ».
ReferencesToAsync Retourne de manière asynchrone une collection de toutes les classes ou instances d’association qui font référence à une classe ou instance spécifique.
SubclassesOf Récupère toutes les sous-classes d’une classe spécifiée à partir de l’espace de stockage CIM.
SubclassesOfAsync Retourne de manière asynchrone une collection de sous-classes pour une classe spécifiée.

Propriétés

L’objet SWbemServices est doté des propriétés suivantes.

Propriété Type d’accès Description
Security_
Lecture seule
Utilisée pour obtenir ou définir les paramètres de sécurité d’un objet SWbemServices.

Notes

Les méthodes peuvent être appelées en mode synchrone, en mode asynchrone ou en mode semi-synchrone. Pour plus d’informations, consultez Appeler une méthode.

Vue d’ensemble

SWbemServices remplit deux rôles principaux. Tout d’abord, l’objet SWbemServices représente une connexion authentifiée à un espace de noms WMI sur un ordinateur cible. Ensuite, SWbemServices est l’objet Automation que vous utilisez pour récupérer des ressources gérées par WMI. Vous pouvez obtenir une référence à un objet SWbemServices de deux manières différentes :

  • Comme illustré dans la plupart des scripts WMI présentés jusqu’à présent, vous pouvez utiliser la fonction VBScript GetObject en association avec le moniker WMI « winmgmts: ». L’exemple suivant est la forme la plus simple d’une connexion WMI. L’exemple se connecte à l’espace de noms par défaut (généralement « Root\CIMv2 ») sur l’ordinateur local :

    Set objSWbemServices = GetObject("winmgmts:")

  • Vous pouvez également utiliser la méthode ConnectServer de l’objet SWbemLocator pour obtenir une référence à un objet SWbemServices.

Après avoir obtenu une référence à un objet SWbemServices, vous utilisez la référence de l’objet pour appeler une des 18 méthodes disponibles à l’aide de SWbemServices. SWbemServices peut retourner l’un des trois différents objets de bibliothèque de scripts WMI (SWbemObjectSet, SWbemObject ou SWbemEventSource), selon la méthode que vous appelez. Le fait de connaître le type d’objet retourné par chaque méthode vous aide à déterminer l’étape suivante que votre script doit effectuer. Par exemple, si vous récupérez un SWbemObjectSet, vous devez énumérer la collection pour accéder à chaque SWbemObject qu’elle contient. Si vous récupérez un SWbemObject, vous pouvez accéder immédiatement aux méthodes et propriétés d’objet sans énumérer au préalable la collection.

Modes de fonctionnement

SWbemServices prend en charge trois modes de fonctionnement : synchrone, asynchrone et semi-synchrone.

  • Synchronous. En mode synchrone, votre script se bloque (s’interrompt) jusqu’à ce que la méthode SWbemServices se termine. Non seulement votre script attend, mais dans les cas où WMI récupère des instances de ressources managées, WMI génère l’intégralité de SWbemObjectSet en mémoire avant que le premier octet de données ne soit retourné au script appelant. Cela peut avoir un effet négatif sur les performances du script et sur l’ordinateur exécutant le script. Par exemple, la récupération synchrone de milliers d’événements à partir des journaux d’événements Windows peut prendre beaucoup de temps et utiliser beaucoup de mémoire. C’est pour ces raisons que les opérations synchrones ne sont pas recommandées excepté pour les trois méthodes (Delete, ExecMethod et Get) qui sont synchrones par défaut. Ces méthodes ne retournent pas des jeux de données volumineux. Une opération semi-synchrone n’est donc pas nécessaire.

  • Asynchrone. En mode asynchrone, votre script appelle l’une des neuf méthodes asynchrones et génère immédiatement un retour. Autrement dit, dès que la méthode asynchrone est appelée, votre script reprend l’exécution de la ligne de code suivante. Pour utiliser une méthode asynchrone, votre script doit d’abord créer un objet SWbemSink et une sous-routine spéciale appelée par le gestionnaire d’événements. WMI effectue l’opération asynchrone et avertit le script en appelant la sous-routine du gestionnaire d’événements une fois l’opération terminée.

  • Semi-synchrone. Le mode semi-synchrone est un compromis entre le mode synchrone et le mode asynchrone. Les opérations semi-synchrones offrent de meilleures performances que les opérations synchrones. Néanmoins, elles ne nécessitent pas les connaissances supplémentaires et les étapes de script nécessaires pour gérer les opérations asynchrones. Il s’agit du type d’opération par défaut pour la plupart des requêtes WMI.

    En mode semi-synchrone, votre script appelle l’une des six méthodes d’extraction de données et génère immédiatement un retour. WMI récupère les ressources managées en arrière-plan à mesure que votre script continue de s’exécuter. Lorsque les ressources sont récupérées, elles sont immédiatement retournées à votre script par le biais d’un SWbemObjectSet. Vous pouvez commencer à accéder aux ressources managées sans attendre que l’intégralité de la collection soit assemblée.

    Il existe une mise en garde aux opérations semi-synchrones lorsque vous travaillez avec des ressources managées qui comprennent de nombreuses instances (à savoir plus de 1 000), comme CIM_DataFile et Win32_NTLogEvent. Cette mise en garde est liée à la façon dont WMI gère les instances de ressources managées. Pour chaque instance d’une ressource managée, WMI crée et met en cache un objet SWbemObject. Lorsqu’il existe un grand nombre d’instances pour une ressource managée, la récupération des instances peut monopoliser les ressources disponibles, ce qui réduit les performances du script et de l’ordinateur.

    Pour contourner le problème, vous pouvez optimiser les appels de méthode semi-synchrones à l’aide de l’indicateur wbemFlagForwardOnly. L’indicateur wbemFlagForwardOnly, combiné à l’indicateur wbemFlagReturnImmediately (l’indicateur semi-synchrone par défaut), indique à WMI de retourner un SWbemObjectSet vers l’avant uniquement, ce qui élimine le problème de performances d’un jeu de données volumineux. Toutefois, l’utilisation de l’indicateur wbemFlagForwardOnly s’accompagne d’un coût. Un SWbemObjectSet vers l’avant uniquement ne peut être énuméré qu’une seule fois. Une fois que chaque SWbemObject d’un SWbemObjectSet a fait l’objet d’accès, la mémoire allouée à l’instance est libérée.

À l’exception des méthodes Delete, ExecMethod, Get et de neuf asynchrones, le mode semi-synchrone est le mode de fonctionnement par défaut et recommandé.

Méthodes couramment utilisées

Les méthodes le plus souvent utilisées dans les scripts d’administration système sont InstancesOf, ExecQuery, Get et ExecNotificationQuery. Bien que souvent utilisée, InstancesOf n’est pas nécessairement le moyen recommandé pour récupérer des informations (même il s’agit incontestablement du moyen le plus simple).

Spécifications

Condition requise Valeur
Client minimal pris en charge
Windows Vista
Serveur minimal pris en charge
Windows Server 2008
En-tête
Wbemdisp.h
Bibliothèque de types
Wbemdisp.tlb
DLL
Wbemdisp.dll
CLSID
CLSID_SWbemServices
IID
IID_ISWbemServices

Voir aussi

Objets de l’API de script

Appel d’une méthode