TypeSpec Service Code Generator for ProviderHub

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

We recommend consuming this package through the typespec-providerhub-templates, which contains a full service implementation in ASP.Net Core MVC, and sets the appropriate configurations for swagger generation, hosting your service, RP and resource registration, and end-to-end testing in RPaaS OneBox.

Usage

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

1. Ensure @azure-tools/typespec-liftr-emitter 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/typespec-liftr-emitter"
3. Run the following command in your project folder:

tsp compile . --emit @azure-tools/typespec-liftr-emitter

Emitter Options

Emitter options can be configured via the tspconfig.yaml configuration:

emitters:
  '@azure-tools/typespec-liftr-emitter':
    <optionName>: <value>


# For example
emitters:
  '@azure-tools/typespec-liftr-emitter':
    include-operation-controller: true

or via the command line with

--option "@azure-tools/typespec-liftr-emitter.<optionName>=<value>"

# For example
--option "@azure-tools/typespec-liftr-emitter.include-operation-controller=true"

output-dir

Path where the service code will be generated. By default will use the compiler output-dir.

include-operation-controller

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. NOTE: This is not usually needed for ProviderHub services.

include-subscription-lifecycle-controller

A SubscriptionLifeCycleNotification controller will be generated to handle subscription life cycle notification requests in your service. This is only enabled by default for new projects.

operation-polling-location

Determines whether a tenant-level ("tenant") or subscription-level ("subscription") status monitor is used for long-running operations. By default, uses the tenant-level status monitor provided by RPaaS.

registration-output-path

When set to a valid path, generates provider and type registration documents to the specified path. These can be used to register your resource provider and your resource types with RPaaS, for later creation of your manifest.

code-kind

Type of generation:

• When set to controller, generates only controller code and assume that the model will be generated in separate process.
• When set to model , generates only model code and assume that the controller will be generated in separate process.

include-cancellation-token

When set to true, generates controller action methods with a System.Threading.CancellationToken parameter.

include-versioning-classes

When set to true, generates versioning classes regardless the number of API versions defined in the spec.

generate-uuid-as

When set to 'guid', generates properties of type Azure.Core.uuid as System.Guid in model classes. When set to 'string', generates properties of type Azure.Core.uuid as System.String in model classes.