Skip to content

Latest commit

 

History

History
151 lines (117 loc) · 5.23 KB

release-2023-02-07.md

File metadata and controls

151 lines (117 loc) · 5.23 KB
title
February 2023

Release Notes February 2023 (2023-02-07)

:::danger This release contains breaking changes :::

New Features

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

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

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

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

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

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

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

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)

@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)

@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)

@service({
  title: "Microsoft.EnvelopeTest",
  version: "2021-09-21-preview",
})
@useDependency(Azure.ResourceManager.Versions.v1_0_Preview_1)
@armProviderNamespace
namespace Microsoft.EnvelopeTest;