New-Event

  • Référence
Module:
Microsoft.PowerShell.Utility

Crée un événement.

Syntax

New-Event
   [-SourceIdentifier] <String>
   [[-Sender] <PSObject>]
   [[-EventArguments] <PSObject[]>]
   [[-MessageData] <PSObject>]
   [<CommonParameters>]

Description

L’applet New-Event de commande crée un événement personnalisé.

Vous pouvez utiliser des événements personnalisés pour informer les utilisateurs des changements d'état dans votre programme et de toute modification que votre programme peut détecter, y compris des conditions liées au matériel ou au système, de l'état de l'application, de l'état du disque, de l'état du réseau ou de l'achèvement d'une tâche en arrière-plan.

Les événements personnalisés sont automatiquement ajoutés à la file d'attente des événements dans votre session chaque fois qu'ils sont déclenchés. Vous n'avez pas besoin de vous y abonner. Toutefois, si vous souhaitez transférer un événement à la session locale ou spécifier une action pour répondre à l’événement, utilisez l’applet Register-EngineEvent de commande pour vous abonner à l’événement personnalisé.

Quand vous vous abonnez à un événement personnalisé, l'abonné aux événements est ajouté à votre session. Si vous annulez l’abonnement aux événements à l’aide de l’applet Unregister-Event de commande, l’abonné à l’événement et l’événement personnalisé sont supprimés de la session. Si vous ne vous abonnez pas à l’événement personnalisé, pour supprimer l’événement, vous devez modifier les conditions du programme ou fermer la session PowerShell.

Exemples

Exemple 1 : Créer un événement dans la file d’attente d’événements

PS C:\> New-Event -SourceIdentifier Timer -Sender windows.timer -MessageData "Test"

Cette commande crée un événement dans la file d’attente des événements PowerShell. Il utilise un objet Windows.Timer pour envoyer l’événement.

Exemple 2 : Déclencher un événement en réponse à un autre événement

PS C:\> function Enable-ProcessCreationEvent
{
   $Query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'"
   $ProcessWatcher = New-Object System.Management.ManagementEventWatcher $Query
   $Identifier = "WMI.ProcessCreated"
   Register-ObjectEvent $ProcessWatcher "EventArrived" -SupportEvent $Identifier -Action
   {
      [void] (New-Event -SourceID "PowerShell.ProcessCreated" -Sender $Args[0] -EventArguments $Args[1].SourceEventArgs.NewEvent.TargetInstance)
   }
}

Cet exemple de fonction utilise l’applet New-Event de commande pour déclencher un événement en réponse à un autre événement. La commande utilise l’applet Register-ObjectEvent de commande pour s’abonner à l’événement WMI (Windows Management Instrumentation) déclenché lors de la création d’un nouveau processus. La commande utilise le paramètre Action de l’applet de commande pour appeler l’applet New-Event de commande, ce qui crée l’événement.

Étant donné que les événements qui New-Event déclenchent sont automatiquement ajoutés à la file d’attente d’événements PowerShell, vous n’avez pas besoin de vous inscrire à cet événement.

Paramètres

-EventArguments

Spécifie un objet qui contient des options relatives à l'événement.

Type:PSObject[]
Position:2
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MessageData

Spécifie des données supplémentaires associées à l'événement. La valeur de ce paramètre apparaît dans la propriété MessageData de l’objet événement.

Type:PSObject
Position:3
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Sender

Spécifie l'objet qui déclenche l'événement. La valeur par défaut est le moteur PowerShell.

Type:PSObject
Position:1
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SourceIdentifier

Spécifie un nom pour le nouvel événement. Ce paramètre est obligatoire et il doit être unique dans la session.

La valeur de ce paramètre apparaît dans la propriété SourceIdentifier des événements.

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

Entrées

None

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

Sorties

PSEventArgs

Notes

Aucune source d’événements n’est disponible sur les plateformes Linux ou macOS.

Le nouvel événement personnalisé, l'abonnement aux événements et la file d'attente d'événements existent uniquement dans la session active. Si vous fermez cette session, la file d'attente d'événements est ignorée et l'abonnement aux événements est annulé.