MQTTnet/Source/MQTTnet.PowerShell/IMPLEMENTATION.md

PowerShell Module Extension - Implementation Summary

Overview

This implementation extends the PowerShell support for the MQTTnet library as requested in issue #2215, implementing the proposal described in the ticket comments and exposing additional features of the library as PowerShell cmdlets.

Changes Implemented

1. Enhanced RegisterMqttMessageHandler (Primary Requirement from #2215)

File: Source/MQTTnet.PowerShell/Cmdlets/RegisterMqttMessageHandlerCmdlet.cs

Implemented the proposal from the issue comment by @ArakniD:

• Proper ScriptBlock execution in the correct runspace
• Asynchronous message handling using Task.Run to avoid blocking
• Passes three parameters to the handler: topic (string), payload (string), and full message object
• Proper error handling with try-catch and error output to host
• Captures the runspace during cmdlet execution and restores it during handler execution

Usage Example:

Register-MqttMessageHandler -Session $session -Action {
    param($topic, $payload, $message)
    Write-Host "Received on $topic: $payload"
    # Can access $message.QoS, $message.Retain, etc.
}

2. Enhanced Connection Options

File: Source/MQTTnet.PowerShell/Cmdlets/ConnectMqttSessionCmdlet.cs

Extended Connect-MqttSession with:

• WebSocket Support: New -WebSocketUri parameter for WebSocket connections
• TLS/SSL Support: New -UseTls and -AllowUntrustedCertificates parameters
• Last Will and Testament: Parameters for -WillTopic, -WillPayload, -WillQoS, -WillRetain
• Connection Tuning: Parameters for -KeepAlivePeriod and -Timeout
• Parameter Sets: Organized into TCP, TcpWithTls, and WebSocket parameter sets

Usage Examples:

# TCP with TLS
Connect-MqttSession -Session $session -Host "broker.com" -Port 8883 -UseTls

# WebSocket
Connect-MqttSession -Session $session -WebSocketUri "ws://broker.com:8000/mqtt"

# With Last Will
Connect-MqttSession -Session $session -Host "broker.com" `
    -WillTopic "status" -WillPayload "Offline" -WillRetain

3. Enhanced Publishing

File: Source/MQTTnet.PowerShell/Cmdlets/PublishMqttMessageCmdlet.cs

Added support for:

• User Properties: New -UserProperties parameter accepting a Hashtable
• MQTT 5 features already supported: ContentType, ResponseTopic, TopicAlias, MessageExpiryInterval

Usage Example:

$props = @{ "source" = "PowerShell"; "version" = "1.0" }
Publish-MqttMessage -Session $session -Topic "data" -Payload "test" -UserProperties $props

4. New Utility Cmdlets

Get-MqttSessionStatus

File: Source/MQTTnet.PowerShell/Cmdlets/GetMqttSessionStatusCmdlet.cs

Returns connection status information.

$status = Get-MqttSessionStatus -Session $session
Write-Host "Connected: $($status.IsConnected)"

Test-MqttConnection

File: Source/MQTTnet.PowerShell/Cmdlets/TestMqttConnectionCmdlet.cs

Pings the broker to verify connectivity.

$isAlive = Test-MqttConnection -Session $session -TimeoutSeconds 5

Unregister-MqttMessageHandler

File: Source/MQTTnet.PowerShell/Cmdlets/UnregisterMqttMessageHandlerCmdlet.cs

Clears all registered message handlers.

Unregister-MqttMessageHandler -Session $session

Show-MqttExamples

File: Source/MQTTnet.PowerShell/Cmdlets/ShowMqttExamplesCmdlet.cs

Displays quick reference examples for common MQTT tasks.

Show-MqttExamples

5. Enhanced PsMqttSession Class

File: Source/MQTTnet.PowerShell/PsMqttSession.cs

Added:

• ClearMessageHandlers() method to remove all event handlers
• Improved event handling infrastructure

6. Documentation

Files:

• Source/MQTTnet.PowerShell/README.md (new)
• Source/MQTTnet.PowerShell/Test.ps1 (updated)
• Source/MQTTnet.PowerShell/SmokeTest.ps1 (new)

Created comprehensive documentation including:

• Quick start guide
• Detailed cmdlet documentation
• Parameter descriptions
• Usage examples for all features
• Advanced scenarios (request-response, error handling)
• Tips and best practices
• Smoke tests for validation

Complete Cmdlet List (13 Total)

1. New-MqttSession - Create MQTT session
2. Connect-MqttSession - Connect with TCP/WebSocket/TLS support
3. Disconnect-MqttSession - Clean disconnect
4. Remove-MqttSession - Cleanup resources
5. Get-MqttSessionStatus - Check connection status
6. Test-MqttConnection - Ping broker
7. Publish-MqttMessage - Publish with advanced features
8. Subscribe-MqttTopic - Subscribe to topics
9. Unsubscribe-MqttTopic - Unsubscribe from topics
10. Receive-MqttMessage - Synchronous message receive
11. Register-MqttMessageHandler - Async message handling ⭐ (Primary requirement)
12. Unregister-MqttMessageHandler - Clear handlers
13. Show-MqttExamples - Quick reference examples

Testing

Build Status

✅ PowerShell module builds successfully ✅ No compilation errors or warnings ✅ Code passes CodeQL security analysis (0 alerts)

Smoke Tests

✅ All 13 cmdlets load correctly ✅ Session creation and disposal works ✅ Show-MqttExamples returns help text ✅ No runtime errors during basic operations

Test Files

• SmokeTest.ps1: Quick validation of module loading and basic operations
• Test.ps1: Comprehensive examples demonstrating all features

Features Not Implemented (Out of Scope)

The following were considered but determined to be out of scope for this task:

• MQTT broker/server cmdlets (only client features were requested)
• Managed MQTT client wrapper (existing client is sufficient)
• RPC extension support (specialized use case)
• File-based certificate handling cmdlets (can be done with existing .NET capabilities)

Compatibility

• Requires .NET 8.0 or later
• Requires PowerShell 7.0 or later
• Works on Windows, Linux, and macOS
• Compatible with MQTT 3.1.1 and MQTT 5.0 protocols

Breaking Changes

None. This is a new feature addition that doesn't modify existing code outside the PowerShell module.

Migration Guide

For users who were using the initial implementation from PR #2215:

• The RegisterMqttMessageHandler now actually works! Update your scripts to use the handler.
• Connect-MqttSession now requires explicit parameter sets (-Host for TCP, -WebSocketUri for WebSocket)
• No other breaking changes

Future Enhancements

Potential future improvements that could be added:

1. Pipeline support for batch publishing
2. Managed client wrapper for automatic reconnection
3. Certificate-based authentication helpers
4. MQTT broker cmdlets for running local brokers
5. Performance counters and statistics cmdlets
6. Async/await support for better PowerShell integration

References

• Issue #2215: https://github.com/dotnet/MQTTnet/pull/2215
• Proposal comment by @ArakniD: https://github.com/dotnet/MQTTnet/pull/2215#issuecomment-3594492551
• MQTTnet Documentation: https://github.com/dotnet/MQTTnet