Skip to content

February 2023

New Features

Section titled “New Features”

Emitter Framework

Section titled “Emitter Framework”

The new emitter framework makes it simpler to build emitters from TypeSpec to other assets. It provides an easy way to handle TypeSpec types and provides a template for asset emitters to spell out the emitter tasks. It provides helpers to solve many difficult problems, including:

  • Constructing references between types
  • Handling circular references
  • Propagating type context based on containers or references
  • Class-based inheritance to encourage reuse and specialization of existing emitters

Details are available on the documentation website or in the [repository documentation] (https://github.com/microsoft/typespec/blob/main/docs/extending-typespec/emitter-framework.md).

Cli support for emitters in development

Section titled “Cli support for emitters in development”

Use the path to the emitter to specify emitter options, rather than the emitter name.

Allow @autoroute and @route to be used together

Section titled “Allow @autoroute and @route to be used together”

Provide standard rules for combining @route and @autoroute decorators

  • Allow @route applied to an operation to override route settings from the interface
  • Allow @route on an operation to prepend the paths provided by @autoroute

Simplified versioning dependencies

Section titled “Simplified versioning dependencies”

Introduced the @useDependency decorator to replace @versionedDependency decorator. Simplify dependencies between versioned namespaces, by allowing each version to be decorated with the appropriate versioned dependency, rather than requiring the user to construct a dependency map.

Breaking Changes

Section titled “Breaking Changes”

Breaking changes in this release resulted from removal of previously decorated types and functions, including:

  • uri scalar removed. Use the url scalar instead.
  • Removed deprecated metadata types with the ‘type’ suffix.
    • Use Enum instead of EnumType
    • Use EnumMember instead of EnumMemberType
    • Use Interface instead of InterfaceType
    • Use Model instead of ModelType
    • Use ModelProperty instead of ModelTypeProperty
    • Use Namespace instead of NamespaceType
    • Use Operation instead of OperationType
    • Use Tuple instead of TupleType
    • Use Union instead of UnionType
  • Removed Map<K, V> type, use Record<V> instead
  • Removed @serviceTitle and @serviceVersion decorators. Use the @service decorator instead.
  • Removed helper and accessor functions associated with @serviceTitle and @serviceVersion decorators
    • Replace getServiceNamespace, getServiceTitle, getServiceVersion, and getServiceNamespaceString with getService or listServices
    • Replace setServiceNamespace with addService
  • Removed @segmentSeparator, use @actionSeparator instead
  • Removed @produces and @consumes decorators. Use @header contentType: <ContentType> instead in the operation return type
  • Removed getSegmentSeparator function. Use getActionSeparator instead
  • Removed getProduces and getConsumes functions. Use getContentTypes instead

Deprecations

Section titled “Deprecations”

Deprecates the @versionedDependency decorator in favor of the @useDependency decorator

Section titled “Deprecates the @versionedDependency decorator in favor of the @useDependency decorator”

For versioned libraries, @useDependency is applied to the version enum members

Before (versioned namespace)

Section titled “Before (versioned namespace)”
@armProviderNamespace
@service(#{ title: "Microsoft.Observability" })
@versionedDependency(
  [
    [Microsoft.Observability.Versions.v2021_06_13_preview, Azure.Core.Versions.v1_0_Preview_2],
    [Microsoft.Observability.Versions.v2022_04_30_preview, Azure.Core.Versions.v1_0_Preview_2]
  ]
)
@versionedDependency(
  [
    [
      Microsoft.Observability.Versions.v2021_06_13_preview,
      Azure.ResourceManager.Versions.v1_0_Preview_1
    ],
    [
      Microsoft.Observability.Versions.v2022_04_30_preview,
      Azure.ResourceManager.Versions.v1_0_Preview_1
    ]
  ]
)
@versioned(Versions)
namespace Microsoft.Observability;


interface Operations extends Azure.ResourceManager.Operations {}


enum Versions {
  v2021_06_13_preview: "2021-06-13-preview",
  v2022_04_30_preview: "2022-04-30-preview",
}

After (Versioned namespace)

Section titled “After (Versioned namespace)”
@armProviderNamespace
@service(#{ title: "Microsoft.Observability" })
@versioned(Versions)
namespace Microsoft.Observability;


interface Operations extends Azure.ResourceManager.Operations {}


enum Versions {
  @useDependency(Azure.Core.Versions.v1_0_Preview_2, Azure.ResourceManager.Versions.v1_0_Preview_1)
  v2021_06_13_preview: "2021-06-13-preview",


  @useDependency(Azure.Core.Versions.v1_0_Preview_2, Azure.ResourceManager.Versions.v1_0_Preview_1)
  v2022_04_30_preview: "2022-04-30-preview",
}

For unversioned libraries that reference versioned libraries, simply replace @versionedDependency with @useDependency

Before (unversioned namespace using versioned library)

Section titled “Before (unversioned namespace using versioned library)”
@service(#{ title: "Microsoft.EnvelopeTest", version: "2021-09-21-preview" })
@versionedDependency(Azure.ResourceManager.Versions.v1_0_Preview_1)
@armProviderNamespace
namespace Microsoft.EnvelopeTest;

After (unversioned namespace using versioned library)

Section titled “After (unversioned namespace using versioned library)”
@service(#{ title: "Microsoft.EnvelopeTest", version: "2021-09-21-preview" })
@useDependency(Azure.ResourceManager.Versions.v1_0_Preview_1)
@armProviderNamespace
namespace Microsoft.EnvelopeTest;