Skip to content

Commit

Permalink
[Docs] Fix broken link and inaccuracies (#33047)
Browse files Browse the repository at this point in the history
* [Docs] Fix broken link and inaccuracies

The focus of these changes is to fix a broken link and make some minor
corrections to formatting and information found while doing so.

* Update doc/DataPlaneCodeGeneration/Autorest_DataPlane_Quickstart.md
  • Loading branch information
jsquire authored Dec 14, 2022
1 parent 210570d commit 84190fe
Showing 1 changed file with 4 additions and 5 deletions.
9 changes: 4 additions & 5 deletions doc/DataPlaneCodeGeneration/Autorest_DataPlane_Quickstart.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Azure SDK Code Generation Quickstart Tutorial (Data Plane)

We build Azure SDK libraries to give developers a consistent, unified experience working with Azure services, in the language ecosystem where they're most comfortable. Azure SDK Code Generation allows you to quickly and easily create a client library so customers can work with your service as part of the SDK. In this tutorial, we will step through the process of creating a new Azure SDK Generated Client library for a data plane Azure service. The output library will have an API that follows [.NET Azure SDK Design Guidelines](https://azure.github.io/azure-sdk/dotnet_introduction.html), which will give it the same look and feel of other .NET libraries in the Azure SDK.
We build Azure SDK libraries to give developers a consistent and unified experience working with Azure services in the language ecosystem where they're most comfortable. Azure SDK Code Generation allows you to quickly and easily create a client library so customers can work with your service as part of the SDK. In this tutorial, we will step through the process of creating a new Azure SDK Generated Client library for a data plane Azure service. The output library will have an API that follows [.NET Azure SDK Design Guidelines](https://azure.github.io/azure-sdk/dotnet_introduction.html), which will give it the same look and feel of other .NET libraries in the Azure SDK.

Azure SDK Code Generation takes an Open API spec as input, and uses the [autorest.csharp](https://github.com/Azure/autorest.csharp) generator to output a generated library. It is important that the input API spec follows the [Azure REST API Guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md), to enable the output library to be consistent with the Azure SDK Guidelines.

Expand Down Expand Up @@ -31,16 +31,15 @@ This tutorial has following sections:

## Prerequisites

- Install VS 2020 (Community or higher) and make sure you have the [latest updates](https://www.visualstudio.com/).
- Install VS 2022 (Community or higher) and make sure you have the [latest updates](https://www.visualstudio.com/).
- Need at least .NET Framework 4.6.1 and 4.7 development tools
- Install the **.NET Core cross-platform development** workloads in VisualStudio
- Install **.NET 6.0 SDK** for your specific platform. (or a higher version)
- Install **.NET core 3.1** for your specific platform.
- Install the latest version of [git](https://git-scm.com/downloads)
- Install [PowerShell](https://docs.microsoft.com/powershell/scripting/install/installing-powershell), version 7 or higher.
- Install [NodeJS](https://nodejs.org/) (14.x.x).

## Setup your repo
## Setup your repository

- Fork and clone an [azure-sdk-for-net](https://github.com/Azure/azure-sdk-for-net) repo. Follow the instructions in the [.NET CONTRIBUTING.md](https://github.com/Azure/azure-sdk-for-net/issues/12903) to fork and clone the `azure-sdk-for-net` repo.
- Create a branch to work in.
Expand Down Expand Up @@ -151,7 +150,7 @@ Adding convenience APIs is not required for Azure SDK data plane generated libra

You can add convienice APIs by adding a customization layer on top of the generated code. Please see the [autorest.csharp README](https://github.com/Azure/autorest.csharp#setup) for the details of adding the customization layer. This is the preferred method for adding convenience APIs to your generated client.

If other modifications are needed to the generated API, you can consider making them directly to the Open API specification, which will have the benefit of making the changes to the library in all languages you generate the library in. As a last resort, you can add modifications with swagger transforms in the `autorest.md` file. [AnomalyDetector autorest.md](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/anomalydetector/Azure.AI.AnomalyDetector/src/autorest.md) shows and example of how this can be accomplished.
If other modifications are needed to the generated API, you can consider making them directly to the Open API specification, which will have the benefit of making the changes to the library in all languages you generate the library in. As a last resort, you can add modifications with swagger transforms in the `autorest.md` file. Details for various transforms can be found in [Customizing the generated code](https://github.com/Azure/autorest.csharp#customizing-the-generated-code).

Once you've made changes to the public API, you will need to run the `eng\scripts\Export-API.ps1` script to update the public API listing. This will generate a file in the library's directory similar to the example found in [sdk\template\Azure.Template\api\Azure.Template.netstandard2.0.cs](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/api/Azure.Template.netstandard2.0.cs).

Expand Down

0 comments on commit 84190fe

Please sign in to comment.