Neutral Point Measurement

    @azure-tools/cadl-providerhub-controller
    TypeScript icon, indicating that this package has built-in type declarations

    0.12.0 • Public • Published

    Cadl Service Code Generator for ProviderHub

    The Cadl service code generator for ProviderHub creates an abstract UserRP implementation of specs using the cadl-providerhub extension. Code is generating using the ASP.NET MVC framework. This doc discusses the high-level design, challenges, and remaining work.

    Usage

    Any Cadl spec defined with @azure-tools/cadl-azure-resource-manager can have server-side controller stub code generated by following these steps:

    1. Ensure @azure-tools/cadl-providerhub-controller is a dependency in your project's package.json file
    2. Ensure this line is in your main spec file's imports: import "@azure-tools/cadl-providerhub-controller"
    3. Run the following command in your project folder:
    cadl compile . --emit @azure-tools/cadl-providerhub-controller
    

    Options

    include-operation-controller

    Add the cadl compile argument --option include-operation-controller=true if you would like to have an OperationController generated in your server-side code.

    NOTE: This is not usually needed for ProviderHub services.

    Overview

    Service Code is laid out as follows:

    • One controller for each resource, containing resource operations
      • Controller is abstract, to ease regeneration
      • Controller contains a validation and completion method for each resource operation
      • Each method has an abstract template method that must be overridden by RP custom code
      • Methods give us scope for default implementations for the service
    • One static class containing service routing constants
    • A Folder containing operation list functionality
    • A Folder containing generated models
    • A boilerplate library representing the language implementation of library parts

    Execution

    Generation follows this general algorithm:

    • Create the top-level ServiceModel from cadl-providerhub metadata
    • Populate resources from cadl-providerhub public methods
      • Pre-populate standard operations
    • Iterate over the namespaces to collect operations
      • Determine resource association with namespace through cadl-providerhub
      • Get operation verb/path info through rest
      • Prevent duplication through maps/sets
      • Determine type references
      • Process return types and parameters to create model generation list
    • Populate model and enumeration declarations by iterating over generation list
      • Filter out properties that originate in parent classes
    • Copy files, and render ServiceModel data through templates to produce c# code

    Options

    include-operation-controller

    By including the --option=include-operation-controller=true argument when invoking cadl compile, an OperationController will be generated to handle operation endpoint requests in your service. This is not enabled by default since most ProviderHub services will use the operation endpoint that is provided automatically by Azure Resource Manager.

    Type Definitions

    ServiceModel

    • service metadata (name, namespace)
    • collection of [Resource]
      • Resource metadata (paths, list)
      • Operations : collection of [Operation]
        • Operation Metadata (name, subpath, verb)
        • ReturnType [TypeReference]
        • [Parameter] collection (ordered)
          • Type [TypeReference]
          • Location
          • Name
    • collection of Models [TypeDefinition]
      • Model metadata (name, namespace)
      • base type [TypeReference]
      • Implements [Collection of [TypeReference]]
      • Properties [Collection of [Property]]
    • collection of Enumerations [Enumeration]
    • [TypeReference]
      • Type metadata (name, namespace)
      • type parameters [TypeReference]
      • builtIn

    Output and Templates

    • Boilerplate c-sharp files for library code
    • Boilerplate templates for Operations
    • ResourceController Template
    • Resource paths template
    • Model Template
    • Closed and Open enumeration templates

    Points of Interest / Questions

    • Should we use library types for ProviderHub and Cadl primitives? And for which ones?
      • Constraint-related decorators
      • Inheritance / implementation / templating choices per language
    • Remove templates?
    • Identifying built-in models & operations / models from extensions
      • Operation Resolution
      • Truncating Model resolution / mapping built-in models to language models
    • Identify type names for assignment (now alias)
    • Managing spread nodes
      • Decorators from spread nodes
    • Higher-level representation of Cadl spec
      • Decorator Resolution
      • Collecting Types
      • Operation verbs and subpaths [Rest]
      • Identifying resource operations [ProviderHub]
    • Logging / tracing in the generator
    • Testing Approach
      • Template tests and Model tests
      • End-to-end generation tests
      • Service-level tests

    Remaining Work

    General

    • Bring in latest updates from main (assignments, aliases, enumerations)
    • Support for default resource
    • Support for extension resources
    • Versioning prototype
    • Factoring out language-agnostic parts
    • Command line options for logging, operation list toggle

    Model Generation in C#

    • Boilerplate types for all ProviderHub models
    • C# reserved word protection and renaming scheme
    • C# Identifier character set mapping
    • Standard handling / prevention of multiple inheritance
      • Extends
      • Templating
      • Spread
    • Error models
    • Translation for regular expressions / higher level representations
    • Refine included namespaces for actual usage

    Dependencies on ProviderHub Hosting

    • Model serialization
    • Logging
    • Design for non-resource operations controllers
    • Automated error handling

    Validation

    • CI Testing
    • End-to-end hosting in ProviderHub

    Install

    npm i @azure-tools/cadl-providerhub-controller@0.12.0

    Version

    0.12.0

    License

    MIT

    Unpacked Size

    201 kB

    Total Files

    42

    Last publish

    Collaborators

    • azure-sdk