A high-performance Snowflake ID generator supporting multiple algorithms (drift, traditional, lock-free) for distributed systems. Supports .NET Framework 4.6.1-4.8, .NET 6-10, .NET Standard 2.0+, and .NET Standard 2.1.
High-performance distributed ID generator based on Twitter's Snowflake algorithm for .NET. Supports three implementation methods for different scenarios.
using Jordium.Framework.Snowflake;
// Create ID generator
var options = new IDGeneratorOptions
{
WorkerId = 1, // Worker ID (0-31)
DataCenterId = 1, // Datacenter ID (0-31)
Method = 1 // Algorithm version (1=Drift, 2=Traditional, 3=Lock-free)
};
var generator = new DefaultIDGenerator(options);
// Generate ID
long id = generator.NewLong();
Console.WriteLine($"Generated ID: {id}");
Advanced Configuration
var options = new IDGeneratorOptions
{
WorkerId = 1,
DataCenterId = 1,
Method = 1,
// Custom bit allocation
WorkerIdBitLength = 5, // Worker ID bits (default 5)
DataCenterIdBitLength = 5, // Datacenter ID bits (default 5)
SeqBitLength = 12, // Sequence bits (default 12)
// Base time (for timestamp calculation)
BaseTime = new DateTime(2020, 1, 1, 0, 0, 0, DateTimeKind.Utc),
// Sequence range
MinSeqNumber = 0,
MaxSeqNumber = 4095, // 2^12 - 1
// Drift algorithm specific: max drift count
TopOverCostCount = 2000
};
var generator = new DefaultIDGenerator(options);
ASP.NET Core Dependency Injection
// Program.cs or Startup.cs
public void ConfigureServices(IServiceCollection services)
{
// Register as singleton
services.AddSingleton<IIDGenerator>(sp =>
{
var options = new IDGeneratorOptions
{
WorkerId = 1,
DataCenterId = 1,
Method = 1
};
return new DefaultIDGenerator(options);
});
}
// Use in Controller
public class OrderController : ControllerBase
{
private readonly IIDGenerator _idGenerator;
public OrderController(IIDGenerator idGenerator)
{
_idGenerator = idGenerator;
}
[HttpPost]
public IActionResult CreateOrder()
{
long orderId = _idGenerator.NewLong();
// Use generated ID
return Ok(new { OrderId = orderId });
}
}
Note: Actual performance depends on multiple factors:
CPU model and frequency
Memory speed
OS scheduling
.NET runtime version
Debug/Release mode
System load
The above data are reference values from typical test environments.
Real deployment environments may have ��30% variations.
We recommend running benchmarks on actual hardware for accurate data.
ID Structure
Standard 64-bit Snowflake ID
����������������������������������������������������������������������������������������������������������������������
�� Timestamp(41bit)�� DC ID (5bit)�� Worker(5bit)�� Sequence(12) ��
�������������������������������������ة��������������������������ة��������������������������ة�����������������������������
~69 years 32 DCs 32 Workers 4096/ms
Bit Allocation Examples
Config
Worker Bits
DC Bits
Seq Bits
Capacity
Standard
5
5
12
32 DC �� 32 Worker �� 4096/ms
Multi-DC
4
6
12
64 DC �� 16 Worker �� 4096/ms
Multi-Worker
6
4
12
16 DC �� 64 Worker �� 4096/ms
Low Concurrency
5
5
10
32 DC �� 32 Worker �� 1024/ms
Constraints:
Worker bits + DC bits + Seq bits �� 22
Seq bits �� 12
FAQ
1. How to Choose WorkerId?
Recommended Approaches:
Monolithic app: Fixed value (e.g., 1)
Microservices: Hash service name and modulo
K8s: Use Pod ordinal (StatefulSet)
Config center: Fetch from configuration service
// Example: Get from environment variable
var workerId = Environment.GetEnvironmentVariable("WORKER_ID");
var options = new IDGeneratorOptions
{
WorkerId = ushort.Parse(workerId ?? "1"),
DataCenterId = 1,
Method = 1
};
2. How to Handle Clock Rollback?
Algorithm
Handling
Method 1
Uses reserved sequence 1-4, supports up to 4 rollbacks
Method 2
Throws exception directly
Method 3
Short time (< 1s) sleeps and waits, long time throws exception
3. How to Ensure Distributed Uniqueness?
Ensure each machine has a unique WorkerId and DataCenterId combination:
// Wrong Example ❌
// Server 1: WorkerId=1, DataCenterId=1
// Server 2: WorkerId=1, DataCenterId=1 ← Will produce duplicate IDs
// Correct Example ✅
// Server 1: WorkerId=1, DataCenterId=1
// Server 2: WorkerId=2, DataCenterId=1
// Server 3: WorkerId=1, DataCenterId=2
4. What if Performance is Below Expectations?
Checklist:
✅ Use singleton pattern (AddSingleton)
✅ Avoid frequent creation of DefaultIDGenerator instances
✅ Choose Method 1 for single-machine high concurrency
