SocketLocator

Lightweight LAN Discovery & Auto-Configuration Library for .NET

SocketLocator is a small but powerful library that allows applications on the same LAN
to automatically detect a server/host machine without configuring static IPs.

It is ideal for:

• POS systems
• Local business networks
• Kiosk systems
• In-store multi-device solutions
• Any LAN-based auto-discovery scenario

SocketLocator uses UDP broadcast discovery with a very small protocol,
making it fast, dependency-free, and extremely easy to integrate.

---

🔗 POS Database Auto-Linking

One of the main goals of SocketLocator is to let POS clients automatically connect
to the main database hosted on a LAN "host" machine.

1. The client broadcasts a discovery message.
2. The host replies with: Host IP, DB Port, and Hostname.
3. The client builds its own database connection string using that information.

Example (SQL Server):

var info = await _socketMap.DiscoverAsync();
if (info is null) throw new Exception("Host not found.");

var connectionString =
    $"Server={info.Ip},{info.DbPort};Database=POSDB;User Id=sa;Password=StrongPassword;TrustServerCertificate=True;";

---

Features

• Automatic host discovery over LAN
• Zero-configuration for client devices
• Hardware serial number (Volume ID) sent automatically
• Server replies with: Host IP, DB Port, HostName
• Clean abstraction layer for Client + Server
• Real-time event when a new client connects
• Thread-safe device list (ConcurrentDictionary)
• Dependency Injection Ready (AddClientSocketMap / AddSocketServer)
• Works on Console, ASP.NET, Worker Service, WinForms, WPF… everything
• Tiny footprint & no external dependencies

---

Installation

dotnet add package SocketLocator

---

Quick Start — Client (POS Device)

var result = await _socketMap.DiscoverAsync();

if(result is not null)
{
    Console.WriteLine($"Host IP: {result.Ip}");
    Console.WriteLine($"DB Port: {result.DbPort}");
    Console.WriteLine($"Hostname: {result.HostName}");
}

Register the client implementation:

builder.Services.AddClientSocketMap(options =>
{
    options.DiscoveryPort = 50000;
    options.RequestMessage = "POS_DISCOVER";
    options.ResponsePrefix = "POS_HOST";
});

---

Quick Start — Host (Server Machine)

Register server services:

builder.Services.AddSocketServer(options =>
{
    options.ConnectionPort = 50000;
    options.RequestMessage = "POS_DISCOVER";
    options.ResponsePrefix = "POS_HOST";
});

Subscribe to new devices:

var server = app.Services.GetRequiredService<ISocketServer>();

if(server is UdpSocketServer udp)
{
    udp.OnSerialAdded += (serial) =>
    {
        Console.WriteLine($"New Client Detected: {serial}");
    };
}

Start server in a HostedService / worker:

public class SocketServerHostedService : BackgroundService
{
    private readonly ISocketServer _server;

    public SocketServerHostedService(ISocketServer server)
    {
        _server = server;
    }

    protected override Task ExecuteAsync(CancellationToken stoppingToken)
        => _server.ListenAsync(stoppingToken);
}

---

Protocol Overview

Client → Host

POS_DISCOVER|<VOLUME_SERIAL>

Host → Client

POS_HOST|<HOST_IP>|<DB_PORT>|<HOST_NAME>

---

Example Project (Console Host)

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSocketServer(options =>
{
    options.ConnectionPort = 50000;
});

builder.Services.AddHostedService<SocketServerHostedService>();

var app = builder.Build();
await app.RunAsync();

---

Author

Ali Zidan Distributed Systems & .NET Developer

Company

Studio Nex Software production