PowerShell Universal
DownloadsIssuesDiscordForums
v4
v4
  • About
  • What's New in v4?
  • Get Started
  • Additional Resources
  • Installation
    • Docker
    • Upgrading
    • Uninstall
  • Licensing
  • System Requirements
  • Supported Browsers
  • Cmdlet Help
  • API
    • About
    • Endpoints
    • Event Hubs
    • Security
    • Error Handling
    • Rate Limiting
  • Automation
    • About Automation
    • Scripts
      • Parameters
    • Jobs
    • Schedules
    • System Events
    • Terminals
    • Triggers
    • Queues
  • User Interfaces
    • About
    • Apps
    • Examples
    • Components
      • Pages
      • Dynamic Regions
      • Element
      • Error Boundary
      • HTML
      • Custom Components
        • Building Custom JavaScript Components
      • Data Display
        • Alert
        • Badge
        • Chip
        • Data Grid
        • Date and Time
        • Icon
        • List
        • Markdown
        • Table
        • Timeline
        • Tooltip
        • Tree View
        • Typography
      • Data Visualization
        • Charts
        • Image
        • Map
      • Feedback
        • Backdrop
        • Modal
        • Progress
        • Skeleton
      • Inputs
        • Autocomplete
        • Button
        • Checkbox
        • Code Editor
        • Date Picker
        • Editor
        • Floating Action Button
        • Form
        • Radio
        • Rating
        • Select
        • Slider
        • Switch
        • Textbox
        • Time Picker
        • Transfer List
        • Upload
      • Navigation
        • Drawer
        • Link
        • Menu
        • Stepper
        • Tabs
      • Layout
        • Grid Layout
        • Grid
        • Hidden
        • Stack
      • Utilities
        • Protect Section
        • Transitions
      • Surfaces
        • AppBar
        • Card
        • Paper
        • Expansion Panel
    • Custom Variable Scopes
    • Interaction
    • Role Based Access
    • Scheduled Endpoints
    • Sessions
    • Themes
      • Cascading Style Sheets
      • Styles
  • Desktop
    • About Desktop Mode
    • File Associations
    • Hotkeys
    • Pages
    • Protocol Handlers
  • Platform
    • Cache
    • Computers
    • Health Checks
    • Middleware
    • Modules
    • Monitoring
    • Notifications
    • Plugins
    • Published Folders
    • Templates
    • Translations
    • User Sessions
    • Variables
  • Configuration
    • About
    • API
    • Command Line Options
    • Environments
    • Feature Flags
    • Git
    • Hosting
      • Azure
      • High Availability
      • IIS
      • Reverse Proxy
    • Login Page
    • Management API
    • Persistence
    • App Settings
    • Security
      • Access Controls
      • App Tokens
      • Client Certificate
      • OpenID Connect
      • PowerShell Protect
      • SAML2
      • WS-Federation
    • Repository
    • Running as a Service Account
    • Best Practices
  • Development
    • Debugging Scripts
    • Editor
    • Hangfire
    • Logging
    • Profiling
    • Visual Studio Code Extension
  • Samples
    • APIs
      • Custom Status Codes
    • Apps
      • Active Directory Tree View
      • Export-CSV Download
      • Dynamic Select Dropdown
      • Textbox Length Validation
      • Tree View Font Size
      • SQL Data Grid
  • Changelogs
    • Changelog
    • Extension Changelog
Powered by GitBook

PowerShell Universal

  • Downloads
  • Pricing
  • Gallery

Community

  • Issues
  • Forums
  • Discord

Support

  • Portal
  • Knowledgebase

Copyright 2025 Ironman Software

On this page
  • Creating an Event Hub
  • Connecting an Event Hub
  • Send Events
  • Receive Data from Clients
  • Event Hub Client Installer
  • eventHubClient.json
  • Options
  • Example: Running Scripts on Remote Machines
  • eventHubClient.json
  • scripts.ps1
  • testEventHub.ps1

Was this helpful?

Edit on GitHub
Export as PDF
  1. API

Event Hubs

Receive client events from the PowerShell Universal server.

Event Hubs provide the ability to connect client to the PowerShell Universal server. Once connected, the PowerShell Universal server can send messages to the connected clients and they will run a local PowerShell script block.

Creating an Event Hub

To create an event hub, click APIs \ Event Hub and click Create New Event Hub. Event Hubs are named and can choose to enforce authentication and authorization.

Connecting an Event Hub

We recommend using the event hub client over the Connect-PSUEventHub cmdlet for persistent connections.

Once created, clients can connect to an event hub using the Connect-PSUEventHub cmdlet found in the Universal module. The cmdlet connects to the hub using a web socket and provides credentials, if necessary. When connecting, specify the -ScriptBlock parameter to define what will happen on the client when an event is received.

Connect-PSUEventHub -ComputerName http://localhost:5000 -Hub 'MyHub' -ScriptBlock {
     Write-Host "Event Received"
}

Objects sent from the hub will be available as $_ or $PSItem.

Connect-PSUEventHub -ComputerName http://localhost:5000 -Hub 'MyHub' -ScriptBlock {
     Write-Host $_
}

Send Events

From within the PowerShell Universal server, you can send events from a hub to connected clients using the Send-PSUEvent cmdlet.

Send-PSUEvent -Hub 'MyHub' -Data "Hello!"

The -Data parameter accepts an object and will be serialized using CLIXML and send to the client. The data will be deserialized before passing to the script block.

Receive Data from Clients

As of 4.1, you can now receive data back from clients. This feature is only available when sending data to an individual client, rather than all clients connected to a hub.

$Connection = Get-PSUEventHubConnection | Where-Object UserName -eq 'Admin'
$Result = Send-PSUEvent -Hub 'Hub' -Data 'Say Hello!' -Connectionid $Connection.ConnectionId
Show-UDToast $Result

From the client side, you would return the data from the script block.

Connect-PSUEventHub -Hub 'Hub' -ScriptBlock {
    Write-Host $EventData 
    "Hello!"
}

Event Hub Client Installer

While you can use the Universal module to connect to event hubs, it may not be the most resilient configuration for your environment. The Event Hub Client Installer provides a MSI that installs a Windows services that will connect to event hubs and run scripts.

eventHubClient.json

After installing the MSI, you will need to configure the client by using an eventHubClient.json file. This file should be created in %ProgramData%\PowerShellUniversal. Changes to this file require a restart of the Event Hub Client service.

The installer will not create the folder or file automatically.

This JSON file configures the Event Hub Client to connect to the hub and run scripts when invoked.

{
    "Connections": [
        {
            "Url": "http://localhost:5000",
            "Hub": "eventHub",
            "AppToken": "tokenXyz",
            "ScriptPath": "script.ps1"
        }
    ]
}

Options

The below options can be included in the eventHubClient.json file.

Connections

These are the connections to Event Hubs. Each connection can contain it's own URL, hub, authentication and script to execute.

Url

The URL of the PowerShell Universal service.

Hub

The name of the Event Hub.

AppToken

The app token used to authentication against the hub.

UseDefaultCredentials

Windows Authentication will be used to authenticate against the hub.

ScriptPath

The script to execute when an event is received. This script is read into memory and not from disk. Variables such as $PSScriptRoot are currently not supported.

Example: Running Scripts on Remote Machines

This example provides a way to run scripts on remote machines without having to install another instance of PowerShell Universal.

This example allows for sending scripts to remote machines and executing them with a generic event hub script.

First, create an event hub in PowerShell Universal. This example does not use authentication.

eventHubClient.json

Next, install the Event Hub Client on the remote machine. Create a configuration file in %ProgramData%\PowerShellUniversal\eventHubClient.json.

{
    "Connections": [
        {
            "Url": "http://localhost:5000",
            "Hub": "eventHub",
            "ScriptPath": "script.ps1"
        }
    ]
}

scripts.ps1

Next, create a helper script.ps1 to receive the event hub data and process requests from PSU to invoke scripts. It creates a new scriptblock and uses the $EventData passed down from the event hub message with the .Contents and .Parameters for the script.

Write-Host $EventData.Hello
$scriptBlock = [Scriptblock]::Create($EventData.Contents)
$Parameters = $EventData.Parameters
& $scriptBlock @Parameters

testEventHub.ps1

In PowerShell Universal, add an automation script testEventHub.ps1.

This script will send the event down to the client. This could be from an API or an App as well. It uses Get-PSUEventHubConnection to get the target computer’s connection ID and then sends an event with the contents of a script and any parameters for that script. The script on event hub side is generic and it will just run whatever is passed to it. Note: -Data maps to $EventData on the client.

param($TargetComputer, $ProcessName)

$scriptBlock = {
    param($Name)
    Start-Process $Name
}

$Connection = Get-PSUEventHubConnection | Where-Object { $_.Computer -eq $TargetComputer -and -not $_.Disconnected } | Select-Object -First 1

Send-PSUEvent -Hub eventHub -ConnectionId $Connection.ConnectionId -Data @{
    Contents = $scriptBlock.ToString() # This will populate $EventData.Contents in the clients script.ps1.
    Parameters = @{
        Name = $ProcessName
    } # This will populate $EventData.Parameters in the clients script.ps1.
    Hello = "Client!" # Having some fun.
}

Another way to populate the .Contents is by using a script file to get code from.

    Contents = Get-Content StartAProcess.ps1 -Raw

From here you could event use the script to schedule jobs to run on the remote machines using the event hub client.

PreviousEndpointsNextSecurity

Last updated 6 months ago

Was this helpful?