[tcgc] client initialization

[tadelesh]

Design doc is included in this PR.

1.Change @clientInitialization decorator's options parameter to ClientInitializationOptions type. The options now could set how to initialize the client. Though the implementation could support backward compatibility, it's better to have all specs that use this decorator change from @clientInitialization(CustomizedOption) to @clientInitialization({parameters: CustomizedOption}). A new helper getClientInitializationOptions is added for getting the new ClientInitializationOptions info from the @clientInitialization decorator.
2. Add new children property to SdkClientType to include all the sub client belong to that client.
3. Add init property to SdkClientType. Its type is SdkClientInitializationType which includes the initialization parameters and how to initialize the client.
4. Deprecate initialization property of SdkClientType. Use init.paramters of SdkClientType instead.
5. Deprecate SdkClientAccessor type. Use parent and children property from SdkClientType to find client hierarchy instead.

Also resolve: #1696, #1702, #1707, #1715

[azure-sdk]

All changed packages have been documented.

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

Show changes

@azure-tools/typespec-client-generator-core - feature ✏️

support name and isGeneratedName for nullable type

@azure-tools/typespec-client-generator-core - feature ✏️

Change @clientInitialization decorator's options parameter to ClientInitializationOptions type. The options now could set how to initialize the client. Though the implementation could support backward compatibility, it's better to have all specs that use this decorator change from @clientInitialization(CustomizedOption) to @clientInitialization({parameters: CustomizedOption}). A new helper getClientInitializationOptions is added for getting the new ClientInitializationOptions info from the @clientInitialization decorator.

@azure-tools/typespec-client-generator-core - feature ✏️

Add new children property to SdkClientType to include all the sub client belong to that client.

@azure-tools/typespec-client-generator-core - feature ✏️

Add init property to SdkClientType. Its type is SdkClientInitializationType which includes the initialization parameters and how to initialize the client.

@azure-tools/typespec-client-generator-core - deprecation ✏️

Deprecate initialization property of SdkClientType. Use init.paramters of SdkClientType instead.

@azure-tools/typespec-client-generator-core - deprecation ✏️

Deprecate SdkClientAccessor type. Use parent and children property from SdkClientType to find client hierarchy instead.

@azure-tools/typespec-client-generator-core - feature ✏️

Add serializationOptions property to SdkModelType and SdkBodyModelPropertyType. Its type is SerializationOptions which contains the info of how to serialize to Json/Xml/Multipart value.

@azure-tools/typespec-client-generator-core - deprecation ✏️

Deprecate serializedName property in SdkBodyModelPropertyType, use serializationOptions.xxx.name instead.

@azure-tools/typespec-client-generator-core - deprecation ✏️

Deprecate multipartOptions in SdkBodyModelPropertyType, use serializationOptions.multipart instead.

[azure-sdk]

You can try these changes here

🛝 Playground	🌐 Website	📚 Next docs

[tadelesh]

two things to be discussed:

1. shall we put initialization method into methods list or move client accessor method out of methods list to keep consistency?
2. if client access is public, shall we put it to be the top-level client?

[weidongxu-microsoft]

Note that for Java, we again want to know whether the e.g. initializedBy is provided by TCGC or by TypeSpec. The case in Java is that all subclient is by default "initialized by" "ClientBuilder of root client", unless specified different by dev (when specified, emitter would follow that -- Accessor or Ctor or both -- Ctor would imply as "ClientBuilder of sub client" in Java).

It maybe supported by 2 ways.

1. initializedBy==undefined if not specified in TypeSpec -- this may not be easy to understand, and could be confusing for other languages
2. emitter can provide a "defaultSubClientInitializedBy" to TCGC. In Java's case, it could be "ClientBuilder"

I am not sure whether JavaScript have similar ask.

[tadelesh]

Note that for Java, we again want to know whether the e.g. initializedBy is provided by TCGC or by TypeSpec. The case in Java is that all subclient is by default "initialized by" "ClientBuilder of root client", unless specified different by dev (when specified, emitter would follow that -- Accessor or Ctor or both -- Ctor would imply as "ClientBuilder of sub client" in Java).

It maybe supported by 2 ways.

1. initializedBy==undefined if not specified in TypeSpec -- this may not be easy to understand, and could be confusing for other languages
2. emitter can provide a "defaultSubClientInitializedBy" to TCGC. In Java's case, it could be "ClientBuilder"

I am not sure whether JavaScript have similar ask.

i think tcgc could give you a flag to not set default.

[iscai-msft]

love it, thanks for the quick turnaround @tadelesh!

[weidongxu-microsoft]

nit, personally I'd like the full word initialization. But appears here we name it init because we need to handle the deprecate procedure.

[tadelesh]

i'm not 100% like current name. but not have more idea. @iscai-msft do you have any suggestion. this pr will not break anything, but just deprecate things, so we could not use previous property name.

[iscai-msft]

we could change the whole thing to "constructor" instead of "initialization"? Don't know if it's that much work though, I'm ok with init if we want to keep it that way

[weidongxu-microsoft]

i think tcgc could give you a flag to not set default.

Current design (not finalized) in Java would be an emitter option to control what emitter handles the subclients on "parent".
By default, "initializedBy = parent" in Azure would be mapped to "initializedBy = parentBuilder".

Therefore, no flag needed, at present.

[tadelesh]

@srnagar @m-nash could you help to review?