Skip to content

June 2023

Release Notes June 2023 (2023-06-06)

See TypeSpec Core release notes

New Features

  • .Net packages now published to public Nuget
  • Decorators are now fully specified in TypeSPec across all libraries. This improves reference documentation and IDE completion when using decorators.

@azure-tools/typespec-azure-core

  • Added LongRunningRpcOperation template to Azure.Core
  • Added new scalars for known formats uuid, ipV4Address, ipV6Address and eTag
  • Added descriptions to library enums

@azure-tools/typespec-azure-resource-manager

  • Added descriptions to library enums

@azure-tools/typespec-client-generator-core

  • Add support for scalars that use @encode.
  • Add mitigation for format removal in url scalar.
  • Add scope to internal decorator

Bug Fixes

  • Missing decorator signatures added for all libraries, adding reference documentation and completion help in language IDE tooling.
  • OpenAPI format derived from encoding is fixed to favor the appropriate format
  • OpenAPI parameter @doc now overrides the @doc for the underlying type

New Linting Rules

@azure-tools/azure-core

  • Documentation comments now required on Enums and Enum values
  • Using encodings outside the known set causes a warning.
  • Discourage using explicit @route in resource operations.
  • Discourage using path parameters in RPC operations.
  • Add validation to @pollingOperation so it can only refer to an operation that returns a model or union of models

Deprecations

Azure.Core Deprecations

Operation templates not accessed through ResourceOperations<T> should not be used in new specifications. Instead, services should specify the standard operation traits using ResourceOperations<T> and use the resulting interface to define these operations. This change will not cause any deprecation warning in existing specs, but the older operations should not be used for new APIs.

Old (deprecated) operations pattern

op get is Azure.Core.ResourceRead<MyResource>;

New operations pattern

alias ServiceTraits = SupportsRepeatableRequests &
  SupportsConditionalRequests &
  SupportsClientRequestId;


alias Operations = Azure.Core.ResourceOperations<ServiceTraits>;


op get is Operations.ResourceRead<MyResource>;

This deprecation impacts the following operations:

  • Azure.Core.ResourceCreateOrReplace
  • Azure.Core.LongRunningResourceCreateOrReplace
  • Azure.Core.ResourceCreateOrUpdate
  • Azure.Core.LongRunningResourceCreateOrUpdate
  • Azure.Core.ResourceUpdate
  • Azure.Core.ResourceCreateWithServiceProvidedName
  • Azure.Core.LongRunningResourceCreateWithServiceProvidedName
  • Azure.Core.ResourceRead
  • Azure.Core.ResourceDelete
  • Azure.Core.LongRunningResourceDelete
  • Azure.Core.ResourceList
  • Azure.Core.ResourceAction
  • Azure.Core.LongRunningResourceAction
  • Azure.Core.ResourceCollectionAction
  • Azure.Core.LongRunningResourceCollectionAction

Breaking Changes

@azure-tools/typespec-autorest Breaking Changes

  • Examples for the same operation must have unique titles. In the past, one of the examples would have been silently dropped. When examples for an operation have duplicate titles, a diagnostic is thrown, prompting users to fix the problem.
  • In operations with an implicit body parameter, the body parameter is now required.

@azure-tools/typespec-azure-core Breaking Changes

  • Standard error type schema corrected to match API Guidelines. This will cause OpenAPI emission to change to the correct error schema.

@azure-tools/typespec-azure-resource-manager Breaking Changes

  • The following templates now use TypeSpec.Reflection.Model as the constraint for their TProperties parameter. Any template that builds on or uses these templates should have the same parameter constraint:
    • ResourceUpdateModelProperties
    • ResourceUpdateModel
    • ProxyresourceUpdateModel
    • ResourceOperations
    • TrackedResourceOperations
    • ResourceInstanceOperations
    • TenantResourceOperations
    • ResourceUpdateAsync
    • ResourceUpdateSync
    • ExtensionResourceInstanceOperations
    • ExtensionResourceOperations
    • ResourceUpdate
    • ProxyResourceUpdate
    • ExtensionResourceUpdate
    • TenantResourceUpdate
    • ArmResourcePatchAsync
    • ArmResourcePatchSync
  • CustomPatch templates were updated to that the TPatchModel parameter extends TypeSpec.Reflection.Model. Any template that builds on or uses these templates should use the same parameter constraint:
    • ArmCustomPatchAsync
    • ArmCustomPatchSync
  • Resource Action operation teamplates have been updated to use TypeSPec.Reflection.Model as the constraint for TRequest and TResponse parameters. Any template that builds on or uses these templates should have the same parameter constraint:
    • ArmResourceActionAsync
    • ArmResourceActionSync
    • ArmResourceActionNoContentAsync
    • ArmResourceActionNoContentSync
  • The checkNameAvailability, checkGlobalNameAvailability and checkLocalNameAvailability templates have been updated so that all of their parameters extend TypeSpec.Model.Reflection. Any template that builds on or uses these templates should use the same parameter constraint.