# Sgcwebsockets Dotnet

> Use when writing C# or .NET code with the eSeGeCe sgcWebSockets library. Covers TsgcWebSocketClient, TsgcWebSocketServer, TsgcWebSocketHTTPServer, the HTTP/2 client and the TCP client, and carries the index of every component the .NET assembly exposes plus the list of Delphi components it does not.

- Skill: `esegece-com/sgcwebsockets-dotnet` (Agent Skill, multi-file: 137 files)
- Install (CLI): `npx skillmds@latest add esegece-com/sgcwebsockets-dotnet`
- Raw SKILL.md: https://api.skillmd.com/api/skills/esegece-com/sgcwebsockets-dotnet/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: esegece-com (https://skillmd.com/u/esegece-com)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/esegece-com/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:

```csharp
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

| Component | What it is |
| --- | --- |
| `TsgcWebSocketClient` | WebSocket client |
| `TsgcWebSocketServer` | WebSocket server |
| `TsgcWebSocketHTTPServer` | WebSocket server that also serves HTTP |
| `TsgcHTTP2Client` | HTTP/2 client |
| `TsgcTCPClient` | plain TCP client |

## Quickstart, a client

```csharp
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.

```csharp
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.