# CanalSharp: a .NET client for Canal, the MySQL binlog subscription service

> CanalSharp is the .NET client for Canal, Alibaba's open source change data capture component for MySQL. It gives a .NET application a connection to a Canal server, a subscription to the subscribed data, and a pull loop that returns decoded binlog entries, with the protocol generated from protobuf 3 definitions. It is Apache-2.0 licensed and a member project of the .NET Core Community.

**dotnetcore/CanalSharp** —  Alibaba mysql database binlog subscription & consumer components Canal's .NET client.

- Repository: https://github.com/dotnetcore/CanalSharp
- Stars: 593 · Forks: 98
- Language: C#
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/dotnetcore-canalsharp

## A .NET client for a Java service, and what that means for you

CanalSharp is the.NET client for Canal, the open source Alibaba project for incremental subscription and consumption of MySQL database binlogs.

The README explains the concept it sits in. In a database, change data capture, or CDC, is a set of software design patterns used to determine and track changed data so that the changed data can be acted on. Canal is a CDC component for MySQL.

So the division of labour is fixed. Canal runs next to MySQL, reads the binlog and speaks its own protocol. CanalSharp is the client library that a.NET application uses to talk to that Canal server. There is no MySQL driver in this library and no binlog parser in it either.

That is worth saying plainly because it determines the operational footprint. Adopting CanalSharp means running, or already running, a Canal server, which in turn means a MySQL with binlog enabled. If you are starting from nothing, the chain is MySQL, then Canal, then CanalSharp, and the README is not a guide to setting up the first two.

The project is Apache-2.0 licensed with a LICENSE file at the root, the primary language is C#, and it is a member project of the.NET Core Community. The default branch is main, the last push was on 2026-10-22, and the topic tags name the domain precisely: binlog, canal, canal-client, cdc, mysql, netcore, netstandard20 and real-time.

The release history is worth reading before you plan an upgrade. The recent tags are v1.2.0 from 2023-02-27, v1.1.0 from 2020-11-16 and v1.0.0 from 2020-11-03. So the packaged versions are old even though the repository is being pushed to, which tells you that most of the recent work is on the main branch rather than in tagged releases.

## The whole API is construct, connect, subscribe, pull

The quick start in the README is short enough that the shape of the library is visible in a minute.

First you install it from NuGet.

```shell
Install-Package CanalSharp
```

Then you set up logging, which is the first piece of real setup because the library uses Microsoft.Extensions.Logging.Abstractions.

```csharp
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddFilter("Microsoft", LogLevel.Debug)
        .AddFilter("System", LogLevel.Information)
        .AddConsole();
});
var logger= loggerFactory.CreateLogger<SimpleCanalConnection>();
```

The reason for using the abstractions rather than a concrete logger is stated: mainstream logging components such as nlog and serilog all support this logging abstraction, so you can use them by installing their adapters, whether it is a Console App or a Web App. That is a deliberate choice not to take a logging dependency, and it means you wire up your own logging stack in the ordinary Microsoft way.

Then you create the connection with the host, port and destination number, connect to the Canal server, and subscribe.

```csharp
var conn=new SimpleCanalConnection(new SimpleCanalOptions("127.0.0.1",11111,1234),logger);
await conn.ConnectAsync();
await conn.SubscribeAsync();
```

The three constructor arguments in the options object are the address, the port and the destination identifier, and 1234 in the example is that destination number, which in Canal terms is the instance where the client wants its changes delivered.

Then data arrives by pulling.

```csharp
var msg = await conn.GetAsync(1024);
```

So the consumption model is pull based. The client asks for up to 1024 entries and gets a batch back. There is no callback registration and no background poller in the visible documentation, which means your application owns the loop.

That is a genuine difference in approach from a push-based CDC client, and it is the design decision an adopter should weigh first. Pull means you control the rate and the backpressure, and you write the scheduling. Push means the library drives your callback and you deal with whatever concurrency it chooses.

## Version compatibility is a single row, and the MySQL version is Canal's problem

The support table in the README is one line.

| CanalSharp | Canal |
|------------|-------|
| 1.2.0      | 1.1.6 |

And then the sentence that removes most of the guesswork: the MySQL version is determined by Canal.

That is a narrow and honest position. Rather than listing a matrix of client and server versions, the project pins one pairing, CanalSharp 1.2.0 with Canal 1.1.6, and explicitly declines to take responsibility for the MySQL side of the matrix. In practice it means the MySQL version, the binlog format and the Canal server version have to be reconciled by you and by Canal's own documentation, and the client library is the one piece that is version-locked.

This is the practical constraint to plan around. If your organisation runs Canal 1.1.7 or a different 1.1.x patch, the pairing in the table does not cover it, and if your Canal server is on a different major line the answer is not in this repository at all.

The repository also carries a Docker sample, a sample/CanalSharp.SimpleApp/ project, a docs/ directory with a zh subdirectory, and a Website published at canalsharp.azurewebsites.net which the README marks as recommended, alongside the GitHub docs.

There is a separate note about the MySQL version being decided by Canal, which is short but load-bearing: a .NET team that assumes CanalSharp pins MySQL compatibility will find out otherwise, and it is better to learn that from the README than from a failed connection.

## The refactoring table is the most informative document in the repository

The README carries a section on refactoring progress, and the table is more revealing than any feature list would be.

The claim in the prose is that the refactored version now fully covers the old version, has higher performance and more elegant code, implements features the old version did not, and supports the latest Canal.

The table then says which of those things are true.

| Task                           | Status        |
|--------------------------------|---------------|
| protobuf 3 协议生成                | 已完成           |
| 对接 Canal                       | 已完成           |
| 数据订阅封装                         | TODO          |
| 集群支持(Service 集群和 Client 集tgi群) | 已完成           |
| 数据发送到Kafka                     | 直接通过 Canal 发送 |
| 数据发送到Redis                     | 直接通过 Canal 发送 |

Reading the statuses: protobuf 3 protocol generation is done, connecting to Canal is done, cluster support covering both the service cluster and the client cluster is done, and data subscription encapsulation is marked TODO.

The subscription encapsulation being marked TODO is the entry to read twice, because SubscribeAsync is part of the quick start. What it means is that the subscription layer has not been wrapped into a finished abstraction of its own, while the protocol, the connection and the cluster handling underneath are in place. The quick start still works, so this is a note about internal completeness rather than a missing feature, but it does tell you that the library's shape is still settling.

The last two rows are the ones that save a reader time. Sending data to Kafka and sending data to Redis are both marked as sent directly through Canal. So CanalSharp is not a pipeline component that writes to a message broker or a cache; those destinations are Canal's own responsibility. If you were expecting the .NET library to publish to Kafka for you, that expectation is wrong, and the table says so before you write the code.

So the picture the table paints is: a rewritten client, on a modern protocol, with cluster support, where the downstream distribution is Canal's job and the subscription abstraction is the piece still marked as work in progress.

## Where CanalSharp is the wrong tool

The first wrong-tool case is a team that wants change data capture without a Canal server. CanalSharp is a client, and the README is explicit that Canal is the CDC component that reads the MySQL binlog. If you want binlog events in your .NET service and you do not already have a Canal deployment, you are starting from the wrong end: the capture side, its configuration, its instance and destination model, and its own operational burden all live in Canal.

The second case is a team that expects the library to fan out to brokers. The refactoring table settles it, and the answer is no. If your architecture needs every change event landing in Kafka regardless of which service consumes it, then Canal is the component that does that, and CanalSharp becomes a consumer of one destination rather than a central pipeline.

The third case is a project on a modern .NET runtime that expects current package conventions. The topic tags include netstandard20, so the library targets .NET Standard 2.0, and the package is distributed as Install-Package CanalSharp, which is the older NuGet console syntax rather than a dotnet add package instruction. That works, but it signals a project whose packaging predates the current CLI workflow.

The fourth case is a team that needs to move quickly on protocol changes. The recent release tags stop at v1.2.0 in February 2023, while the repository is being pushed to as of 2026-10-13. The README states that the refactored version supports the latest Canal, so the capability is in the source, but if you want to consume a tagged artefact from NuGet you may be looking at a 2023 build while the work is on main.

There is also a support boundary to note. The README asks for feedback through an Issue, asks contributors to submit pull requests, and provides a documentation site and a GitHub docs directory, with the docs in a zh subdirectory and the website recommended. The project also carries both code-of-conduct.md and code-of-conduct.zh-CN.md, a renovate.json for dependency updates, a CanalSharp.sln with a DotSettings file, and separate src/, test/, build/, sample/ and assets/ directories. So there is real project infrastructure, but the developer-facing documentation is Chinese-first.

On licence, Apache-2.0 is permissive and imposes no copyleft obligation on code that merely uses the library, which for an infrastructure client linking against a vendor protocol is the uncomplicated case. The MySQL binlog format that the whole chain depends on is a separate matter governed by Oracle's licence, and a legal review of a binlog-based pipeline should look at that rather than at the Apache grant.

## Conclusion

CanalSharp suits a .NET team that already runs a Canal server and needs MySQL change events inside a .NET service, because the client speaks Canal's protobuf protocol and the connection, subscribe and pull steps are three short calls. It does not suit a team that wants a database change feed without running Canal itself, since CanalSharp is a client and not a capture agent, and it does not suit a project that expects the Kafka and Redis paths to be handled by the library, since the refactoring table lists those as sent directly by Canal. Before adopting, check the version table, which pairs CanalSharp 1.2.0 with Canal 1.1.6 and leaves the MySQL version to Canal, and confirm your Canal server runs that version.

## FAQ

### What is CanalSharp?

CanalSharp is the .NET client for Canal, the open source Alibaba project for incremental subscription and consumption of MySQL database binlogs. CanalSharp connects to a Canal server, subscribes, and lets a .NET application pull the decoded change events.

### How do I install CanalSharp?

Install it from NuGet with Install-Package CanalSharp. The package targets .NET Standard 2.0 and the repository carries the solution under the main branch.

### Which versions of Canal and MySQL does CanalSharp support?

The README lists one pairing, CanalSharp 1.2.0 with Canal 1.1.6, and states that the MySQL version is determined by Canal. The recent release tags are v1.2.0 from 2023-02-27, v1.1.0 from 2020-11-16 and v1.0.0 from 2020-11-03.

### How do I get change events with CanalSharp?

Create a SimpleCanalConnection with a SimpleCanalOptions holding the host, port and destination number, call ConnectAsync and SubscribeAsync, then pull batches with GetAsync, for example await conn.GetAsync(1024). The consumption model is pull based, so your application owns the loop.

### Does CanalSharp send data to Kafka or Redis?

No. The refactoring table in the README marks sending data to Kafka and sending data to Redis as handled directly by Canal, not by the client library. CanalSharp is a consumer of a Canal destination rather than a pipeline component.

### What license is CanalSharp released under?

CanalSharp is released under the Apache-2.0 license, with the LICENSE file at the root of the repository. The project is a member project of the .NET Core Community and its primary language is C#.

## Sources

- [dotnetcore/CanalSharp on GitHub](https://github.com/dotnetcore/CanalSharp)
- [Issues](https://github.com/dotnetcore/CanalSharp/issues)
- [License: Apache-2.0](https://github.com/dotnetcore/CanalSharp/blob/main/LICENSE)
- [README](https://github.com/dotnetcore/CanalSharp/blob/main/README.md)
- [Releases](https://github.com/dotnetcore/CanalSharp/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dotnetcore-canalsharp