Skip to content

Convenient method generation

This page documents how to customize method generation for the emitters. For an overview of the setup, please visit the setup page.

Default behaviors

By default, any language code generator will generate both protocol methods and convenient methods.

NOTE: Python and Typescript don’t have a separation of convenient/protocol methods.

main.tsp
namespace PetStoreNamespace;
/** This is the input I need */
@resource("output")
model OutputModel {
/** Id of this object */
@key
@visibility("read")
name: string;
}
/** Read my resource */
op GetModel is ResourceRead<OutputModel>;
class OutputModel:
name: str = rest_field(readonly=True)
response: OutputModel = client.get(name="name")

Customizations

The detailed generation configuration of protocol and/or convenient methods that can be done:

As emitters global parameters:

  • generate-protocol-methods: boolean flag to shift the entire generation for the process (true by default)
  • generate-convenience-methods: boolean flag to shift the entire generation for the process (true by default)

To set global emitters parameters, read the documentation of emitters configuration.

For fine tuning, the set of decorators @protocolAPI and @convenientAPI can be used. They take a required boolean as parameter.

Shifting the generation of protocol and convenience on and off

This can be achieved with the augment operator and the emitter package

client.tsp
import "./main.tsp";
import "@azure-tools/typespec-client-generator-core";
using Azure.ClientGenerator.Core;
@@convenientAPI(PetStoreNamespace.GetModel, false);
# Python do not change behavior based on protocolAPI or convenientAPI

Make methods private/internal

Sometimes it may be useful to still generate the method, but to make it private, so it can be re-used by a manual code wrapper.

The two possible value for the Access enum are internal and public.

client.tsp
import "./main.tsp";
import "@azure-tools/typespec-client-generator-core";
using Azure.ClientGenerator.Core;
@@access(PetStoreNamespace.GetModel, "internal");
# can't import form models directly
from petstorenamespace.models import GetModel # will report error

Decide the usage of a model

Models can be used for input, output, or both at the same time. In some languages, this changes the way the API is exposed for those models.

By default, the code generator will infer the usage based on the TypeSpec. If this inference doesn’t correspond to expectation, this can be customized with the usage decorator. Possible values are input and output, and can be combined with Usage.input | Usage.output.

NOTE: If a model is never used, it will not be generated. Assigning a usage will force generation.

client.tsp
import "./main.tsp";
import "@azure-tools/typespec-client-generator-core";
using Azure.ClientGenerator.Core;
// This model is input only
@@usage(Azure.OpenAI.AzureCognitiveSearchIndexFieldMappingOptions, Usage.input);
// This models is input/output
@@usage(Azure.OpenAI.ImageGenerations, Usage.input | Usage.output);
# Python doesn't generate different code based on usage
# However, the model may not be generated if it's never used
# In that case, set a usage for the model