Breaking Change: The .On() Method in the Latest Copilot SDK

If you're upgrading to the latest version of the Copilot SDK beta, there's a syntax change you need to know about. The .On() method now requires a generic type parameter. As the SDK is still in beta, breaking changes are not unexpected. But this one should be handled with extra care to avoid resource leaks.

This post walks you through what changed, why it matters, and how to update your code.

What changed

In previous versions of the SDK, registering an event handler looked something like this:

// Old syntax
app.On(evt =>
{
    if (ev is AssistantMessageDeltaEvent deltaEvent)
    {
        Console.Write(deltaEvent.Data.DeltaContent);
    }); 
}

In the latest version, the .On() method is now generic. You must explicitly specify the activity or event type you're handling:

// New syntax
using var subscription = app.On<AssistantMessageDeltaEvent>(evt =>
{
    Console.Write(deltaEvent.Data.DeltaContent);
});

The method signature has changed from:

// Before

IDisposable On(SessionEventHandler handler)

// After
IDisposable On<TSessionEvent>(Action<TSessionEvent> handler)

Why you must capture and dispose the return value

This is the part where you can get into trouble when using the updated API

.On<T>() returns an IDisposable — a subscription handle. If you don't hold onto this reference and dispose it properly, you risk:

• Memory leaks: The handler stays registered indefinitely, holding references that prevent garbage collection.
• Duplicate handlers: If .On<T>() is called multiple times (e.g., on reconnects or re-initialization), handlers accumulate and fire multiple times per event.
• Unexpected behavior after shutdown: Handlers may continue firing even after you intend the component to be inactive.

This was also the case with the non-generic.On() method. But I noticed some team members refactor this original implementation (that handles the subscription correctly):

To this(which no longer handles the subscription)

The correct pattern

Use using declarations (C# 8+) or using blocks to ensure deterministic cleanup:

Option 1

// Option 1: using declaration (recommended for scoped lifetime)
using var subscription = app.On<AssistantMessageDeltaEvent>(evt =>
{
    Console.Write(deltaEvent.Data.DeltaContent);
});

Option 2

If you need to capture multiple events in one subscription you can subscribe to the base SessionEvent and still use pattern matching:

// Option 2: using declaration (recommended for scoped lifetime)
using var subscription = app.On<SessionEvent>(evt =>
{
  switch(evt){//Add your pattern matching here}   
}

Summary

The new generic API is a clear improvement and helps to align with the syntax of other language versions(like TypeScript), but it does require a small amount of care around subscription management. The good news is that the pattern is standard C# — if you're already using IDisposable elsewhere in your project, this will feel familiar.

Take the time to audit your existing .On() calls before shipping to production.