你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 .NET 的 Azure 架构注册表 Apache Avro 客户端库 - 版本 1.0.0

项目
04/23/2023

Azure 架构注册表是由 Azure 事件中心托管的架构存储库服务，提供架构存储、版本控制和管理。此包提供 Avro 序列化程序，能够序列化和反序列化包含架构注册表架构标识符和 Avro 序列化数据的有效负载。

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure 架构注册表 Apache Avro 库：

dotnet add package Microsoft.Azure.Data.SchemaRegistry.ApacheAvro

先决条件

如果需要创建事件中心命名空间，可以使用 Azure 门户或Azure PowerShell。

可以使用 Azure PowerShell 通过以下命令创建事件中心命名空间：

New-AzEventHubNamespace -ResourceGroupName myResourceGroup -NamespaceName namespace_name -Location eastus

验证客户端

若要与 Azure 架构注册表服务交互，需要创建架构注册表客户端类的实例。若要创建此客户端，需要 Azure 资源凭据和事件中心命名空间主机名。

获取凭据

若要获取凭据并开始与 Azure 资源交互，请参阅此处的快速入门指南。

获取事件中心命名空间主机名

最简单的方法是使用 Azure 门户并导航到事件中心命名空间。在“概述”选项卡中，你将看到 Host name。复制此字段中的值。

创建 SchemaRegistryClient

获得 Azure 资源凭据和事件中心命名空间主机名后，可以创建 SchemaRegistryClient。还需要 Azure.Identity 包来创建凭据。

// Create a new SchemaRegistry client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
// For more information on Azure.Identity usage, see: https://github.com/Azure/azure-sdk-for-net/blob/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro_1.0.0/sdk/identity/Azure.Identity/README.md
var schemaRegistryClient = new SchemaRegistryClient(fullyQualifiedNamespace: fullyQualifiedNamespace, credential: new DefaultAzureCredential());

关键概念

序列化程序

此库提供与事件交互的EventData序列化程序 SchemaRegistryAvroSerializer。 SchemaRegistryAvroSerializer 利用 SchemaRegistryClient 使用用于序列化数据的架构的架构 ID 来扩充 EventData 事件。

此序列化程序需要 Apache Avro 库。此序列化程序接受的有效负载类型包括 GenericRecord 和 ISpecificRecord。

示例

下面显示了通过 SchemaRegistryAvroSerializer提供的内容的示例。有同步和异步方法可用于这些操作。这些示例使用以下架构创建的生成的 Apache Avro 类 Employee.cs ：

{
   "type" : "record",
    "namespace" : "TestSchema",
    "name" : "Employee",
    "fields" : [
        { "name" : "Name" , "type" : "string" },
        { "name" : "Age", "type" : "int" }
    ]
}

有关使用 Apache Avro 库生成类的详细信息，请参阅 Avro C# 文档。

使用事件中心 EventData 模型序列化和反序列化数据

若要使用 Avro 信息序列化 EventData 实例，可以执行以下操作：

var serializer = new SchemaRegistryAvroSerializer(client, groupName, new SchemaRegistryAvroSerializerOptions { AutoRegisterSchemas = true });

var employee = new Employee { Age = 42, Name = "Caketown" };
EventData eventData = (EventData) await serializer.SerializeAsync(employee, messageType: typeof(EventData));

// the schema Id will be included as a parameter of the content type
Console.WriteLine(eventData.ContentType);

// the serialized Avro data will be stored in the EventBody
Console.WriteLine(eventData.EventBody);

// construct a publisher and publish the events to our event hub
var fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like something.servicebus.windows.net) >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var credential = new DefaultAzureCredential();
await using var producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential);
await producer.SendAsync(new EventData[] { eventData });

反序列化 EventData 正在使用的事件：

// construct a consumer and consume the event from our event hub
await using var consumer = new EventHubConsumerClient(EventHubConsumerClient.DefaultConsumerGroupName, fullyQualifiedNamespace, eventHubName, credential);
await foreach (PartitionEvent receivedEvent in consumer.ReadEventsAsync())
{
    Employee deserialized = (Employee) await serializer.DeserializeAsync(eventData, typeof(Employee));
    Console.WriteLine(deserialized.Age);
    Console.WriteLine(deserialized.Name);
    break;
}

还可以使用泛型方法来序列化和反序列化数据。如果不在 Avro 序列化程序上构建库，这可能更方便，因为不必担心泛型的病毒性：

var serializer = new SchemaRegistryAvroSerializer(client, groupName, new SchemaRegistryAvroSerializerOptions { AutoRegisterSchemas = true });

var employee = new Employee { Age = 42, Name = "Caketown" };
EventData eventData = await serializer.SerializeAsync<EventData, Employee>(employee);

// the schema Id will be included as a parameter of the content type
Console.WriteLine(eventData.ContentType);

// the serialized Avro data will be stored in the EventBody
Console.WriteLine(eventData.EventBody);

同样，若要反序列化：

Employee deserialized = await serializer.DeserializeAsync<Employee>(eventData);
Console.WriteLine(deserialized.Age);
Console.WriteLine(deserialized.Name);

直接使用 `MessageContent` 序列化和反序列化数据

还可以使用 MessageContent进行序列化和反序列化。如果未与使用 MessageContent的任何消息传递库集成，请使用此选项。

var serializer = new SchemaRegistryAvroSerializer(client, groupName, new SchemaRegistryAvroSerializerOptions { AutoRegisterSchemas = true });
MessageContent content = await serializer.SerializeAsync<MessageContent, Employee>(employee);

Employee deserializedEmployee = await serializer.DeserializeAsync<Employee>(content);

疑难解答

如果在与架构注册表服务通信时遇到错误，这些错误将作为 RequestFailedException 引发。序列化程序只会在序列化) 时第一次遇到架构 (时与服务通信，或者在反序列化) 时 (架构 ID。与无效内容类型相关的任何错误都将作为 FormatException引发。与无效架构相关的错误将作为 Exception引发，并且属性 InnerException 将包含从 Apache Avro 库引发的基础异常。此类错误通常在测试期间捕获，不应在代码中处理。与不兼容架构相关的任何错误都将作为 Exception 引发，并将 InnerException 属性设置为 Apache Avro 库中的基础异常。

后续步骤

有关其他信息，请参阅 Azure 架构注册表。

贡献

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 cla.microsoft.com。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

曝光数

通过