Skip to content

Latest commit

 

History

History
58 lines (39 loc) · 3.7 KB

README.md

File metadata and controls

58 lines (39 loc) · 3.7 KB
Raw

Quick Start

Azure services define their web APIs using swagger files.

To bind those into an SDK, Azure SDK uses Autorest to parse the swagger definitions into boilerplate networking and serialization code.

As the Azure SDK has multiple supported languages, Autorest uses plugins for each languages backend. This repository is the C# platform support plugin.

During autorest execution, the plugin is passed a YAML intermediate representation (IR) of the API definition.

Example YAML IR

The plugin is normally called via JSON RPC but there is a standalone mode that can process the intermediate yaml from disk.

autorest uses a markdown based configuration system (autorest.md) to determine what swagger files to process.

The C# backend also has an associated csproj next to autorest.md that is both:

  • As an input to code generator - Partial classes include and attributes on them configure code generation
  • As the final destination of generated code - Generated code is written into a Generated folder and compiled as part of the the project later

History

There are two “tracks" of generated Azure SDK codegen with some history behind them

  • Track 1 refers to Azure bindings before the Azure SDK team was formed to standardize bindings
    • C# uses v2 (master) branch of autorest.csharp
    • Some of these bindings was solely the autogenerated code, and were not always easy to use
  • Track 2 is the modern set of bindings reviewed by Arch board and consistent across product/language
    • C# uses v3 branch of autorest.csharp
    • Many of these leverage the autoget output internally but provide nicer hand written layer on top
    • Generated code example

Internals

Autorest first takes a pass at processing the swagger input files, and then hands the output to a “Modeler 4” pipeline inside auto rest which can encode patterns useful on all language backends

Example: Many APIs have paging, where a request will only return the first 100, and you have to ask for additional "pages" of 100 one at a time

The c# autorest plugin/generator has three major components:

  • A model layer that builds up a representation of the desired output based upon the YAML IR
    • These are C# specific modelling decisisons
    • The input project can customize the generated code by having partial classes defined. Those are read by the C# backend and modify the generated code.
    • Generated code is output in a folder named 'Generated' next to the csproj
  • A rendering layer that uses CodeWriter to output C# code
  • A roslyn simplification pass processes that generated output to make formatting and namespaces look more natural

One important part of codegen is serialization.

  • Models get json serialization
  • Requests also get serialization (so they can be sent over HTTPRequest)
    • For models a .Serialization class is created.
    • For requests a CreateRequest method is created.

There are a number of “shared” files that get included with the generated code implicitly into the final project

  • All are internal visibility, and let us iterate quickly upon their API surface
  • Long term the goal should be to upstream to Azure.Core