Updated on
NewId is a .NET library that generates unique IDs we can sort by the time we created them. Each ID is 128 bits, the size of a Guid, and is built from a timestamp, a worker ID taken from the machine’s network card and a sequence counter.
We install the NewId package and call NewId.NextGuid() or NewId.NextSequentialGuid() where we used to call Guid.NewGuid(). Which of the two we want depends on how our database sorts GUIDs.
Let’s dive in!
Why Might We Need Sortable Unique IDs in .NET?
We all know there are two main approaches when it comes to generating IDs for entities in our projects: either an int or Guid (globally unique identifier) values. But both approaches have their problems. Let’s explore them in an API that deals with customer orders.
Integers as Primary Keys
First, let’s look at integers as primary keys:
public class Order
{
public int Id { get; set; }
public required string CustomerName { get; set; }
public required List<string> Products { get; set; }
public required decimal TotalAmount { get; set; }
}
We create an Order class and use an int as the ID.Â
With this approach, we leave the ID generation to the database provider. The good here is that we get short, nice, and sequential IDs. But, with database-generated primary keys, we get one major downside – our applications get harder to scale up. With large amounts of insert statements, generating new primary keys in the database quickly becomes a bottleneck.
Storing entities over several different databases and maintaining unique int IDs is also hard. Another thing is that we might leak sensitive information to our competitors – do we want to have sequential IDs and let people know exactly how many orders we have?
Globally Unique Identifiers as Primary Keys
The other popular approach is to use Guid values. We change the Order‘s ID from int to Guid:
public class Order
{
public required Guid Id { get; set; }
public required string CustomerName { get; set; }
public required List<string> Products { get; set; }
public required decimal TotalAmount { get; set; }
}
Then our OrderService class sets the ID when it creates an order. The block is an excerpt: the IUnitOfWork and IOrderService interfaces and the OrderForCreationDto and OrderDto classes it uses are in the sample project:
public class OrderService(IUnitOfWork unitOfWork) : IOrderService
{
public async Task<OrderDto> CreateAsync(
OrderForCreationDto orderForCreationDto,
CancellationToken cancellationToken = default)
{
var order = new Order
{
Id = Guid.NewGuid(),
CustomerName = orderForCreationDto.CustomerName,
Products = orderForCreationDto.Products,
TotalAmount = orderForCreationDto.TotalAmount,
};
unitOfWork.OrderRepository.Insert(order);
await unitOfWork.SaveChangesAsync(cancellationToken);
return new OrderDto
{
Id = order.Id,
CustomerName = order.CustomerName,
Products = order.Products,
TotalAmount = order.TotalAmount,
};
}
// omitted for brevity
}
Our project is based on the Onion architecture, so our service takes in a DTO object, processes it, and inserts the entity into the database using a repository.
With this approach, the OrderService class is responsible for generating the primary key value. The biggest plus here is that we can use Guid.NewGuid() and get unique IDs with zero effort. Having unique, but random, IDs makes scaling our application to several databases very easy. But this is their greatest problem as well: it makes our data unsortable based on the primary keys alone and can lead to potential indexing problems. This type of primary key also takes up four times as much space as a regular integer when stored in the database.
And this is where the NewId library comes into play. By utilizing it, we combine the good sides of both int and Guid primary keys and eliminate some of the downsides.
What Is the NewId Library?
The NewId library is a NuGet package that generates unique IDs we can sort by creation time. Chris Patterson, the author of MassTransit, wrote it, and its types live in the MassTransit namespace. It ships as a separate package, though, with no dependencies and an Apache-2.0 licence.
Every NewId is 128 bits, the size of a Guid, and three parts go into it. The first is a timestamp. Then comes a worker ID, which NewId reads from the machine’s network card (MAC) address, falling back to a hash of the host name. The last part is a sequence counter that keeps IDs in order when we create several within the same clock tick.
NewId adds the process ID only if we call NewId.SetProcessIdProvider() before the first ID, and it replaces the last two bytes of the MAC address. It helps when several instances of our application share one machine, and so one worker ID.
The design borrows from Twitter’s Snowflake and from flake, an Erlang library.
MassTransit itself is commercial from version 9 on. NewId 4.0.1, the newest release since January 2023, carries the Apache-2.0 licence.
Before we start generating IDs, we need to install the NewId package:
dotnet add package NewId
Using the dotnet add package command, we install the library.
Now that we have things ready, let’s start using the package to generate IDs.
How Do We Generate IDs With the NewId Type?
To generate our IDs, we use the NewId type. It is a struct in the MassTransit namespace, and three of its static methods matter here.Â
First, the Next() method returns a new NewId value:
00070000-ac11-0242-3d9b-08dc45bed613 00070000-ac11-0242-c9d3-08dc45bed614 00070000-ac11-0242-cafd-08dc45bed614 00070000-ac11-0242-cb2e-08dc45bed614 00070000-ac11-0242-cb69-08dc45bed614
Next, the NextGuid() method returns a new Guid value:
00070000-ac11-0242-df20-08dc45bed614 00070000-ac11-0242-0c11-08dc45bed615 00070000-ac11-0242-0d30-08dc45bed615 00070000-ac11-0242-0d46-08dc45bed615 00070000-ac11-0242-0d58-08dc45bed615
Finally, the NextSequentialGuid() method returns a Guid with its bytes in a different order:
08dc45be-d615-19b5-0242-ac1100070000 08dc45be-d615-1b01-0242-ac1100070000 08dc45be-d615-1b46-0242-ac1100070000 08dc45be-d615-1b66-0242-ac1100070000 08dc45be-d615-1ba4-0242-ac1100070000
Next() and NextGuid() print the same pattern: the worker ID sits at the front and the timestamp at the end. NextSequentialGuid() turns that around and puts the timestamp first. NextGuid() and NextSequentialGuid() return a Guid, so our Order class needs no change. If we opt for Next(), we either change the ID type of Order or convert the value with ToGuid() or ToSequentialGuid().
Let’s use one of them:
using MassTransit;
public class OrderService(IUnitOfWork unitOfWork) : IOrderService
{
public async Task<OrderDto> CreateAsync(
OrderForCreationDto orderForCreationDto,
CancellationToken cancellationToken = default)
{
var order = new Order
{
Id = NewId.NextSequentialGuid(),
CustomerName = orderForCreationDto.CustomerName,
Products = orderForCreationDto.Products,
TotalAmount = orderForCreationDto.TotalAmount,
};
unitOfWork.OrderRepository.Insert(order);
await unitOfWork.SaveChangesAsync(cancellationToken);
return new OrderDto
{
Id = order.Id,
CustomerName = order.CustomerName,
Products = order.Products,
TotalAmount = order.TotalAmount,
};
}
// omitted for brevity
}
In our OrderService class, where we generate the IDs, we replace Guid.NewGuid() with NewId.NextSequentialGuid(). Apart from the using MassTransit; line, that is the only change we need.
Our sample exposes the orders through minimal API endpoints, so let’s run it and add some orders:
[
{
"id": "08dc45c0-b5b5-0d5d-5811-22b038790000",
"customerName": "Marcel Waters",
"products": [
"Piano"
],
"totalAmount": 599.99
},
{
"id": "08dc45c0-d6f4-fbed-5811-22b038790000",
"customerName": "Elizabeth Doyle",
"products": [
"Vase",
"Mirror",
"Blanket"
],
"totalAmount": 49.39
},
{
"id": "08dc45c0-f143-a9f9-5811-22b038790000",
"customerName": "Rayford Lopez",
"products": [
"Headphones",
"Microphone"
],
"totalAmount": 86.06
}
]
We can see that our entities now have unique yet not completely random identifiers that can be sorted. If you want a standardized, sortable identifier instead of a library-specific one, the ULID generator produces ULIDs that encode a timestamp the same way and converts them to and from a GUID.
Which NewId Method Keeps SQL Server Inserts in Order?
For a SQL Server uniqueidentifier column, NewId.NextGuid() is the method that keeps new rows in creation order. NextSequentialGuid() is the one to use when the IDs are compared as .NET Guid values or as text.
The two orderings read a GUID from opposite ends. Guid.CompareTo() and a plain string sort start at the front. SQL Server starts with the last six bytes. The Microsoft documentation for SqlGuid, the .NET type that compares GUIDs the way SQL Server does, says it “treats the last 6 bytes as the most significant ones in comparisons.”
NewId writes the same timestamp in both methods and only moves it. NextGuid() puts it at the end, where SQL Server looks first. NextSequentialGuid() puts it at the front, where Guid.CompareTo() and a string sort look.
If we pick the wrong method, the IDs stay unique, but new rows land in the index in an order that has nothing to do with time.
Tests in the sample check this on 1,000 IDs per method:
using System.Data.SqlTypes;
using MassTransit;
namespace GenerateUniqueIDsWithNewId.Tests;
public class NewIdOrderingTests
{
private static List<Guid> Generate(Func<Guid> next, int count = 1000) =>
Enumerable.Range(0, count).Select(_ => next()).ToList();
[Fact]
public void WhenNextGuidIsUsed_ThenSqlServerOrderMatchesCreationOrder()
{
var ids = Generate(NewId.NextGuid);
Assert.Equal(ids, ids.OrderBy(id => new SqlGuid(id)));
}
[Fact]
public void WhenNextSequentialGuidIsUsed_ThenGuidAndTextOrderMatchCreationOrder()
{
var ids = Generate(NewId.NextSequentialGuid);
Assert.Equal(ids, ids.OrderBy(id => id));
Assert.Equal(ids, ids.OrderBy(id => id.ToString(), StringComparer.Ordinal));
}
}
Both tests pass. SqlGuid comes with .NET in System.Data.SqlTypes, so they need no database, and that is also their limit: they prove the order SqlGuid reports, and we haven’t run them against a SQL Server instance.
The opposite pairings don’t hold. In our run, NextGuid() values sorted as Guid or as text came out of creation order, and so did NextSequentialGuid() values sorted the SQL Server way.
Should We Use NewId or Guid.CreateVersion7?
Since .NET 9, Guid.CreateVersion7() gives us time-ordered GUIDs with no package at all. It follows the version 7 format from RFC 9562: a Unix timestamp in milliseconds at the front, and random bits after it.
That makes it a fit for the same cases as NextSequentialGuid(), IDs compared as Guid values or as text, as long as we create them at least a millisecond apart. Inside one millisecond the order is random. In our run, 1,000 back-to-back calls came out of order, while 50 calls spaced 2 milliseconds apart sorted correctly.
On SQL Server, the built-in method doesn’t keep that order. Its timestamp sits at the front, and the last six bytes, which SQL Server compares first, are random.
So for SQL Server keys, NewId.NextGuid() is the generator to use. Elsewhere, CreateVersion7() saves us a dependency, and NewId is worth adding only when we create many IDs per millisecond and need them in exact order.
A third test checks version 7, waiting 2 milliseconds between IDs:
[Fact]
public void WhenCreateVersion7IsUsedOncePerMillisecond_ThenGuidOrderMatchesButSqlServerOrderDoesNot()
{
var ids = Generate(() =>
{
Thread.Sleep(2);
return Guid.CreateVersion7();
}, 50);
Assert.Equal(ids, ids.OrderBy(id => id));
Assert.NotEqual(ids, ids.OrderBy(id => new SqlGuid(id)));
}
The test goes in the same class as the first two, since it calls Generate(), and it passes on .NET 11. The NotEqual check holds because the last six bytes of each ID are random, so sorting 50 IDs by them gives back the creation order only by an enormous coincidence.
Here is where each generator from this article keeps its order:
| Method | Needs a package | In order as Guid or text | In order in SQL Server (SqlGuid) | Several IDs in one millisecond |
|---|---|---|---|---|
Guid.NewGuid() | No | No | No | Random, no order at all |
NewId.NextGuid() | NewId | No | Yes | In order |
NewId.NextSequentialGuid() | NewId | Yes | No | In order |
Guid.CreateVersion7() | No (.NET 9 and later) | Yes, across milliseconds | No | Random order |
For a SQL Server key, NewId.NextGuid() is the only generator in this table that keeps the order. For a store that sorts GUIDs from the front, Guid.CreateVersion7() does the job without a package, unless several IDs created in the same millisecond must stay in order.
When Should We Not Use NewId?
NewId makes sortable unique IDs easy, but there are a few scenarios where we should avoid it. The library’s readme puts the main one plainly: “The generated ids are predictable by design.” Anyone who knows the algorithm and has seen one ID can guess the IDs around it.
The same readme warns about a second thing. Every ID exposes the machine that created it, through its MAC address, and the time it was created. If that information is sensitive for our application, these IDs shouldn’t be visible to users.
So we don’t use NewId-generated IDs where unpredictability matters. We shouldn’t use them for passwords, security tokens, or any other value someone must not be able to guess. If we do, an attacker who sees one ID has a head start on the next.
Conclusion
In this article, we looked at the limits of integer and Guid primary keys, and at NewId, which builds unique IDs from a timestamp, a worker ID and a sequence counter so they sort by creation time.
For SQL Server keys, NewId.NextGuid() keeps the order. When GUIDs are compared from the front, NewId.NextSequentialGuid() works, and so does the built-in Guid.CreateVersion7() as long as we don’t need exact order within a millisecond. Whichever we pick, the IDs are at least partly predictable, so they stay out of anything security-related.
If you want to learn more about the Guid type itself, check out our article on working with Guid in C#.
Tested with .NET 11 (SDK 11.0.100, runtime 11.0.0), NewId 4.0.1 and xUnit 2.9.3.
