From afa1115d968f5c4517abea17d081da99fe0e5500 Mon Sep 17 00:00:00 2001 From: Peter Giacomo Lombardo Date: Mon, 15 Jan 2024 14:47:16 +0100 Subject: [PATCH] Documentation Additions (#119) --- .../docs/how-to/allow-invalid-certs.md | 7 +++++ .../docs/how-to/client-certificates.md | 8 ++++++ .../docs/how-to/configure-logging.md | 6 ++++- .../docs/how-to/connect-with-auth.md | 8 ++++++ Documentation/docs/how-to/publish.md | 7 ++--- Documentation/docs/how-to/set-lwt.md | 27 ++++++++++--------- Documentation/docs/how-to/subscribe-multi.md | 5 ++++ Documentation/docs/how-to/wait-on-event.md | 6 +++++ 8 files changed, 58 insertions(+), 16 deletions(-) diff --git a/Documentation/docs/how-to/allow-invalid-certs.md b/Documentation/docs/how-to/allow-invalid-certs.md index d7c34952..acf80564 100644 --- a/Documentation/docs/how-to/allow-invalid-certs.md +++ b/Documentation/docs/how-to/allow-invalid-certs.md @@ -13,3 +13,10 @@ var options = new HiveMQClientOptionsBuilder() var client = new HiveMQClient(options); var connectResult = await client.ConnectAsync().ConfigureAwait(false); ``` + +## See Also + +* [HiveMQClientOptionsBuilder.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/Client/HiveMQClientOptionsBuilder.cs) +* [HiveMQClientOptions.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/Client/Options/HiveMQClientOptions.cs) +* [TLS/SSL - MQTT Security Fundamentals](https://www.hivemq.com/blog/mqtt-security-fundamentals-tls-ssl/) +* [HiveMQ Documentation on Security](https://docs.hivemq.com/hivemq/latest/user-guide/security.html) diff --git a/Documentation/docs/how-to/client-certificates.md b/Documentation/docs/how-to/client-certificates.md index f8ee89dd..3168e6c4 100644 --- a/Documentation/docs/how-to/client-certificates.md +++ b/Documentation/docs/how-to/client-certificates.md @@ -191,3 +191,11 @@ A couple tips on the above example: TLS negotiation with client certificates is based on the `X509Certificate2` class. See the [official .NET documentation](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509certificate2?view=net-8.0) for more options and information. + +## See Also + +* [X509 Client Certificate Authentication - MQTT Security Fundamentals](https://www.hivemq.com/blog/mqtt-security-fundamentals-x509-client-certificate-authentication/) +* [TLS/SSL - MQTT Security Fundamentals](https://www.hivemq.com/blog/mqtt-security-fundamentals-tls-ssl/) +* [HiveMQClientOptionsBuilder.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/Client/HiveMQClientOptionsBuilder.cs) +* [HiveMQClientOptions.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/Client/Options/HiveMQClientOptions.cs) +* [Microsoft .NET Documentation: X.509](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509certificate2?view=net-8.0) diff --git a/Documentation/docs/how-to/configure-logging.md b/Documentation/docs/how-to/configure-logging.md index 92b95fcf..18796510 100644 --- a/Documentation/docs/how-to/configure-logging.md +++ b/Documentation/docs/how-to/configure-logging.md @@ -1,4 +1,4 @@ -# Configure HiveMQtt Logging +# Configure Logging The HiveMQtt package uses [NLog](https://github.com/NLog/NLog) and can be configured with a configuration file (`NLog.config`). Having this file in the same directory of your executable will configure the HiveMQtt logger to output as configured: @@ -32,3 +32,7 @@ Setting `minlevel` to `Trace` will output all activity in the HiveMQtt package d 2023-10-04 16:56:55.0374|TRACE|HiveMQtt.Client.HiveMQClient|OnConnAckReceivedEventLauncher 2023-10-04 16:56:55.0379|TRACE|HiveMQtt.Client.HiveMQClient|AfterConnectEventLauncher ``` + +## See Also + +* [NLog](https://github.com/NLog/NLog) diff --git a/Documentation/docs/how-to/connect-with-auth.md b/Documentation/docs/how-to/connect-with-auth.md index 4b75831e..bff447d6 100644 --- a/Documentation/docs/how-to/connect-with-auth.md +++ b/Documentation/docs/how-to/connect-with-auth.md @@ -14,3 +14,11 @@ var options = new HiveMQClientOptionsBuilder() var client = new HiveMQClient(options); var connectResult = await client.ConnectAsync().ConfigureAwait(false); ``` + +## See Also + +* [Authentication with Username and Password - MQTT Security Fundamentals](https://www.hivemq.com/blog/mqtt-security-fundamentals-authentication-username-password/) +* [Advanced Authentication Mechanisms - MQTT Security Fundamentals](https://www.hivemq.com/blog/mqtt-security-fundamentals-advanced-authentication-mechanisms/) +* [HiveMQ Cloud / Authentication and Authorization](https://docs.hivemq.com/hivemq-cloud/authn-authz.html) +* [HiveMQClientOptionsBuilder.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/Client/HiveMQClientOptionsBuilder.cs) +* [HiveMQClientOptions.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/Client/Options/HiveMQClientOptions.cs) diff --git a/Documentation/docs/how-to/publish.md b/Documentation/docs/how-to/publish.md index 0ae62a4c..8d133c2d 100644 --- a/Documentation/docs/how-to/publish.md +++ b/Documentation/docs/how-to/publish.md @@ -72,6 +72,7 @@ For ease of use, you can call `PublishResult.ReasonCode()` to retrieve the appro ## See Also -* [MQTT5PublishMessage](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/MQTT5/Types/MQTT5PublishMessage.cs) -* [QualityOfService](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/MQTT5/Types/QualityOfService.cs) -* [PublishResult](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/Client/Results/PublishResult.cs) +* [PublishMessageBuilder.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/Client/PublishMessageBuilder.cs) +* [MQTT5PublishMessage.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/MQTT5/Types/MQTT5PublishMessage.cs) +* [QualityOfService.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/MQTT5/Types/QualityOfService.cs) +* [PublishResult.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/Client/Results/PublishResult.cs) diff --git a/Documentation/docs/how-to/set-lwt.md b/Documentation/docs/how-to/set-lwt.md index fcfd7d68..3c90d4a1 100644 --- a/Documentation/docs/how-to/set-lwt.md +++ b/Documentation/docs/how-to/set-lwt.md @@ -4,8 +4,7 @@ The Last Will and Testament support of MQTT can be used to notify subscribers th For a more in-depth explanation, see [What is MQTT Last Will and Testament (LWT)? – MQTT Essentials: Part 9](https://www.hivemq.com/blog/mqtt-essentials-part-9-last-will-and-testament/). - -# LastWillAndTestament +## Using LastWillAndTestament This example instantiates the `LastWillAndTestament` in the `HiveMQClientOption` class. This is then sent to the broker in the `connect` operation. @@ -37,12 +36,11 @@ var disconnectResult = await client.DisconnectAsync(disconnectOptions).Configure Because the client above disconnected with `DisconnectReasonCode.DisconnectWithWillMessage`, subscribers to the `last/will` topic will receive the Last Will and Testament message as specified above. -# LastWillAndTestament Builder Class +## The LastWillAndTestament Builder Class -As an ease-of-use alternative, the HiveMQtt client offers a `LastWillAndTestamentBuilder` class to more easily define a last will and testament class. +As an ease-of-use alternative, the HiveMQtt client offers a `LastWillAndTestamentBuilder` class to more easily instantiate a `LastWillAndTestament` class. ```csharp - var lwt = new LastWillAndTestamentBuilder() .WithTopic("last/will") .WithPayload("last will message") @@ -56,13 +54,18 @@ var lwt = new LastWillAndTestamentBuilder() .WithWillDelayInterval(1) .Build(); - // Setup & Connect the client with LWT - var options = new HiveMQClientOptions - { - LastWillAndTestament = lwt, - }; +// Setup & Connect the client with LWT +var options = new HiveMQClientOptions +{ + LastWillAndTestament = lwt, +}; - var client = new HiveMQClient(options); - connectResult = await client.ConnectAsync().ConfigureAwait(false); +var client = new HiveMQClient(options); +connectResult = await client.ConnectAsync().ConfigureAwait(false); ``` +## See Also + + * [What is MQTT Last Will and Testament (LWT)? – MQTT Essentials: Part 9](https://www.hivemq.com/blog/mqtt-essentials-part-9-last-will-and-testament/) + * [LastWillAndTestamentBuilder.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/Client/LastWillAndTestamentBuilder.cs) + * [LastWillAndTestament.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/Client/LastWillAndTestament.cs) diff --git a/Documentation/docs/how-to/subscribe-multi.md b/Documentation/docs/how-to/subscribe-multi.md index ddabc368..675b098c 100644 --- a/Documentation/docs/how-to/subscribe-multi.md +++ b/Documentation/docs/how-to/subscribe-multi.md @@ -14,3 +14,8 @@ var result = await client.SubscribeAsync(options); * `result.Subscriptions` contains the list of subscriptions made with this call * `client.Subscriptions` is updated with complete list of subscriptions made up to this point * each `Subscription` object has a resulting `ReasonCode` that represents the Subscribe result in `result.Subscriptions[0].ReasonCode` + +## See Also + +* [TopicFilter.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/MQTT5/Types/TopicFilter.cs) +* [SubscribeOptionsBuilder.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/Client/SubscribeOptionsBuilder.cs) diff --git a/Documentation/docs/how-to/wait-on-event.md b/Documentation/docs/how-to/wait-on-event.md index 778c8843..1f57a55f 100644 --- a/Documentation/docs/how-to/wait-on-event.md +++ b/Documentation/docs/how-to/wait-on-event.md @@ -30,6 +30,12 @@ await client.DisconnectAsync().ConfigureAwait(false); await taskCompletionSource.Task.WaitAsync(TimeSpan.FromSeconds(5)).ConfigureAwait(false); ``` +## See Also + +* [Lifecycle Events](/docs/events) +* [Events Source](https://github.com/hivemq/hivemq-mqtt-client-dotnet/tree/main/Source/HiveMQtt/Client/Events) +* [TaskCompletionSource Class (System.Threading.Tasks)](https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskcompletionsource-1?view=net-8.0) +