From 16f8765562432df362826be486512e403e373975 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 7 Feb 2026 10:50:42 +0000
Subject: [PATCH] Add Test-MqttConnection and Show-MqttExamples cmdlets, update
 documentation

Co-authored-by: chkr1011 <6939810+chkr1011@users.noreply.github.com>
---
 .../Cmdlets/ShowMqttExamplesCmdlet.cs         | 78 +++++++++++++++++++
 .../Cmdlets/TestMqttConnectionCmdlet.cs       | 41 ++++++++++
 Source/MQTTnet.PowerShell/README.md           | 21 +++++
 Source/MQTTnet.PowerShell/SmokeTest.ps1       | 10 ++-
 4 files changed, 149 insertions(+), 1 deletion(-)
 create mode 100644 Source/MQTTnet.PowerShell/Cmdlets/ShowMqttExamplesCmdlet.cs
 create mode 100644 Source/MQTTnet.PowerShell/Cmdlets/TestMqttConnectionCmdlet.cs

diff --git a/Source/MQTTnet.PowerShell/Cmdlets/ShowMqttExamplesCmdlet.cs b/Source/MQTTnet.PowerShell/Cmdlets/ShowMqttExamplesCmdlet.cs
new file mode 100644
index 00000000..8a526f08
--- /dev/null
+++ b/Source/MQTTnet.PowerShell/Cmdlets/ShowMqttExamplesCmdlet.cs
@@ -0,0 +1,78 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Management.Automation;
+
+namespace MQTTnet.PowerShell.Cmdlets;
+
+[Cmdlet(VerbsCommon.Show, "MqttExamples")]
+public class ShowMqttExamplesCmdlet : PSCmdlet
+{
+    protected override void ProcessRecord()
+    {
+        var examples = @"
+MQTTnet PowerShell Module - Quick Examples
+==========================================
+
+1. Basic Connection and Publish:
+   $session = New-MqttSession
+   Connect-MqttSession -Session $session -Host 'broker.hivemq.com'
+   Publish-MqttMessage -Session $session -Topic 'test/topic' -Payload 'Hello'
+   Disconnect-MqttSession -Session $session
+   Remove-MqttSession -Session $session
+
+2. Subscribe and Receive Messages:
+   $session = New-MqttSession
+   Connect-MqttSession -Session $session -Host 'broker.hivemq.com'
+   Subscribe-MqttTopic -Session $session -Topic 'test/demo'
+   $msg = Receive-MqttMessage -Session $session -TimeoutSeconds 30
+   Write-Host ""Received: $($msg.Payload)""
+
+3. WebSocket Connection:
+   $session = New-MqttSession
+   Connect-MqttSession -Session $session -WebSocketUri 'broker.hivemq.com:8000/mqtt'
+   Publish-MqttMessage -Session $session -Topic 'test/ws' -Payload 'Hello WS'
+
+4. TLS/SSL Connection:
+   $session = New-MqttSession
+   Connect-MqttSession -Session $session -Host 'broker.hivemq.com' -Port 8883 `
+       -UseTls -AllowUntrustedCertificates
+
+5. Async Message Handler:
+   $session = New-MqttSession
+   Connect-MqttSession -Session $session -Host 'broker.hivemq.com'
+   Subscribe-MqttTopic -Session $session -Topic 'test/#'
+   Register-MqttMessageHandler -Session $session -Action {
+       param($topic, $payload, $message)
+       Write-Host ""Message on $topic : $payload""
+   }
+
+6. Last Will and Testament:
+   $session = New-MqttSession
+   Connect-MqttSession -Session $session -Host 'broker.hivemq.com' `
+       -WillTopic 'status/client' -WillPayload 'Offline' -WillQoS 1 -WillRetain
+
+7. Publish with User Properties:
+   $props = @{ 'source' = 'PowerShell'; 'version' = '1.0' }
+   Publish-MqttMessage -Session $session -Topic 'test/props' `
+       -Payload 'Data' -UserProperties $props
+
+8. High QoS Publishing:
+   Publish-MqttMessage -Session $session -Topic 'critical/data' `
+       -Payload 'Important' -QoS 2
+
+9. Test Connection:
+   $isAlive = Test-MqttConnection -Session $session
+   Write-Host ""Connection alive: $isAlive""
+
+10. Get Session Status:
+    $status = Get-MqttSessionStatus -Session $session
+    Write-Host ""Connected: $($status.IsConnected)""
+
+For more details, see: Source/MQTTnet.PowerShell/README.md
+";
+        
+        WriteObject(examples);
+    }
+}
diff --git a/Source/MQTTnet.PowerShell/Cmdlets/TestMqttConnectionCmdlet.cs b/Source/MQTTnet.PowerShell/Cmdlets/TestMqttConnectionCmdlet.cs
new file mode 100644
index 00000000..8014d5a4
--- /dev/null
+++ b/Source/MQTTnet.PowerShell/Cmdlets/TestMqttConnectionCmdlet.cs
@@ -0,0 +1,41 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Management.Automation;
+
+namespace MQTTnet.PowerShell.Cmdlets;
+
+[Cmdlet(VerbsDiagnostic.Test, "MqttConnection")]
+[OutputType(typeof(bool))]
+public class TestMqttConnectionCmdlet : PSCmdlet
+{
+    [Parameter(Mandatory = true, ValueFromPipeline = true)]
+    public required PsMqttSession Session { get; set; }
+
+    [Parameter]
+    public int TimeoutSeconds { get; set; } = 5;
+
+    protected override void ProcessRecord()
+    {
+        try
+        {
+            var client = Session.GetClient();
+            
+            if (!client.IsConnected)
+            {
+                WriteObject(false);
+                return;
+            }
+
+            var cts = new CancellationTokenSource(TimeSpan.FromSeconds(TimeoutSeconds));
+            client.PingAsync(cts.Token).GetAwaiter().GetResult();
+            
+            WriteObject(true);
+        }
+        catch
+        {
+            WriteObject(false);
+        }
+    }
+}
diff --git a/Source/MQTTnet.PowerShell/README.md b/Source/MQTTnet.PowerShell/README.md
index 3b7fd238..6e087219 100644
--- a/Source/MQTTnet.PowerShell/README.md
+++ b/Source/MQTTnet.PowerShell/README.md
@@ -88,6 +88,15 @@ Remove-MqttSession -Session $session
 
 ## Available Cmdlets
 
+### Help and Examples
+
+#### Show-MqttExamples
+Displays quick examples for common MQTT tasks.
+
+```powershell
+Show-MqttExamples
+```
+
 ### Session Management
 
 #### New-MqttSession
@@ -174,6 +183,18 @@ Disposes the MQTT session and releases resources.
 Remove-MqttSession -Session $session
 ```
 
+#### Test-MqttConnection
+Tests if the MQTT connection is alive by sending a PING packet.
+
+```powershell
+$isAlive = Test-MqttConnection -Session $session -TimeoutSeconds 5
+Write-Host "Connection is alive: $isAlive"
+```
+
+**Parameters:**
+- `Session`: The MQTT session (mandatory)
+- `TimeoutSeconds`: Timeout for the ping operation (default: 5)
+
 ### Publishing
 
 #### Publish-MqttMessage
diff --git a/Source/MQTTnet.PowerShell/SmokeTest.ps1 b/Source/MQTTnet.PowerShell/SmokeTest.ps1
index 3b642b9a..6bc04998 100644
--- a/Source/MQTTnet.PowerShell/SmokeTest.ps1
+++ b/Source/MQTTnet.PowerShell/SmokeTest.ps1
@@ -1,5 +1,5 @@
 # Quick smoke test for MQTTnet PowerShell Module
-Import-Module ./bin/Debug/net8.0/MQTTnet.PowerShell.dll
+Import-Module ./bin/Debug/net8.0/MQTTnet.PowerShell.dll -WarningAction SilentlyContinue
 
 Write-Host "Testing module load..." -ForegroundColor Yellow
 $commands = Get-Command -Module MQTTnet.PowerShell
@@ -10,6 +10,14 @@ Write-Host "`nTesting session creation..." -ForegroundColor Yellow
 $session = New-MqttSession
 Write-Host "Session created successfully!" -ForegroundColor Green
 
+Write-Host "`nTesting Show-MqttExamples..." -ForegroundColor Yellow
+$examples = Show-MqttExamples
+if ($examples) {
+    Write-Host "Examples retrieved successfully!" -ForegroundColor Green
+} else {
+    Write-Host "Failed to retrieve examples!" -ForegroundColor Red
+}
+
 Write-Host "`nTesting session cleanup..." -ForegroundColor Yellow
 Remove-MqttSession -Session $session
 Write-Host "Session removed successfully!" -ForegroundColor Green