New-Event

  • Referência
Módulo:
Microsoft.PowerShell.Utility

Cria um novo evento.

Sintaxe

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

Description

O New-Event cmdlet cria um novo evento personalizado.

Você pode usar eventos personalizados para notificar os usuários sobre as alterações de estado em seu programa e qualquer alteração que seu programa puder detectar, incluindo hardware ou condições do sistema, status de aplicativos, status do disco, status da rede ou a conclusão de um trabalho em segundo plano.

Eventos personalizados são adicionados automaticamente à fila de eventos na sessão sempre que são gerados. Você não precisa se inscrever neles. No entanto, se você quiser encaminhar um evento para a sessão local ou especificar uma ação para responder ao evento, use o Register-EngineEvent cmdlet para assinar o evento personalizado.

Quando você se inscreve em um evento personalizado, o assinante do evento é adicionado à sua sessão. Se você cancelar a assinatura do evento usando o Unregister-Event cmdlet, o assinante do evento e o evento personalizado serão excluídos da sessão. Se você não assinar o evento personalizado, para excluir o evento, deverá alterar as condições do programa ou fechar a sessão do PowerShell.

Exemplos

Exemplo 1: Criar um novo evento na fila de eventos

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

Esse comando cria um novo evento na fila de eventos do PowerShell. Ele usa um objeto Windows.Timer para enviar o evento.

Exemplo 2: Gerar um evento em resposta a outro evento

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)
   }
}

Esta função de exemplo usa o New-Event cmdlet para gerar um evento em resposta a outro evento. O comando usa o Register-ObjectEvent cmdlet para assinar o evento WMI (Instrumentação de Gerenciamento do Windows) que é gerado quando um novo processo é criado. O comando usa o parâmetro Action do cmdlet para chamar o New-Event cmdlet, que cria o novo evento.

Como os eventos gerados New-Event são adicionados automaticamente à fila de eventos do PowerShell, você não precisa se registrar para esse evento.

Parâmetros

-EventArguments

Especifica um objeto que contém opções para o evento.

Tipo:PSObject[]
Cargo:2
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-MessageData

Especifica os dados adicionais associados ao evento. O valor desse parâmetro aparece na propriedade MessageData do objeto de evento.

Tipo:PSObject
Cargo:3
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Sender

Especifica o objeto que gera o evento. O padrão é o mecanismo do PowerShell.

Tipo:PSObject
Cargo:1
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-SourceIdentifier

Especifica um nome para o novo evento. Este parâmetro é obrigatório e deve ser exclusivo na sessão.

O valor desse parâmetro aparece na propriedade SourceIdentifier dos eventos.

Tipo:String
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

Entradas

None

Você não pode canalizar objetos para esse cmdlet.

Saídas

PSEventArgs

Observações

Nenhuma fonte de evento disponível nas plataformas Linux ou macOS.

O novo evento personalizado, a inscrição do evento e a fila de eventos existem apenas na sessão atual. Se você fechar a sessão atual, a fila de eventos será descartada e a inscrição do evento será cancelada.