SimpleUdp

Simple wrapper for UDP client and server in C#

SimpleUdp provides simple methods for creating your own UDP-based sockets application, enabling easy integration of sending data, receiving data, and building state machines.

New in v3.3.1

• Update the Caching dependency to 5.1.2 and refresh the test tooling (Touchstone 0.2.0, NUnit 5.0.0, Microsoft.NET.Test.Sdk, coverlet, NUnit analyzers/adapter)
• No public API changes

New in v3.3.0

• Built-in metrics and traces through the BCL Meter and ActivitySource named SimpleUdp (no new dependencies, near-zero cost when nothing is listening)
• Covers sends (per-stage queued/transmit latency, outcomes by error.type), receives, event handler latency and swallowed handler exceptions, receive loop stops, endpoint lifecycle, and the recent-endpoints cache
• Ready-to-provision Grafana dashboard in assets/grafana/simpleudp.json
• Raise the socket send buffer to fit 65507-byte datagrams on platforms with a smaller default (macOS)
• See TELEMETRY.md

New in v3.2.0

• Update the Caching dependency to 5.0.1 and refresh the test tooling
• Add synchronous concurrent-send and post-dispose broadcast test coverage
• No public API changes

New in v3.1.0

• Add EnableBroadcast for opt-in UDP broadcast sends without changing the existing send and receive APIs

New in v3.0.0

• Require .NET 8.0 or newer
• Use a single bound socket for both inbound and outbound UDP traffic

New in v2.0.x

• Retarget to .NET 8.0
• Removal of Start, Stop APIs, and, the started event
• Better multi-platform compatibility (Windows, Mac OSX, Ubuntu)

Telemetry

SimpleUdp emits OpenTelemetry-compatible metrics and traces through the .NET Meter and ActivitySource named SimpleUdp. Subscribe your collector to that name and the data flows to Prometheus, Tempo, or any OTLP backend:

// Radiant
settings.Sources.AddMeter("SimpleUdp");
settings.Sources.AddActivitySource("SimpleUdp");

// OpenTelemetry SDK
Sdk.CreateMeterProviderBuilder().AddMeter("SimpleUdp")...
Sdk.CreateTracerProviderBuilder().AddSource("SimpleUdp")...

See TELEMETRY.md for the metric and span catalogs, recommended alerts, and the Grafana dashboard.

Help or Feedback

Need help or have feedback? Please file an issue here!

Tests

Touchstone-based tests live under src/:

• Test.Shared contains the reusable test case descriptors and helpers
• Test.Automated is the console runner
• Test.Xunit runs the shared cases through the Touchstone xUnit adapter
• Test.Nunit runs the shared cases through the Touchstone NUnit adapter

Run the console suite:

dotnet run --project src/Test.Automated --framework net10.0

Run adapter suites:

dotnet test src/Test.Xunit/Test.Xunit.csproj --framework net10.0
dotnet test src/Test.Nunit/Test.Nunit.csproj --framework net10.0

Special Thanks

Thanks to community members that have helped improve this library! @jholzer @charleypeng @seatrix

Need TCP Instead?

I have you covered.

• WatsonTcp - easiest way to build TCP-based applications with built-in framing
  • Github: https://github.com/jchristn/watsontcp
  • NuGet: https://www.nuget.org/packages/WatsonTcp/
  • 
• SimpleTcp - lightweight TCP wrapper without framing
  • Github: https://github.com/jchristn/simpletcp
  • NuGet: https://www.nuget.org/packages/SuperSimpleTcp/
  • 
• CavemanTcp - TCP wrapper exposing controls for sending and receiving data to build state machines
  • Github: https://github.com/jchristn/cavemantcp
  • NuGet: https://www.nuget.org/packages/CavemanTcp/
  • 

Don't know what to use? Just ask! File an issue, I'll be happy to help.

Simple Example

Start a node.

using SimpleUdp;

UdpEndpoint udp = new UdpEndpoint("127.0.0.1", 8000);
udp.EndpointDetected += EndpointDetected;

// only if you want to receive messages...
udp.DatagramReceived += DatagramReceived;

// send a message...
udp.Send("127.0.0.1", 8001, "Hello to my friend listening on port 8001!");

// enable broadcast if you need to send to a broadcast address...
udp.EnableBroadcast = true;
udp.Send("255.255.255.255", 8001, "Hello to everyone listening on port 8001!");

static void EndpointDetected(object sender, EndpointMetadata md)
{
  Console.WriteLine("Endpoint detected: " + md.Ip + ":" + md.Port);
}

static void DatagramReceived(object sender, Datagram dg)
{
  Console.WriteLine("[" + dg.Ip + ":" + dg.Port + "]: " + Encoding.UTF8.GetString(dg.Data));
}

The Node Project

Start node 1.

Node\bin\Debug\net8.0> node 127.0.0.1 8000

Start node 2.

Node\bin\Debug\net8.0> node 127.0.0.1 8001

Send message from node 1 to node 2. To do this, enter a command as follows:

[ip:port] [msg]

i.e.

127.0.0.1:8001 hello to my friend running on port 8001!

[127.0.0.1:8000 Command/? for help]: 127.0.0.1:8001 hello to my friend on port 8001!

Send message from node 2 to node 1.

[127.0.0.1:8001 Command/? for help]: Endpoint detected: 127.0.0.1:8000
[127.0.0.1:8000]: hello to my friend on port 8001!
127.0.0.1:8000 hello back to you my friend!

Version History

Please refer to CHANGELOG.md.