Sgcwebsockets Dotnet

sgcWebSockets .NET

The WebSocket client, the two WebSocket servers, the HTTP/2 client and the TCP client. This skill also carries the index of every component the .NET assembly exposes and, just as usefully, the list of Delphi components it does not.

When to use this skill

• Open a WebSocket connection from C#, or accept them in a server
• Serve HTTP and WebSocket from one port
• Talk HTTP/2 to a server
• Open a plain TCP connection
• Work out which skill documents a component, or whether it exists in .NET at all

Install and using

Reference esegece.sgcWebSockets.dll from the lib folder that matches your target framework, then:

using esegece.sgcWebSockets;

One namespace holds the whole library, so unlike the Delphi product there is no per-component unit to work out. concepts/overview.md lists the frameworks the installation ships.

Before you start, ask the developer

Use a structured question tool if your host has one, for example Claude Code's AskUserQuestion. Otherwise ask in chat:

1. Client or server? They are different components with different events.
2. Is this a UI application or a service? That decides NotifyEvents, and getting it wrong is the most common source of a hang or a cross-thread exception. See below.
3. TLS? TLS = true on the client, SSL = true plus SSLOptions on the server. A wss:// URL against a client with TLS left false will not connect.
4. Which framework? The assembly ships for everything from .NET Framework 2.0 to .NET 9, and the answer decides which lib folder to reference.

Components in this skill

Quickstart, a client

using esegece.sgcWebSockets;

var client = new TsgcWebSocketClient();
client.Host = "echo.websocket.org";
client.Port = 443;
client.TLS = true;

client.OnConnect += (TsgcWSConnection connection) =>
    Console.WriteLine("connected");
client.OnMessage += (TsgcWSConnection connection, string text) =>
    Console.WriteLine(text);
client.OnDisconnect += (TsgcWSConnection connection, int code) =>
    Console.WriteLine("closed " + code);
client.OnError += (TsgcWSConnection connection, string error) =>
    Console.WriteLine(error);

client.Active = true;

Active = true connects, Active = false disconnects. Start() and Stop() do the same thing under other names. WriteData(text) sends.

There is no sender parameter: the connection is the first argument and it is the only context a handler gets. The exact signatures are on the type pages under reference/types/. Read them rather than guessing, because they are generated from the assembly and they are what compiles.

The threading question, which is the one that bites

NotifyEvents decides which thread your handlers run on:

• neAsynchronous is the default. Events are queued and synchronised with the main thread asynchronously. This is what a WinForms or WPF application wants, because touching a control from another thread throws.
• neSynchronous blocks the connection thread until the main thread has processed the event. Correct when order matters, and a good way to deadlock if the main thread is waiting on the connection.
• neNoSync fires events directly on the connection thread. Faster, right for a console application or a service, and it makes every handler your problem to keep thread-safe.

client.NotifyEvents = TwsNotifyEvent.neNoSync;   // console or service

A console application left on the default is the usual reason "the events never fire": there is no message loop to synchronise with.

Things that catch people out

• Active = true returns before the connection is up. Do the work in OnConnect, not on the line after.
• TLS on the client, SSL on the server. Two different property names for the same idea, and neither is inferred from the port.
• The server takes Bindings as a string. Leave it empty to listen on Port for every interface.
• TsgcWebSocketHTTPServer serves HTTP as well as WebSocket. If you need a page and a socket on the same port, this is the one; TsgcWebSocketServer will not answer a plain HTTP request.
• The Delphi library has a separate TsgcHTTPServer and a REST server. Neither is in this assembly. concepts/coverage.md is the list.
• Watch the disconnect path in a UI application: closing a form while a connection is open and events are synchronising is where a shutdown hangs. Set Active = false before the form closes.

Routing

• API detail: reference/api/<Component>.md has the properties, events and methods, each with its C# signature.
• Option / enum / delegate types: property and event types link to reference/types/<TypeName>.md.
• Examples: examples/<Component>.md is a trimmed snippet from the shipped demo; examples/index.md maps every component to its demo.
• Find a component: reference/components-index.md lists every component this assembly exposes and the skill that documents it.
• Delphi parity: concepts/coverage.md lists what the Delphi library has that this assembly does not.
• Version history: reference/history.md.
• Getting started: concepts/overview.md covers the single using, the target frameworks and the naming.

What is documented

Public instance properties, events and methods declared anywhere in the library's own class chain. Members inherited from the .NET base classes are left out, as are internals, so a page shows the surface a caller writes against and nothing else.

If a component you need is not here, read concepts/coverage.md before assuming a different name for it. This assembly carries fewer components than the Delphi library, and saying so is more useful than guessing an API that does not exist.