mirror of
https://github.com/dotnet/MQTTnet.git
synced 2026-10-15 00:15:15 +08:00
Add implementation summary documentation
Co-authored-by: chkr1011 <6939810+chkr1011@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
co-authored by
chkr1011
chkr1011
parent
9cf9a714cb
commit
06842366b8
@@ -0,0 +1,197 @@
|
||||
# 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:**
|
||||
```powershell
|
||||
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:**
|
||||
```powershell
|
||||
# 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:**
|
||||
```powershell
|
||||
$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.
|
||||
|
||||
```powershell
|
||||
$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.
|
||||
|
||||
```powershell
|
||||
$isAlive = Test-MqttConnection -Session $session -TimeoutSeconds 5
|
||||
```
|
||||
|
||||
#### Unregister-MqttMessageHandler
|
||||
**File**: `Source/MQTTnet.PowerShell/Cmdlets/UnregisterMqttMessageHandlerCmdlet.cs`
|
||||
|
||||
Clears all registered message handlers.
|
||||
|
||||
```powershell
|
||||
Unregister-MqttMessageHandler -Session $session
|
||||
```
|
||||
|
||||
#### Show-MqttExamples
|
||||
**File**: `Source/MQTTnet.PowerShell/Cmdlets/ShowMqttExamplesCmdlet.cs`
|
||||
|
||||
Displays quick reference examples for common MQTT tasks.
|
||||
|
||||
```powershell
|
||||
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
|
||||
Reference in New Issue
Block a user