在 .NET SDK 中转换会话令牌格式Convert session token formats in .NET SDK

适用于： SQL API

本文介绍如何在不同会话令牌格式之间进行转换，以确保 SDK 版本之间的兼容性。This article explains how to convert between different session token formats to ensure compatibility between SDK versions.

备注

默认情况下，SDK 会自动跟踪会话令牌，并会使用最新的会话令牌。By default, the SDK keeps track of the session token automatically and it will use the most recent session token. 有关详细信息，请访问利用会话令牌。For more information, please visit Utilize session tokens. 本文中的说明仅适用于以下情况：The instructions in this article only apply with the following conditions:

  • Azure Cosmos DB 帐户使用会话一致性。Your Azure Cosmos DB account uses Session consistency.
  • 你手动管理会话令牌。You are managing the session tokens are manually.
  • 你同时使用了多个版本的 SDK。You are using multiple versions of the SDK at the same time.

会话令牌格式Session token formats

有两种会话令牌格式：“简单”和“向量”。There are two session token formats: simple and vector. 这两种格式不能互换，因此，在将会话令牌传递到不同版本的客户端应用程序时，应转换格式。These two formats are not interchangeable so, the format should be converted when passing to the client application with different versions.

  • .NET SDK V1（Microsoft.Azure.DocumentDB - 版本 1.x）使用“简单”会话令牌格式。The simple session token format is used by the .NET SDK V1 (Microsoft.Azure.DocumentDB -version 1.x)
  • .NET SDK V2（Microsoft.Azure.DocumentDB - 版本 2.x）使用“向量”会话令牌格式。The vector session token format is used by the .NET SDK V2 (Microsoft.Azure.DocumentDB -version 2.x)

简单会话令牌Simple session token

简单会话令牌采用此格式：{pkrangeid}:{globalLSN}A simple session token has this format: {pkrangeid}:{globalLSN}

向量会话令牌Vector session token

向量会话令牌采用以下格式：{pkrangeid}:{Version}#{GlobalLSN}#{RegionId1}={LocalLsn1}#{RegionId2}={LocalLsn2}....#{RegionIdN}={LocalLsnN}A vector session token has the following format: {pkrangeid}:{Version}#{GlobalLSN}#{RegionId1}={LocalLsn1}#{RegionId2}={LocalLsn2}....#{RegionIdN}={LocalLsnN}

转换为“简单”会话令牌Convert to Simple session token

若要使用 .NET SDK V1 将会话令牌传递给客户端，请使用“简单”会话令牌格式。To pass a session token to client using .NET SDK V1, use a simple session token format. 例如，使用下面的示例代码来转换会话令牌。For example, use the following sample code to convert it.

private static readonly char[] SegmentSeparator = (new[] { '#' });
private static readonly char[] PkRangeSeparator = (new[] { ':' });

// sessionTokenToConvert = session token from previous response
string[] items = sessionTokenToConvert.Split(PkRangeSeparator, StringSplitOptions.RemoveEmptyEntries);
string[] sessionTokenSegments = items[1].Split(SessionTokenHelpers.SegmentSeparator, StringSplitOptions.RemoveEmptyEntries);

string sessionTokenInSimpleFormat;

if (sessionTokenSegments.Length == 1)
{
    // returning the same token since it already has the correct format
    sessionTokenInSimpleFormat = sessionTokenToConvert;
}
else
{
    long version = 0;
    long globalLSN = 0;

    if (!long.TryParse(sessionTokenSegments[0], out version)
        || !long.TryParse(sessionTokenSegments[1], out globalLSN))
    {
        throw new ArgumentException("Invalid session token format", sessionTokenToConvert);
    }

    sessionTokenInSimpleFormat = string.Format("{0}:{1}", items[0], globalLSN);
}

转换为“向量”会话令牌Convert to Vector session token

若要使用 .NET SDK V2 将会话令牌传递给客户端，请使用“向量”会话令牌格式。To pass a session token to client using .NET SDK V2, use the vector session token format. 例如，使用下面的示例代码来转换会话令牌。For example, use the following sample code to convert it.


private static readonly char[] SegmentSeparator = (new[] { '#' });
private static readonly char[] PkRangeSeparator = (new[] { ':' });

// sessionTokenToConvert = session token from previous response
string[] items = sessionTokenToConvert.Split(PkRangeSeparator, StringSplitOptions.RemoveEmptyEntries);
string[] sessionTokenSegments = items[1].Split(SegmentSeparator, StringSplitOptions.RemoveEmptyEntries);

string sessionTokenInVectorFormat;

if (sessionTokenSegments.Length == 1)
{
    long globalLSN = 0;
    if (long.TryParse(sessionTokenSegments[0], out globalLSN))
    {
        sessionTokenInVectorFormat = string.Format("{0}:-2#{1}", items[0], globalLSN);
    }
    else
    {
        throw new ArgumentException("Invalid session token format", sessionTokenToConvert);
    }
}
else
{
    // returning the same token since it already has the correct format
    sessionTokenInVectorFormat = sessionTokenToConvert;
}

后续步骤Next steps

请阅读以下文章：Read the following articles: