{"id":15101981,"url":"https://github.com/hivemq/hivemq-mqtt-client-dotnet","last_synced_at":"2026-04-18T13:01:00.352Z","repository":{"id":71612025,"uuid":"559875418","full_name":"hivemq/hivemq-mqtt-client-dotnet","owner":"hivemq","description":"The HiveMQ C# Asynchronous MQTT client for .NET featuring full MQTT 5.0 and back pressure support.","archived":false,"fork":false,"pushed_at":"2025-01-26T12:37:55.000Z","size":12521,"stargazers_count":66,"open_issues_count":17,"forks_count":9,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-01-30T09:05:11.915Z","etag":null,"topics":["csharp","csharp-library","dotnet","dotnet-core","iot","iot-application","mqtt","mqtt-client","nuget","nuget-package"],"latest_commit_sha":null,"homepage":"https://hivemq.github.io/hivemq-mqtt-client-dotnet/","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hivemq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-31T09:30:01.000Z","updated_at":"2025-01-20T14:09:11.000Z","dependencies_parsed_at":"2023-05-31T19:01:19.161Z","dependency_job_id":"bd8788ef-2621-481a-8a5c-3acd95c832ca","html_url":"https://github.com/hivemq/hivemq-mqtt-client-dotnet","commit_stats":{"total_commits":208,"total_committers":4,"mean_commits":52.0,"dds":0.3173076923076923,"last_synced_commit":"5f2b4d8c02da2912c7806a299b26d2faf79b0fc9"},"previous_names":[],"tags_count":56,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hivemq%2Fhivemq-mqtt-client-dotnet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hivemq%2Fhivemq-mqtt-client-dotnet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hivemq%2Fhivemq-mqtt-client-dotnet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hivemq%2Fhivemq-mqtt-client-dotnet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hivemq","download_url":"https://codeload.github.com/hivemq/hivemq-mqtt-client-dotnet/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247149501,"owners_count":20891954,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csharp","csharp-library","dotnet","dotnet-core","iot","iot-application","mqtt","mqtt-client","nuget","nuget-package"],"created_at":"2024-09-25T18:44:20.296Z","updated_at":"2026-04-18T13:01:00.332Z","avatar_url":"https://github.com/hivemq.png","language":"C#","funding_links":[],"categories":["Clients","MQTT","Audio","C# #"],"sub_categories":["DotNET","GUI - other","C# / .NET"],"readme":"![HiveMQtt logo](https://i.imgur.com/YmafvGk.png)\n![HiveMQ C# MQTT Client banner](https://i.imgur.com/Tnl78V6.png)\n\n# The Spectacular C# MQTT and Sparkplug Clients for .NET\n\n[![NuGet Version](https://img.shields.io/nuget/v/HiveMQtt?style=for-the-badge)](https://www.nuget.org/packages/HiveMQtt)\n[![GitHub release (latest by date)](https://img.shields.io/github/v/release/hivemq/hivemq-mqtt-client-dotnet?style=for-the-badge)](https://github.com/hivemq/hivemq-mqtt-client-dotnet/releases)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/hivemq/hivemq-mqtt-client-dotnet/build.yml?style=for-the-badge)](https://github.com/hivemq/hivemq-mqtt-client-dotnet/actions)\n[![NuGet](https://img.shields.io/nuget/dt/HiveMQtt?style=for-the-badge)](https://www.nuget.org/packages/HiveMQtt)\n[![GitHub](https://img.shields.io/github/license/hivemq/hivemq-mqtt-client-dotnet?style=for-the-badge)](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/LICENSE)\n\n![Static Badge](https://img.shields.io/badge/.NET-6.0-%23512BD4?style=for-the-badge)\n![Static Badge](https://img.shields.io/badge/.NET-7.0-%23512BD4?style=for-the-badge)\n![Static Badge](https://img.shields.io/badge/.NET-8.0-%23512BD4?style=for-the-badge)\n![Static Badge](https://img.shields.io/badge/.NET-9.0-%23512BD4?style=for-the-badge)\n![Static Badge](https://img.shields.io/badge/.NET-10.0-%23512BD4?style=for-the-badge)\n\n\u003e Looking for the **Sparkplug Client**? Use [HiveMQtt.Sparkplug](https://www.nuget.org/packages/HiveMQtt.Sparkplug/) and start with the [Sparkplug README](./Source/HiveMQtt.Sparkplug/README.md) for quick start guides and examples.\n\n### 💽 Installation \u0026 Compatibility\n* **Easy-to-Install**: Available as a [NuGet package](https://www.nuget.org/packages/HiveMQtt).\n* **Globally Compatible**: Built to be a fully compliant MQTT 5.0 client compatible with all modern MQTT brokers.\n* **Multi-Targeted**: Supports .NET 6.0, 7.0, 8.0, 9.0 \u0026 10.0\n* **Sparkplug Client extension**: The [HiveMQtt.Sparkplug](https://www.nuget.org/packages/HiveMQtt.Sparkplug) package adds Host Application and Edge Node support for industrial IoT (IIoT) using the [Eclipse Sparkplug B 3.0](https://sparkplug.eclipse.org/specification/version/3.0) specification—install with `dotnet add package HiveMQtt.Sparkplug` and see the [Sparkplug README](./Source/HiveMQtt.Sparkplug/README.md) for full details.\n\n### 🚀 Features\n* **MQTT 5.0 Support**: Fully compliant with the latest [MQTT 5.0 specification](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html), ensuring compatibility with modern MQTT brokers.\n* **Multiple Transport Options**: Support for both TCP and WebSocket connections (ws:// and wss://), ideal for network environments that restrict TCP traffic or require HTTP-compatible transport.\n* **Manual Acknowledgement**: Control when the broker considers QoS 1 and QoS 2 messages delivered. Process or persist messages first, then call `AckAsync`—ideal for at-least-once and exactly-once workflows. See the [manual ack guide](https://hivemq.github.io/hivemq-mqtt-client-dotnet/docs/how-to/manual-ack).\n* **TCP \u0026 WebSocket Proxy Support**: Connect through HTTP proxies—TCP via [HTTP CONNECT tunneling](https://hivemq.github.io/hivemq-mqtt-client-dotnet/docs/how-to/configure-proxy) (`WithProxy`), WebSocket via `WithWebSocketProxy`. Perfect for corporate networks and firewalls.\n* **Back Pressure Management**: Automatically manages back pressure to prevent overwhelming the broker (or client), ensuring reliable and efficient communication.\n* **Asynchronous Design**: Designed for high-performance and low-latency communication, allowing your application to process multiple messages concurrently.\n* **Extensive Event System**: Hook into all parts of the client down to the packet level with [built in events](https://hivemq.github.io/hivemq-mqtt-client-dotnet/docs/events).\n* **Global and Per-Subscription Message Handling**: Use multiple targeted handlers for more targeted and specialized message processing.\n* **Full Last Will \u0026 Testament Support**: Reliable message delivery and notification of client disconnections.\n* **Secure Client Identification**: Full support for [X.509 client certificates](https://hivemq.github.io/hivemq-mqtt-client-dotnet/docs/how-to/client-certificates) and TLS connections.\n* **Observable**: Configure up to [TRACE level logging](https://hivemq.github.io/hivemq-mqtt-client-dotnet/docs/how-to/debug) for package internals.\n* **Fast**: Optimized \u0026 benchmarked.  See the benchmark results [here](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Benchmarks/ClientBenchmarkApp/README.md).\n\n### 🔒 Security\n* **Secure Password Storage**: Passwords are stored using `SecureString` to prevent exposure in memory dumps and process memory. Use `WithPassword(SecureString)` for enhanced security.\n* **Secure Certificate Password Handling**: Certificate passwords are handled securely using `SecureString`. Use `WithClientCertificate(path, SecureString)` for enhanced security.\n* **Memory-Safe Password Handling**: Temporary password strings are automatically cleared from memory after use, ensuring no sensitive data persists in memory.\n* **Backward Compatibility**: Existing code using string passwords continues to work while being automatically converted to secure storage internally.\n* **TLS/SSL Support**: Full support for encrypted connections (both TCP and WebSocket) with configurable certificate validation and custom certificate handling.\n* **Secure WebSocket (wss://)**: Complete support for secure WebSocket connections with client certificate authentication and configurable certificate validation.\n* **X.509 Certificate Authentication**: Complete support for client certificate authentication with secure private key handling for both TCP and WebSocket connections.\n\n### 🏝️ Ease of Use\n* **Easy to Use**: Smart defaults, excellent interfaces and intelligent automation make implementation a breeze.\n* **Easy Integration**: Simple and intuitive API makes it easy to integrate with your .NET applications.\n\n### 🛟 Maintenance and Support\n* **Actively Maintained**: Built by the MQTT professionals that built HiveMQ (and do this for a living).\n* **Supported**: Contact us anytime in [this repository](https://github.com/hivemq/hivemq-mqtt-client-dotnet/issues), in the [community forum](https://community.hivemq.com) or [through support](https://www.hivemq.com/support/).\n* **Extensively Documented**: What good is it without [excellent documentation](https://hivemq.github.io/hivemq-mqtt-client-dotnet/)?\n\n### 🐧 Open Source\n* **Open Source**: No blackbox code. Only trusted, tested and reviewed open source code.\n\n\n**📍 Get Started Today**\n\nDownload the HiveMQ C# MQTT Client for .NET and start building your next-generation IoT, industrial automation, or real-time data streaming application with HiveMQ on your side.\n\n_Do you have a success story with this client?  [Let us know](https://www.hivemq.com/contact/?btn=contact-nav).  We'd love to feature your story in a blog post or video and you'll get some sweet HiveMQ swag (and publicity) along the way._\n\n## What is this?\n\nMQTT is an [open standard protocol](https://mqtt.org) for publishing and consuming messages from IoT devices all the way up to mainframes.  It's binary, massively performant and easy to use.\n\nThis client library is used to publish and consume messages over MQTT.  So you can get the temperature from a remote sensor, send a control message to a factory robot, tunnel WhatsApp messages to an X account or anything else you can imagine.\n\nThis is the client library that speaks with an MQTT broker that delivers messages to their final destination.\n\nNeed a broker? Sign up for a free broker at [HiveMQ Cloud](https://www.hivemq.com/mqtt-cloud-broker/) and be up and running in a couple minutes.  Connect up to 100 devices - no credit card required.\n\n## MQTT Resources\n\n* [MQTT Essentials](https://www.hivemq.com/mqtt-essentials/) (Great for beginners wanting an introduction)\n* [MQTT Toolbox](https://www.hivemq.com/mqtt-toolbox/)\n* [MQTT Client Library Encyclopedia](https://www.hivemq.com/mqtt-client-library-encyclopedia/)\n* HiveMQ [Public Broker](http://www.mqtt-dashboard.com)\n* HiveMQ [Support](https://www.hivemq.com/support/)\n\n## Need an MQTT Broker?\n\nThis client communicates with an MQTT broker to publish and consume messages.  It's built to be compatible with all major MQTT brokers but if you need a broker now run the HiveMQ Community Edition:\n\n```bash\ndocker run --name hivemq-ce -d -p 1883:1883 hivemq/hivemq-ce\n```\n\nThis will run the HiveMQ Community Edition broker on localhost port 1883.\n\nIf you need advanced features, check out our [premium editions](https://www.hivemq.com/hivemq/editions/) or alternatively [HiveMQ Cloud](https://www.hivemq.com/mqtt-cloud-broker/) which is free to connect up to 100 devices (no credit card required).\n\n## Install\n\n### HiveMQtt (core client)\n\nThis package is [available on NuGet.org](https://www.nuget.org/packages/HiveMQtt/) and can be installed with:\n\n```sh\ndotnet add package HiveMQtt\n```\n\nSee the [HiveMQtt NuGet page](https://www.nuget.org/packages/HiveMQtt/) for more installation options.\n\n### HiveMQtt.Sparkplug (Sparkplug B extension)\n\nThe **HiveMQtt.Sparkplug** package is now available on NuGet. It extends the HiveMQtt client with [Sparkplug B 3.0](https://sparkplug.eclipse.org/specification/version/3.0) support for industrial IoT: Host Applications (subscribe to Edge Nodes and Devices, publish NCMD/DCMD) and Edge Nodes (publish NBIRTH/NDATA/NDEATH, DBIRTH/DDATA/DDEATH; receive NCMD/DCMD). Install with:\n\n```sh\ndotnet add package HiveMQtt.Sparkplug\n```\n\nSee the [HiveMQtt.Sparkplug NuGet page](https://www.nuget.org/packages/HiveMQtt.Sparkplug/) and the [extension README](Source/HiveMQtt.Sparkplug/README.md) for details and quick start.\n\n## Example\n\nThe following illustrates the client pattern to connect, subscribe and publish messages.\n\n```csharp\nusing HiveMQtt.Client;\nusing HiveMQtt.MQTT5.Types;\n\n// Setup Client options and instantiate\nvar options = new HiveMQClientOptionsBuilder().\n                    WithBroker(\"candy.x39.eu.hivemq.cloud\").\n                    WithPort(8883).\n                    WithUseTls(true).\n                    Build();\nvar client = new HiveMQClient(options);\n\n// Setup application message handlers BEFORE subscribing to a topic\nclient.OnMessageReceived += (sender, args) =\u003e\n{\n    Console.WriteLine($\"Message Received: {args.PublishMessage.PayloadAsString}\");\n};\n\n// Connect to the MQTT broker\nvar connectResult = await client.ConnectAsync().ConfigureAwait(false);\n\n// Configure the subscriptions we want and subscribe\nvar builder = new SubscribeOptionsBuilder();\nbuilder.WithSubscription(\"topic1\", QualityOfService.AtLeastOnceDelivery)\n       .WithSubscription(\"topic2\", QualityOfService.ExactlyOnceDelivery);\nvar subscribeOptions = builder.Build();\nvar subscribeResult = await client.SubscribeAsync(subscribeOptions);\n\n// Publish a message\nvar publishResult = await client.PublishAsync(\"topic1/example\", \"Hello Payload\");\n```\n\n### WebSocket Connection Example\n\nThe client also supports WebSocket connections (ws:// and wss://). WebSocket is useful when:\n- Network policies only allow HTTP/HTTPS traffic (firewalls, proxies that block TCP)\n- You need to leverage existing WebSocket infrastructure\n- You're building server-side .NET applications that require HTTP-compatible transport\n\n```csharp\nusing HiveMQtt.Client;\nusing HiveMQtt.MQTT5.Types;\n\n// Connect via WebSocket (ws://)\nvar options = new HiveMQClientOptionsBuilder()\n    .WithWebSocketServer(\"ws://localhost:8000/mqtt\")\n    .WithClientId(\"WebSocketClient\")\n    .Build();\n\n// Or connect via secure WebSocket (wss://) with TLS\nvar secureOptions = new HiveMQClientOptionsBuilder()\n    .WithWebSocketServer(\"wss://broker.hivemq.com:8884/mqtt\")\n    .WithClientId(\"SecureWebSocketClient\")\n    .Build();\n\nvar client = new HiveMQClient(secureOptions);\nvar connectResult = await client.ConnectAsync().ConfigureAwait(false);\n\n// Use the same API for publish/subscribe - works identically to TCP connections\nclient.OnMessageReceived += (sender, args) =\u003e\n{\n    Console.WriteLine($\"WebSocket Message: {args.PublishMessage.PayloadAsString}\");\n};\n\nawait client.SubscribeAsync(\"my/topic\");\nawait client.PublishAsync(\"my/topic\", \"Hello from WebSocket!\");\n```\n\n### Manual Acknowledgement (QoS 1 \u0026 2)\n\nWhen you need to process or persist messages before the broker is told they were received, enable manual ack. The client won't send PubAck/PubRec until you call `AckAsync`:\n\n```csharp\nusing HiveMQtt.Client;\nusing HiveMQtt.MQTT5.Types;\n\nvar options = new HiveMQClientOptionsBuilder()\n    .WithBroker(\"broker.example.com\")\n    .WithPort(1883)\n    .WithManualAck()\n    .Build();\n\nvar client = new HiveMQClient(options);\nclient.OnMessageReceived += async (sender, args) =\u003e\n{\n    await ProcessOrPersistAsync(args.PublishMessage);\n    await client.AckAsync(args);   // Safe for any QoS (no-op for QoS 0)\n};\n\nawait client.ConnectAsync();\nawait client.SubscribeAsync(\"orders/#\", QualityOfService.AtLeastOnceDelivery);\n```\n\nSee the [manual acknowledgement guide](https://hivemq.github.io/hivemq-mqtt-client-dotnet/docs/how-to/manual-ack) for Receive Maximum, thread safety, and RawClient usage.\n\n### TCP and WebSocket Proxy Support\n\nConnect through HTTP proxies—essential in corporate or restricted networks:\n\n**TCP (HTTP CONNECT tunnel):**\n\n```csharp\nusing System.Net;\nusing HiveMQtt.Client;\n\nvar options = new HiveMQClientOptionsBuilder()\n    .WithBroker(\"broker.example.com\")\n    .WithPort(1883)\n    .WithProxy(new WebProxy(\"http://proxy.example.com:8080\"))\n    .Build();\n\nvar client = new HiveMQClient(options);\nawait client.ConnectAsync();\n```\n\n**WebSocket:** Use `WithWebSocketProxy(new WebProxy(\"http://proxy.example.com:8080\"))` with `WithWebSocketServer(...)`. Both support proxy credentials. Full details: [Configure a Proxy Server](https://hivemq.github.io/hivemq-mqtt-client-dotnet/docs/how-to/configure-proxy).\n\n---\n\nFor a Quickstart, more examples and walkthroughs, see [the documentation](https://hivemq.github.io/hivemq-mqtt-client-dotnet/docs/quickstart).\n\n## Other MQTT Clients\n\n* [Java](https://github.com/hivemq/hivemq-mqtt-client)\n* [Javascript](https://github.com/hivemq/hivemq-mqtt-web-client)\n\nFor a list of all known MQTT clients, see [MQTT.org](https://mqtt.org/software/).\n\n## 🛡 License\n\n[![License](https://img.shields.io/github/license/hivemq/hivemq-mqtt-client-dotnet)](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/LICENSE)\n\nThis project is licensed under the terms of the `Apache Software License 2.0` license. See [LICENSE](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/LICENSE) for more details.\n\n## 📃 Citation\n\n```bibtex\n@misc{hivemq-mqtt-client-dotnet,\n  author = {HiveMQ GmbH},\n  title = {The HiveMQ C# MQTT client for .NET},\n  year = {2026},\n  publisher = {GitHub},\n  journal = {GitHub repository},\n  howpublished = {\\url{https://github.com/hivemq/hivemq-mqtt-client-dotnet}}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhivemq%2Fhivemq-mqtt-client-dotnet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhivemq%2Fhivemq-mqtt-client-dotnet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhivemq%2Fhivemq-mqtt-client-dotnet/lists"}