# TraconId

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.traconid/
> Summary: TraconId: UUID version 7 generator for Tracon identifiers (RFC 9562).

<div class="api-provenance">Namespace Tracon · Assembly <code>Tracon.Abstractions.dll</code></div>

UUID version 7 generator for Tracon identifiers (RFC 9562).

```csharp
public static class TraconId
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.traconid/">TraconId</a></dd><dt>Inherited Members</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object.gettype">object.GetType()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.memberwiseclone">object.MemberwiseClone()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.tostring">object.ToString()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object)">object.Equals(object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object)">object.Equals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.referenceequals">object.ReferenceEquals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.gethashcode">object.GetHashCode()</a></dd></dl>

## Remarks

A UUIDv7 is time ordered: the first 48 bits are a Unix millisecond stamp.
This keeps B-tree indexes from fragmenting and makes `ORDER BY id`
return time order. It also avoids the central sequence bottleneck of
`bigserial`.

We use our own implementation instead of `Guid.CreateVersion7` from.NET 9. The reason: the package also targets `net8.0`, and storage keys
must be produced the same way on every target.

## Methods

### <a id="Tracon_TraconId_DeriveId_System_DateTimeOffset_System_String_"></a> DeriveId\(DateTimeOffset, string\)

Creates a UUIDv7 that depends only on its inputs: the same time stamp
and seed always produce the same identifier.

```csharp
public static Guid DeriveId(DateTimeOffset timestamp, string seed)
```

#### Parameters

`timestamp` [DateTimeOffset](https://learn.microsoft.com/dotnet/api/system.datetimeoffset)

The time stamp to embed. Must itself be stable across calls — a stored
creation time, never [DateTimeOffset.UtcNow](https://learn.microsoft.com/dotnet/api/system.datetimeoffset).

`seed` [string](https://learn.microsoft.com/dotnet/api/system.string)

The value the identifier is derived from.

#### Returns

 [Guid](https://learn.microsoft.com/dotnet/api/system.guid)

A time-ordered identifier that can be recomputed.

#### Remarks

For a write that must be re-drivable after a crash. Where
[TraconId.NewId](/api/tracon.traconid/#Tracon_TraconId_NewId) would mint a second identifier on a retry — and
so a second row — a derived one lets the retry land on exactly the row
the interrupted attempt was creating, without a table to remember what
that row was going to be.

Still a real UUIDv7, so it keeps the index locality
[TraconId.NewId](/api/tracon.traconid/#Tracon_TraconId_NewId) is chosen for: only the random bytes are replaced,
by a SHA-256 digest of `seed`. It is a derivation, not
a signature — the seed is not recoverable, but neither is it a secret.

### <a id="Tracon_TraconId_GetTimestamp_System_Guid_"></a> GetTimestamp\(Guid\)

Reads the time stamp back out of a UUIDv7.

```csharp
public static DateTimeOffset GetTimestamp(Guid id)
```

#### Parameters

`id` [Guid](https://learn.microsoft.com/dotnet/api/system.guid)

The UUIDv7 value.

#### Returns

 [DateTimeOffset](https://learn.microsoft.com/dotnet/api/system.datetimeoffset)

The time stamp embedded in the identifier.

#### Exceptions

 [ArgumentException](https://learn.microsoft.com/dotnet/api/system.argumentexception)

`id` is not a version 7 value.

### <a id="Tracon_TraconId_NewId"></a> NewId\(\)

Creates a new UUIDv7 stamped with the current time.

```csharp
public static Guid NewId()
```

#### Returns

 [Guid](https://learn.microsoft.com/dotnet/api/system.guid)

A time-ordered identifier.

### <a id="Tracon_TraconId_NewId_System_DateTimeOffset_"></a> NewId\(DateTimeOffset\)

Creates a UUIDv7 stamped with the given time.

```csharp
public static Guid NewId(DateTimeOffset timestamp)
```

#### Parameters

`timestamp` [DateTimeOffset](https://learn.microsoft.com/dotnet/api/system.datetimeoffset)

The time stamp to embed in the identifier.

#### Returns

 [Guid](https://learn.microsoft.com/dotnet/api/system.guid)

A time-ordered identifier.