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