New SDK - SchemaRegistry

sdk/schemaregistry/Azure.Data.SchemaRegistry/README.md

@@ -42,8 +42,13 @@ The simpliest way is to use the [Azure portal][azure_portal] and navigate to you
 Once you have the Azure resource credentials and the Event Hubs namespace hostname, you can create the [SchemaRegistryClient][schema_registry_client]. You'll also need the [Azure.Identity][azure_identity] package to create the credential.
 
 ```C# Snippet:CreateSchemaRegistryClient
-string connectionString = "<connection_string>";
-var client = new ConfigurationClient(connectionString);
+string endpoint = "<event_hubs_namespace_hostname>";
+var credentials = new ClientSecretCredential(
+    "<tenant_id>",
+    "<client_id>",
+    "<client_secret>"
+);
+var client = new SchemaRegistryClient(endpoint, credentials);
 ```
 
 ## Key concepts
@@ -73,26 +78,57 @@ The following shows examples of what is available through the SchemaRegistryClie
 Register a schema to be stored in the Azure Schema Registry.
 
 ```C# Snippet:RegisterSchema
-string connectionString = "<connection_string>";
-var client = new ConfigurationClient(connectionString);
+            string schemaName = "<schema_name>";
+            string groupName = "<schema_group_name>";
+            SerializationType schemaType = SerializationType.Avro;
+            // Example schema's content
+            string schemaContent = @"
+{
+   ""type"" : ""record"",
+    ""namespace"" : ""TestSchema"",
+    ""name"" : ""Employee"",
+    ""fields"" : [
+    { ""name"" : ""Name"" , ""type"" : ""string"" },
+    { ""name"" : ""Age"", ""type"" : ""int"" }
+    ]
+}";
+
+            Response<SchemaProperties> schemaProperties = client.RegisterSchema(groupName, schemaName, schemaType, schemaContent);
 ```
 
 ### Retrieve a schema ID
 
 Retrieve a previously registered schema ID from the Azure Schema Registry.
 
 ```C# Snippet:RetrieveSchemaId
-string connectionString = "<connection_string>";
-var client = new ConfigurationClient(connectionString);
+            string schemaName = "<schema_name>";
+            string groupName = "<schema_group_name>";
+            SerializationType schemaType = SerializationType.Avro;
+            // Example schema's content
+            string schemaContent = @"
+{
+   ""type"" : ""record"",
+    ""namespace"" : ""TestSchema"",
+    ""name"" : ""Employee"",
+    ""fields"" : [
+    { ""name"" : ""Name"" , ""type"" : ""string"" },
+    { ""name"" : ""Age"", ""type"" : ""int"" }
+    ]
+}";
+
+            Response<SchemaProperties> schemaProperties = client.GetSchemaId(groupName, schemaName, schemaType, schemaContent);
+            string schemaId = schemaProperties.Value.Id;
 ```
 
 ### Retrieve a schema
 
 Retrieve a previously registered schema's content from the Azure Schema Registry.
 
 ```C# Snippet:RetrieveSchema
-string connectionString = "<connection_string>";
-var client = new ConfigurationClient(connectionString);
+string schemaId = "<schema_id>";
+
+Response<SchemaProperties> schemaProperties = client.GetSchema(schemaId);
+string schemaContent = schemaProperties.Value.Content;
 ```
 
 ## Contributing

sdk/schemaregistry/Azure.Data.SchemaRegistry/tests/Samples/SchemaRegistryClientSamples.ReadmeSnippets.cs → sdk/schemaregistry/Azure.Data.SchemaRegistry/tests/Samples/SchemaRegistryReadmeSnippets.cs

@@ -7,9 +7,7 @@
 
 namespace Azure.Data.SchemaRegistry.Tests.Samples
 {
-#pragma warning disable SA1649 // File name should match first type name
     public class SchemaRegistryReadmeSnippets : SamplesBase<SchemaRegistryClientTestEnvironment>
-#pragma warning restore SA1649 // File name should match first type name
     {
         [Ignore("Only verifying that the sample builds")]
         [Test]
@@ -54,11 +52,11 @@ public void RegisterSchema()
 
         [Ignore("Only verifying that the sample builds")]
         [Test]
-        public void GetSchemaId()
+        public void RetrieveSchemaId()
         {
             var client = new SchemaRegistryClient(TestEnvironment.SchemaRegistryUri, TestEnvironment.Credential);
 
-            #region Snippet:GetSchemaId
+            #region Snippet:RetrieveSchemaId
             string schemaName = "<schema_name>";
             string groupName = "<schema_group_name>";
             SerializationType schemaType = SerializationType.Avro;
@@ -81,11 +79,11 @@ public void GetSchemaId()
 
         [Ignore("Only verifying that the sample builds")]
         [Test]
-        public void GetSchema()
+        public void RetrieveSchema()
         {
             var client = new SchemaRegistryClient(TestEnvironment.SchemaRegistryUri, TestEnvironment.Credential);
 
-            #region Snippet:GetSchema
+            #region Snippet:RetrieveSchema
             string schemaId = "<schema_id>";
 
             Response<SchemaProperties> schemaProperties = client.GetSchema(schemaId);

sdk/schemaregistry/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro/README.md

@@ -1,104 +1,146 @@
-# README.md template
+# Azure Schema Registry Apache Avro library for .NET
 
-Use the guidelines in each section of this template to ensure consistency and readability of your README. The README resides in your package's GitHub repository at the root of its directory within the repo. It's also used as the package distribution page (NuGet, PyPi, npm, etc.) and as a Quickstart on docs.microsoft.com. See [README-EXAMPLE.md](README-EXAMPLE.md) for an example following this template.
+This library provides an Apache Avro serialization and deserialization API using the Azure Schema Registry service.
 
-**Title**: The H1 of your README should be in the format: `# [Product Name] client library for [Language]`
+## Getting started
 
-* All headings, including the H1, should use **sentence-style capitalization**. Refer to the [Microsoft Style Guide][style-guide-msft] and [Microsoft Cloud Style Guide][style-guide-cloud] for more information.
-* Example: `# Azure Batch client library for Python`
+### Install the package
 
-# Azure Template client library for .NET
+Install the Azure Schema Registry Apache Avro library for .NET with [NuGet][nuget]:
 
-**Introduction**: The introduction appears directly under the title (H1) of your README.
+```PowerShell
+Install-Package Microsoft.Azure.Data.SchemaRegistry.ApacheAvro
+```
 
-* **DO NOT** use an "Introduction" or "Overview" heading (H2) for this section.
-* First sentence: **Describe the service** briefly. You can usually use the first line of the service's docs landing page for this (Example: [Cosmos DB docs landing page](https://docs.microsoft.com/azure/cosmos-db/)).
-* Next, add a **bulleted list** of the **most common tasks** supported by the package or library, prefaced with "Use the client library for [Product Name] to:". Then, provide code snippets for these tasks in the [Examples](#examples) section later in the document. Keep the task list short but include those tasks most developers need to perform with your package.
-* Include this single line of links targeting your product's content at the bottom of the introduction, making any adjustments as necessary (for example, NuGet instead of PyPi):
+### Prerequisites
 
-  [Source code](https://github.com/Azure/azure-sdk-for-python/tree/master/azure-batch) | [Package (PyPi)](https://pypi.org/project/azure-batch/) | [API reference documentation](https://docs.microsoft.com/python/api/overview/azure/batch?view=azure-python) | [Product documentation](https://docs.microsoft.com/azure/batch/)
+* An [Azure subscription][azure_sub]
+* An [Event Hubs namespace][event_hubs_namespace]
 
-> TIP: Your README should be as **brief** as possible but **no more brief** than necessary to get a developer new to Azure, the service, or the package up and running quickly. Keep it brief, but include everything a developer needs to make their first API call successfully.
+If you need to [create an Event Hubs namespace][create_event_hubs_namespace], you can use the Azure Portal or [Azure PowerShell][azure_powershell].
 
-## Getting started
+You can use Azure PowerShell to create the Event Hubs namespace with the following command:
 
-This section should include everything a developer needs to do to install and create their first client connection *very quickly*.
+```PowerShell
+New-AzEventHubNamespace -ResourceGroupName myResourceGroup -NamespaceName namespace_name -Location eastus
+```
 
-### Install the package
+### Authenticate the client
 
-First, provide instruction for obtaining and installing the package or library. This section might include only a single line of code, like `pip install package-name`, but should enable a developer to successfully install the package from NuGet, pip, npm, Maven, or even cloning a GitHub repository.
+In order to interact with the Azure Schema Registry service, you'll need to create an instance of the [Schema Registry Client][schema_registry_client] class. To create this client, you'll need Azure resource credentials and the Event Hubs namespace hostname.
 
-### Prerequisites
+#### Get credentials
 
-Include a section after the install command that details any requirements that must be satisfied before a developer can [authenticate](#authenticate-the-client) and test all of the snippets in the [Examples](#examples) section. For example, for Cosmos DB:
+To acquire authenicated credentials and start interacting with Azure resources, please see the [quickstart guide here][quickstart_guide].
 
-> You must have an [Azure subscription](https://azure.microsoft.com/free/), [Cosmos DB account](https://docs.microsoft.com/azure/cosmos-db/account-overview) (SQL API), and [Python 3.6+](https://www.python.org/downloads/) to use this package.
+#### Get Event Hubs namespace hostname
 
-### Authenticate the client
+The simpliest way is to use the [Azure portal][azure_portal] and navigate to your Event Hubs namespace. From the Overview tab, you'll see `Host name`. Copy the value from this field.
 
-If your library requires authentication for use, such as for Azure services, include instructions and example code needed for initializing and authenticating.
+#### Create SchemaRegistryClient
 
-For example, include details on obtaining an account key and endpoint URI, setting environment variables for each, and initializing the client object.
+Once you have the Azure resource credentials and the Event Hubs namespace hostname, you can create the [SchemaRegistryClient][schema_registry_client]. You'll also need the [Azure.Identity][azure_identity] package to create the credential.
 
-## Key concepts
+```C# Snippet:CreateSchemaRegistryClient
+string endpoint = "<event_hubs_namespace_hostname>";
+var credentials = new ClientSecretCredential(
+    "<tenant_id>",
+    "<client_id>",
+    "<client_secret>"
+);
+var client = new SchemaRegistryClient(endpoint, credentials);
+```
 
-The *Key concepts* section should describe the functionality of the main classes. Point out the most important and useful classes in the package (with links to their reference pages) and explain how those classes work together. Feel free to use bulleted lists, tables, code blocks, or even diagrams for clarity.
+## Key concepts
 
-## Examples
+### ObjectSerializer
 
-Include code snippets and short descriptions for each task you listed in the [Introduction](#introduction) (the bulleted list). Briefly explain each operation, but include enough clarity to explain complex or otherwise tricky operations.
+This library provides a serializer, [SchemaRegistryAvroObjectSerializer][schema_registry_avro_serializer], that implements the [ObjectSerializer][object_serializer] abstract class. This allows a developer to use this serializer in any .NET Azure SDKs that utilize ObjectSerializer. The SchemaRegistryAvroObjectSerializer utilitizes a SchemaRegistryClient to construct messages using a wire format containing schema information such as a schema ID.
 
-If possible, use the same example snippets that your in-code documentation uses. For example, use the snippets in your `examples.py` that Sphinx ingests via its [literalinclude](https://www.sphinx-doc.org/en/1.5/markup/code.html?highlight=code%20examples#includes) directive. The `examples.py` file containing the snippets should reside alongside your package's code, and should be tested in an automated fashion.
+This serializer requires the [Apache Avro library][apache_avro_library]. The payload types accepted by this serializer include [GenericRecord][generic_record] and [ISpecificRecord][specific_record].
 
-Each example in the *Examples* section starts with an H3 that describes the example. At the top of this section, just under the *Examples* H2, add a bulleted list linking to each example H3. Each example should deep-link to the types and/or members used in the example.
+### Wire Format
 
-* [Create the thing](#create-the-thing)
-* [Get the thing](#get-the-thing)
-* [List the things](#list-the-things)
+The serializer in this library creates messages in a wire format. The format is the following:
 
-### Create the thing
+- Bytes [0-3] – record format indicator – currently is \x00\x00\x00\x00
+- Bytes [4-35] – UTF-8 GUID, identifying the schema in a Schema Registry instance
+- Bytes [36-end] – serialized payload bytes
 
-Use the [create_thing](not-valid-link) method to create a Thing reference; this method does not make a network call. To persist the Thing in the service, call [Thing.save](not-valid-link).
+## Examples
 
-```Python
-thing = client.create_thing(id, name)
-thing.save()
+The following shows examples of what is available through the SchemaRegistryAvroObjectSerializer. There are both sync and async methods available for these operations. These examples use a generated Apache Avro class [Employee.cs][employee] created using this schema:
+
+```json
+{
+   "type" : "record",
+    "namespace" : "TestSchema",
+    "name" : "Employee",
+    "fields" : [
+        { "name" : "Name" , "type" : "string" },
+        { "name" : "Age", "type" : "int" }
+    ]
+}
 ```
 
-### Get the thing
+Details on generating a class using the Apache Avro library can be found in the [Avro C# Documentation][avro_csharp_documentation].
 
-The [get_thing](not-valid-link) method retrieves a Thing from the service. The `id` parameter is the unique ID of the Thing, not its "name" property.
+* [Serialize](#register-a-schema)
+* [Deserialize](#retrieve-a-schema-id)
 
-```C# Snippet:GetSecret
-var client = new MiniSecretClient(new Uri(endpoint), new DefaultAzureCredential());
+### Serialize
 
-SecretBundle secret = client.GetSecret("TestSecret");
+Register a schema to be stored in the Azure Schema Registry.
 
-Console.WriteLine(secret.Value);
-```Python
-things = client.list_things()
-```
-
-## Troubleshooting
+```C# Snippet:Serialize
+var employee = new Employee { Age = 42, Name = "John Doe" };
+string groupName = "<schema_group_name>";
 
-Describe common errors and exceptions, how to "unpack" them if necessary, and include guidance for graceful handling and recovery.
+var memoryStream = new MemoryStream();
+var serializer = new SchemaRegistryAvroObjectSerializer(client, groupName, new SchemaRegistryAvroObjectSerializerOptions { AutoRegisterSchemas = true });
+serializer.Serialize(memoryStream, employee, typeof(Employee), CancellationToken.None);
+```
 
-Provide information to help developers avoid throttling or other service-enforced errors they might encounter. For example, provide guidance and examples for using retry or connection policies in the API.
+### Deserialize
 
-If the package or a related package supports it, include tips for logging or enabling instrumentation to help them debug their code.
+Retrieve a previously registered schema ID from the Azure Schema Registry.
 
-## Next steps
+```C# Snippet:Deserialize
+string groupName = "<schema_group_name>";
 
-* Provide a link to additional code examples, ideally to those sitting alongside the README in the package's `/samples` directory.
-* If appropriate, point users to other packages that might be useful.
-* If you think there's a good chance that developers might stumble across your package in error (because they're searching for specific functionality and mistakenly think the package provides that functionality), point them to the packages they might be looking for.
+var serializer = new SchemaRegistryAvroObjectSerializer(client, groupName, new SchemaRegistryAvroObjectSerializerOptions { AutoRegisterSchemas = true });
+memoryStream.Position = 0;
+Employee employee = (Employee)serializer.Deserialize(memoryStream, typeof(Employee), CancellationToken.None);
+```
 
 ## Contributing
 
-This is a template, but your SDK readme should include details on how to contribute code to the repo/package.
+This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla].
 
-<!-- LINKS -->
-[style-guide-msft]: https://docs.microsoft.com/style-guide/capitalization
-[style-guide-cloud]: https://worldready.cloudapp.net/Styleguide/Read?id=2696&topicid=25357
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the [Code of Conduct FAQ][code_of_conduct_faq] or contact [[email protected]][email_opencode] with any additional questions or comments.
 
 ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Ftemplate%2FAzure.Template%2FREADME.png)
+
+<!-- LINKS -->
+[nuget]: https://www.nuget.org/
+[event_hubs_namespace]: https://docs.microsoft.com/en-us/azure/event-hubs/event-hubs-about
+[azure_powershell]: https://docs.microsoft.com/en-us/powershell/azure/
+[create_event_hubs_namespace]: https://docs.microsoft.com/en-us/azure/event-hubs/event-hubs-quickstart-powershell#create-an-event-hubs-namespace
+[quickstart_guide]: https://github.com/Azure/azure-sdk-for-net/blob/master/doc/mgmt_preview_quickstart.md
+[schema_registry_client]: src/SchemaRegistryClient.cs
+[azure_portal]: https://ms.portal.azure.com/
+[schema_properties]: src/SchemaProperties.cs
+[azure_identity]: https://www.nuget.org/packages/Azure.Identity
+[cla]: https://cla.microsoft.com
+[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
+[code_of_conduct_faq]: https://opensource.microsoft.com/codeofconduct/faq/
+[email_opencode]: mailto:[email protected]
+[object_serializer]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/src/Serialization/ObjectSerializer.cs
+[schema_registry_avro_serializer]: src/SchemaRegistryAvroObjectSerializer.cs
+[employee]: tests\Models\Employee.cs
+[avro_csharp_documentation]: https://avro.apache.org/docs/current/api/csharp/html/index.html
+[apache_avro_library]: https://www.nuget.org/packages/Apache.Avro/
+[generic_record]: https://avro.apache.org/docs/current/api/csharp/html/classAvro_1_1Generic_1_1GenericRecord.html
+[specific_record]: https://avro.apache.org/docs/current/api/csharp/html/interfaceAvro_1_1Specific_1_1ISpecificRecord.html