Microsoft.Azure.Core.NewtonsoftJson 2.0.0

Newtonsoft.Json 支持针对 .NET 的 Azure Core 共享客户端库

Azure.Core 包 包含由最新 Azure SDK 客户端库共享的类型。此 Newtonsoft.Json 兼容库

• 包含依赖 Newtonsoft.Json 包的转换器。
• 启用使用 Newtonsoft.Json 对自定义模型类型进行序列化和反序列化。这些自定义模型类型可用于以下客户端库
  • Azure.DigitalTwins.Core
  • Azure.Search/Documents

入门指南

安装包

使用 .NET CLI 从 NuGet 安装此包

dotnet add package Microsoft.Azure.Core.NewtonsoftJson

关键概念

本支持包包含 NewtonsoftJsonObjectSerializer 类，可以将该类传递给一些 Azure SDKs 的客户端选项类，如下面的示例所示。

如果您未传递自己的 JsonSerializerSettings，以下转换器将自动添加到 NewtonsoftJsonObjectSerializer 中。

• NewtonsoftJsonETagConverter 用于转换 Azure.ETag 属性。

请参阅下面的示例 使用默认转换器，以获得具有此默认列表的 JsonSerializerSettings 实例，然后您可以按需修改。

示例

以下示例使用了 Azure.Search.Documents 包 来演示如何反序列化搜索结果。有关更多信息和使用 Azure.Search.Documents 的示例，请参阅其 README。

反序列化模型

考虑一个包含关于电影信息的自定义模型类。

public class Movie
{
    [JsonProperty("uuid")]
    public string Id { get; private set; } = Guid.NewGuid().ToString();

    public string Title { get; set; }

    public string Description { get; set; }

    public float Rating { get; set; }
}

我们的 Azure Cognitive Search 索引使用 camelCase 字段定义，而 Id 字段实际上定义为 "uuid"；但是，我们可以设置 JsonSerializerSettings.ContractResolver 属性，如下所示，以提供一个符合习惯的模型，而无需为所有属性添加属性

// Get the Azure Cognitive Search endpoint and read-only API key.
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(Environment.GetEnvironmentVariable("SEARCH_API_KEY"));

// Create serializer options with default converters for Azure SDKs.
JsonSerializerSettings serializerSettings = NewtonsoftJsonObjectSerializer.CreateJsonSerializerSettings();

// Serialize property names using camelCase by default.
serializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();

SearchClientOptions clientOptions = new SearchClientOptions
{
    Serializer = new NewtonsoftJsonObjectSerializer(serializerSettings)
};

SearchClient client = new SearchClient(endpoint, "movies", credential, clientOptions);
Response<SearchResults<Movie>> results = client.Search<Movie>("Return of the King");

foreach (SearchResult<Movie> result in results.Value.GetResults())
{
    Movie movie = result.Document;

    Console.WriteLine(movie.Title);
    Console.WriteLine(movie.Description);
    Console.WriteLine($"Rating: {movie.Rating}\n");
}

在搜索大量电影索引时，可能会打印以下内容

The Lord of the Rings: The Return of the King
Gandalf and Aragorn lead the World of Men against Sauron's army to draw his gaze from Frodo and Sam as they approach Mount Doom with the One Ring.
Rating: 9.1

使用默认转换器

如果您使用默认构造函数实例化 NewtonsoftJsonObjectSerializer，则会自动添加像上面在 关键概念 中列出的常见 Azure SDKs 转换器。要修改这些默认设置，您可以根据以下示例创建一个新的 JsonSerializerSettings

JsonSerializerSettings serializerSettings = NewtonsoftJsonObjectSerializer.CreateJsonSerializerSettings();

// Serialize property names using camelCase by default.
serializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();

// Add converters as needed, for example, to convert movie genres to an enum.
serializerSettings.Converters.Add(new StringEnumConverter());

SearchClientOptions clientOptions = new SearchClientOptions
{
    Serializer = new NewtonsoftJsonObjectSerializer(serializerSettings)
};

您可以添加或删除转换器，设置 ContractResolver 或 JsonSerializerSettings 的其他任何成员。

贡献

本项目欢迎贡献和建议。大多数贡献都需要您同意一份贡献许可协议 (CLA)，申明您有权并且确实授予我们使用您的贡献的权利。有关详细信息，请访问 https://cla.microsoft.com。

当您提交拉取请求时，一个 CLA-bot 将自动确定您是否需要提供 CLA，并相应地装饰 PR（例如，标记、注释）。只需遵循 bot 提供的说明。您只需在每个使用我们的 CLA 的仓库中做一次。

本项目采用了 Microsoft 开放源代码行为准则。有关更多信息，请参阅 行为准则常见问题解答 或通过 [email protected] 联系我们，有任何额外的问题或评论。