GATT Service

Overview

GATT services define the data your BLE peripheral exposes. Each service contains characteristics that centrals can read from, write to, or subscribe to for notifications.

Creating a Service (Inline)

Use the builder pattern to create services dynamically.

IBleHostingManager hostingManager; // injected

var service = await hostingManager.AddService(
    "Your-Service-UUID",
    true, // primary service
    sb =>
    {
        sb.AddCharacteristic("char-uuid-1", cb =>
        {
            cb.SetRead(request =>
            {
                var data = System.Text.Encoding.UTF8.GetBytes("Hello");
                return Task.FromResult(GattResult.Success(data));
            });

            cb.SetWrite(request =>
            {
                var receivedData = request.Data;
                Console.WriteLine($"Received: {System.Text.Encoding.UTF8.GetString(receivedData)}");
                return Task.CompletedTask;
            });

            cb.SetNotification((subscription) =>
            {
                Console.WriteLine(subscription.IsSubscribing
                    ? "Central subscribed"
                    : "Central unsubscribed");
                return Task.CompletedTask;
            });
        });
    }
);

Characteristic Operations

Read

Return a GattResult with your data or an error status.

cb.SetRead(request =>
{
    // request.Peripheral - the connecting central
    // request.Offset - data offset
    var data = GetYourData();
    return Task.FromResult(GattResult.Success(data));
}, encrypted: false);

Write

Handle incoming writes from centrals.

cb.SetWrite(request =>
{
    // request.Data - the written bytes
    // request.Peripheral - the connecting central
    // request.IsReplyNeeded - whether a response is expected
    // request.Respond(GattState) - send response if needed

    if (request.IsReplyNeeded)
        request.Respond(GattState.Success);

    return Task.CompletedTask;
}, WriteOptions.Write);

WriteOptions flags: Write, WriteWithoutResponse, AuthenticatedSignedWrites, EncryptionRequired

Notifications

Send data to subscribed centrals.

// After setting up notification on a characteristic:
var characteristic = service.Characteristics.First();

// Notify all subscribed centrals
await characteristic.Notify(data);

// Notify specific centrals
await characteristic.Notify(data, central1, central2);

// Check who is subscribed
var subscribers = characteristic.SubscribedCentrals;

On iOS, Mac Catalyst and macOS, Notify applies CoreBluetooth’s back-pressure: when the transmit queue is full it waits until the queue drains and retries, so the returned task completes once the value is actually queued. Await it before sending the next notification rather than firing many in parallel.

Pass a CancellationToken to stop waiting - it goes before the centrals. If Bluetooth powers off while a notification is waiting, the task faults with InvalidOperationException.

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
await characteristic.Notify(data, cts.Token);
await characteristic.Notify(data, cts.Token, central1, central2);

An empty centrals list sends to every subscriber; a named list sends only to those centrals. SubscribedCentrals is tracked whether or not you pass a subscribe hook to SetNotification.

Android

Notify waits for each central’s onNotificationSent before sending that central the next value - Android refuses a second notification while one is in flight. Centrals are sent to in parallel. A notification Android refuses or reports as failed throws; a central that disconnects mid-send is skipped.

Linux (BlueZ)

BlueZ tells an external GATT application only whether notifications are enabled, not which central enabled them - while any central is subscribed, every connected central is reported in SubscribedCentrals. BlueZ also sends each value to every subscribed central, so the centrals you pass cannot narrow the recipients (the send is skipped only if none of them is subscribed). Don’t put per-central data on a notify characteristic shared by several centrals on Linux.

NotificationOptions flags: Notify, Indicate, EncryptionRequired

Managing Services

// Remove a specific service
hostingManager.RemoveService("Your-Service-UUID");

// Clear all services
hostingManager.ClearServices();

// List active services
var services = hostingManager.Services;

Composing Services in a Class

The reflection-based managed characteristic pattern (BleGattCharacteristic base + [BleGattCharacteristic] attribute + AttachRegisteredServices) was removed for AOT compliance. You have two replacements:

• Declare the service with [BleService] on a partial class and let the source generator emit these calls for you — attribute ergonomics with no reflection. This is the shorter path for anything beyond a characteristic or two.
• Or compose the service in code by registering a hosting class that calls AddService(...) on startup:

public class MyGattHostingService(IBleHostingManager manager, ILogger<MyGattHostingService> logger) : IShinyStartupTask
{
    public async void Start()
    {
        var access = await manager.RequestAccess(advertise: true, connect: true);
        if (access != AccessState.Available)
            return;

        await manager.AddService("Your-Service-UUID", primary: true, sb =>
        {
            sb.AddCharacteristic("Your-Characteristic-UUID", cb =>
            {
                cb.SetRead(req =>
                {
                    var data = System.Text.Encoding.UTF8.GetBytes("Hello");
                    return Task.FromResult(GattResult.Success(data));
                });

                cb.SetWrite(req =>
                {
                    logger.LogInformation("Received {Bytes} bytes", req.Data.Length);
                    if (req.IsReplyNeeded)
                        req.Respond(GattState.Success);
                    return Task.CompletedTask;
                }, WriteOptions.Write);

                cb.SetNotification(sub =>
                {
                    logger.LogInformation("Subscription change: {Sub}", sub.IsSubscribing);
                    return Task.CompletedTask;
                }, NotificationOptions.Notify);
            });
        });

        await manager.StartAdvertising(new AdvertisementOptions("MyDevice", "Your-Service-UUID"));
    }
}

Register it like any other Shiny service:

services.AddBluetoothLeHosting();
services.AddSingleton<IShinyStartupTask, MyGattHostingService>();

This keeps everything testable (the class can be exercised against a mocked IBleHostingManager), preserves AOT-cleanliness, and avoids the runtime attribute scanning the old pattern relied on. The source generator produces the same shape from attributes, and additionally hands you a per-connected-central context, generated notify helpers, and compile-time checks on your UUIDs and handler signatures.

Caution

Write the full 128-bit UUID when calling AddService / AddCharacteristic directly. Short forms like "180D" are accepted by Apple’s CBUUID.FromString but throw on Android, which goes through java.util.UUID.fromString. The source generator normalizes them for you; the imperative API does not.