Add the cloudSetting option for ARM Modular SDK (#3233)

* Add the cloud setting option for ARM modular SDK

* Update the idea

* Build the cloud setting enum in model.ts

* Update the comments

* Fix the generation issues

* Refactor code a little to remove duplications

* Update the integration testings

* Fix the thrown exception messages

* Update the formats

* Directly use tcgc arm option

* Fix the UTs

* Update packages/typespec-ts/src/modular/buildClientContext.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Regen the smoke with copilot comments

* Regen with smoke testing

* Move the helper into our static helper folder

* Remove the baseurl

* Update the un-necessary codes

* Update the un-necessary codes

* Fix the UTs

* Fix the UTs

* Update packages/typespec-ts/src/modular/buildRootIndex.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update the comments

* Update the copilot suggestion

* Update the git diff

* Regen modular integration test

* Update packages/typespec-test/test/NetworkAnalytics.Management/generated/typespec-ts/sdk/test/arm-test/src/static-helpers/cloudSettingHelpers.ts

Co-authored-by: Jeff Fisher <xirzec@xirzec.com>

* Update packages/typespec-test/test/NetworkAnalytics.Management/generated/typespec-ts/sdk/test/arm-test/src/static-helpers/cloudSettingHelpers.ts

Co-authored-by: Jeff Fisher <xirzec@xirzec.com>

* Refresh the smoke test and integration test

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Jeff Fisher <xirzec@xirzec.com>

Author: 3 people

packages/typespec-test/test/NetworkAnalytics.Management/generated/typespec-ts/sdk/test/arm-test/review/arm-networkanalytics.api.md

@@ -28,6 +28,16 @@ export interface AccountSasToken {
 // @public
 export type ActionType = string;
 
+// @public
+export enum AzureClouds {
+    AZURE_CHINA_CLOUD = "AZURE_CHINA_CLOUD",
+    AZURE_PUBLIC_CLOUD = "AZURE_PUBLIC_CLOUD",
+    AZURE_US_GOVERNMENT = "AZURE_US_GOVERNMENT"
+}
+
+// @public
+export type AzureSupportedClouds = `${AzureClouds}`;
+
 // @public
 export interface ConsumptionEndpointsProperties {
     readonly fileAccessResourceId?: string;
@@ -442,6 +452,7 @@ export class NetworkAnalyticsApi {
 // @public
 export interface NetworkAnalyticsApiOptionalParams extends ClientOptions {
     apiVersion?: string;
+    cloudSetting?: AzureSupportedClouds;
 }
 
 // @public

packages/typespec-test/test/NetworkAnalytics.Management/generated/typespec-ts/sdk/test/arm-test/src/api/networkAnalyticsApiContext.ts

@@ -3,6 +3,10 @@
 
 import { logger } from "../logger.js";
 import { KnownVersions } from "../models/models.js";
+import {
+  AzureSupportedClouds,
+  getArmEndpoint,
+} from "../static-helpers/cloudSettingHelpers.js";
 import { Client, ClientOptions, getClient } from "@azure-rest/core-client";
 import { TokenCredential } from "@azure/core-auth";
 
@@ -19,14 +23,19 @@ export interface NetworkAnalyticsApiOptionalParams extends ClientOptions {
   /** The API version to use for this operation. */
   /** Known values of {@link KnownVersions} that the service accepts. */
   apiVersion?: string;
+  /** Specifies the Azure cloud environment for the client. */
+  cloudSetting?: AzureSupportedClouds;
 }
 
 export function createNetworkAnalyticsApi(
   credential: TokenCredential,
   subscriptionId: string,
   options: NetworkAnalyticsApiOptionalParams = {},
 ): NetworkAnalyticsApiContext {
-  const endpointUrl = options.endpoint ?? "https://management.azure.com";
+  const endpointUrl =
+    options.endpoint ??
+    getArmEndpoint(options.cloudSetting) ??
+    "https://management.azure.com";
   const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
   const userAgentInfo = `azsdk-js-arm-networkanalytics/1.0.0-beta.1`;
   const userAgentPrefix = prefixFromOptions

packages/typespec-test/test/NetworkAnalytics.Management/generated/typespec-ts/sdk/test/arm-test/src/index.ts

@@ -1,6 +1,10 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+import {
+  AzureClouds,
+  AzureSupportedClouds,
+} from "./static-helpers/cloudSettingHelpers.js";
 import {
   PageSettings,
   ContinuablePage,
@@ -104,3 +108,4 @@ export {
   OperationsOperations,
 } from "./classic/index.js";
 export { PageSettings, ContinuablePage, PagedAsyncIterableIterator };
+export { AzureClouds, AzureSupportedClouds };

packages/typespec-test/test/NetworkAnalytics.Management/generated/typespec-ts/sdk/test/arm-test/src/static-helpers/cloudSettingHelpers.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+/** An enum to describe Azure Cloud. */
+export enum AzureClouds {
+  /** Azure public cloud, which is the default cloud for Azure SDKs. */
+  AZURE_PUBLIC_CLOUD = "AZURE_PUBLIC_CLOUD",
+  /** Azure China cloud */
+  AZURE_CHINA_CLOUD = "AZURE_CHINA_CLOUD",
+  /** Azure US government cloud */
+  AZURE_US_GOVERNMENT = "AZURE_US_GOVERNMENT",
+}
+
+/** The supported values for cloud setting as a string literal type */
+export type AzureSupportedClouds = `${AzureClouds}`;
+
+export function getArmEndpoint(
+  cloudSetting?: AzureSupportedClouds,
+): string | undefined {
+  if (cloudSetting === undefined) {
+    return undefined;
+  }
+  const cloudEndpoints: Record<keyof typeof AzureClouds, string> = {
+    AZURE_CHINA_CLOUD: "https://management.chinacloudapi.cn/",
+    AZURE_US_GOVERNMENT: "https://management.usgovcloudapi.net/",
+    AZURE_PUBLIC_CLOUD: "https://management.azure.com/",
+  };
+  if (cloudSetting in cloudEndpoints) {
+    return cloudEndpoints[cloudSetting];
+  } else {
+    throw new Error(
+      `Unknown cloud setting: ${cloudSetting}. Please refer to the enum AzureClouds for possible values.`,
+    );
+  }
+}

packages/typespec-ts/src/framework/load-static-helpers.ts

@@ -2,6 +2,7 @@ import { readdir, stat, readFile } from "fs/promises";
 import * as path from "path";
 import {
   ClassDeclaration,
+  EnumDeclaration,
   FunctionDeclaration,
   InterfaceDeclaration,
   Project,
@@ -15,7 +16,7 @@ import { ModularEmitterOptions } from "../modular/interfaces.js";
 export const SourceFileSymbol = Symbol("SourceFile");
 export interface StaticHelperMetadata {
   name: string;
-  kind: "function" | "interface" | "typeAlias" | "class";
+  kind: "function" | "interface" | "typeAlias" | "class" | "enum";
   location: string;
   [SourceFileSymbol]?: SourceFile;
 }
@@ -137,6 +138,7 @@ function getDeclarationByMetadata(
   | FunctionDeclaration
   | TypeAliasDeclaration
   | InterfaceDeclaration
+  | EnumDeclaration
   | undefined {
   switch (declaration.kind) {
     case "class":
@@ -147,6 +149,8 @@ function getDeclarationByMetadata(
       return file.getInterface(declaration.name);
     case "typeAlias":
       return file.getTypeAlias(declaration.name);
+    case "enum":
+      return file.getEnum(declaration.name);
     default:
       throw new Error(
         `invalid helper kind ${declaration.kind}\nAll helpers provided to loadStaticHelpers are of kind: function, interface, typeAlias, class`

packages/typespec-ts/src/index.ts

@@ -11,6 +11,7 @@ import {
 import { EmitContext, Program } from "@typespec/compiler";
 import { GenerationDirDetail, SdkContext } from "./utils/interfaces.js";
 import {
+  CloudSettingHelpers,
   MultipartHelpers,
   PagingHelpers,
   PollingHelpers,
@@ -130,7 +131,8 @@ export async function $onEmit(context: EmitContext) {
       ...PagingHelpers,
       ...PollingHelpers,
       ...UrlTemplateHelpers,
-      ...MultipartHelpers
+      ...MultipartHelpers,
+      ...CloudSettingHelpers
     },
     {
       sourcesDir: dpgContext.generationPathDetail?.modularSourcesDir,

packages/typespec-ts/src/lib.ts

@@ -356,6 +356,12 @@ const libDef = {
       messages: {
         default: paramMessage`The property name ${"propertyName"} has conflicts with others and please use @clientName to rename it.`
       }
+    },
+    "parameter-name-conflict": {
+      severity: "warning",
+      messages: {
+        default: paramMessage`The parameter name ${"parameterName"} has conflicts with others and please use @clientName to rename it.`
+      }
     }
   },
   emitter: {

packages/typespec-ts/src/modular/buildClientContext.ts

@@ -33,6 +33,9 @@ import {
 import { getModularClientOptions } from "../utils/clientUtils.js";
 import { useContext } from "../contextManager.js";
 import { refkey } from "../framework/refkey.js";
+import { reportDiagnostic } from "../lib.js";
+import { NoTarget } from "@typespec/compiler";
+import { CloudSettingHelpers } from "./static-helpers-metadata.js";
 
 /**
  * This function gets the path of the file containing the modular client context
@@ -100,25 +103,46 @@ export function buildClientContext(
       })
   });
 
+  const propertiesInOptions = getClientParameters(client, dpgContext, {
+    optionalOnly: true
+  })
+    .filter((p) => p.name !== "endpoint")
+    .map((p) => {
+      return {
+        name: getClientParameterName(p),
+        type:
+          p.name.toLowerCase() === "apiversion"
+            ? "string"
+            : getTypeExpression(dpgContext, p.type),
+        hasQuestionToken: true,
+        docs: getDocsWithKnownVersion(dpgContext, p)
+      };
+    });
+  if (dpgContext.arm) {
+    propertiesInOptions.push({
+      name: "cloudSetting",
+      type: `${resolveReference(CloudSettingHelpers.AzureSupportedClouds)}`,
+      hasQuestionToken: true,
+      docs: [`Specifies the Azure cloud environment for the client.`]
+    });
+  }
+  // check if we have duplication options
+  const existingOptionNames = new Set<string>();
+  for (const property of propertiesInOptions) {
+    if (existingOptionNames.has(property.name)) {
+      reportDiagnostic(dpgContext.program, {
+        code: "parameter-name-conflict",
+        format: { parameterName: property.name },
+        target: NoTarget
+      });
+    }
+    existingOptionNames.add(property.name);
+  }
   clientContextFile.addInterface({
     name: `${getClassicalClientName(client)}OptionalParams`,
     isExported: true,
     extends: [resolveReference(dependencies.ClientOptions)],
-    properties: getClientParameters(client, dpgContext, {
-      optionalOnly: true
-    })
-      .filter((p) => p.name !== "endpoint")
-      .map((p) => {
-        return {
-          name: getClientParameterName(p),
-          type:
-            p.name.toLowerCase() === "apiversion"
-              ? "string"
-              : getTypeExpression(dpgContext, p.type),
-          hasQuestionToken: true,
-          docs: getDocsWithKnownVersion(dpgContext, p)
-        };
-      }),
+    properties: propertiesInOptions,
     docs: ["Optional parameters for the client."]
   });
 

packages/typespec-ts/src/modular/buildRootIndex.ts

@@ -3,7 +3,11 @@ import { Project, SourceFile } from "ts-morph";
 import { getClassicalClientName } from "./helpers/namingHelpers.js";
 import { ModularEmitterOptions } from "./interfaces.js";
 import { resolveReference } from "../framework/reference.js";
-import { MultipartHelpers, PagingHelpers } from "./static-helpers-metadata.js";
+import {
+  CloudSettingHelpers,
+  MultipartHelpers,
+  PagingHelpers
+} from "./static-helpers-metadata.js";
 import {
   SdkClientType,
   SdkContext,
@@ -68,6 +72,7 @@ export function buildRootIndex(
 
   exportPagingTypes(context, rootIndexFile);
   exportFileContentsType(context, rootIndexFile);
+  exportAzureCloudTypes(context, rootIndexFile);
 }
 
 function exportModels(
@@ -91,6 +96,15 @@ function exportModels(
   }
 }
 
+function exportAzureCloudTypes(context: SdkContext, rootIndexFile: SourceFile) {
+  if (context.arm) {
+    addExportsToRootIndexFile(rootIndexFile, [
+      resolveReference(CloudSettingHelpers.AzureClouds),
+      resolveReference(CloudSettingHelpers.AzureSupportedClouds)
+    ]);
+  }
+}
+
 /**
  * This is a temporary solution for adding paging exports. Eventually we will have the binder generate the exports automatically.
  */
@@ -99,18 +113,11 @@ function exportPagingTypes(context: SdkContext, rootIndexFile: SourceFile) {
     return;
   }
 
-  const existingExports = getExistingExports(rootIndexFile);
-  const namedExports = [
+  addExportsToRootIndexFile(rootIndexFile, [
     resolveReference(PagingHelpers.PageSettings),
     resolveReference(PagingHelpers.ContinuablePage),
     resolveReference(PagingHelpers.PagedAsyncIterableIterator)
-  ];
-
-  const newNamedExports = getNewNamedExports(namedExports, existingExports);
-
-  if (newNamedExports.length > 0) {
-    addExportsToRootIndexFile(rootIndexFile, newNamedExports);
-  }
+  ]);
 }
 
 function hasPaging(context: SdkContext): boolean {
@@ -139,14 +146,9 @@ function exportFileContentsType(
       )
     )
   ) {
-    const existingExports = getExistingExports(rootIndexFile);
-    const namedExports = [resolveReference(MultipartHelpers.FileContents)];
-
-    const newNamedExports = getNewNamedExports(namedExports, existingExports);
-
-    if (newNamedExports.length > 0) {
-      addExportsToRootIndexFile(rootIndexFile, newNamedExports);
-    }
+    addExportsToRootIndexFile(rootIndexFile, [
+      resolveReference(MultipartHelpers.FileContents)
+    ]);
   }
 }
 
@@ -171,11 +173,15 @@ function getNewNamedExports(
 
 function addExportsToRootIndexFile(
   rootIndexFile: SourceFile,
-  newNamedExports: string[]
+  namedExports: string[]
 ) {
-  rootIndexFile.addExportDeclaration({
-    namedExports: newNamedExports
-  });
+  const existingExports = getExistingExports(rootIndexFile);
+  const newNamedExports = getNewNamedExports(namedExports, existingExports);
+  if (newNamedExports.length > 0) {
+    rootIndexFile.addExportDeclaration({
+      namedExports: newNamedExports
+    });
+  }
 }
 
 function exportRestoreHelpers(

packages/typespec-ts/src/modular/helpers/clientHelpers.ts

@@ -20,6 +20,8 @@ import { SdkContext } from "../../utils/interfaces.js";
 import { getClassicalClientName } from "./namingHelpers.js";
 import { getTypeExpression } from "../type-expressions/get-type-expression.js";
 import { isCredentialType } from "./typeHelpers.js";
+import { CloudSettingHelpers } from "../static-helpers-metadata.js";
+import { resolveReference } from "../../framework/reference.js";
 
 interface ClientParameterOptions {
   onClientOnly?: boolean;
@@ -170,8 +172,16 @@ export function buildGetClientEndpointParam(
   dpgContext: SdkContext,
   client: SdkClientType<SdkServiceOperation>
 ): string {
-  const coreEndpointParam = `options.endpoint`;
-
+  let coreEndpointParam = "";
+  if (dpgContext.rlcOptions?.flavor === "azure") {
+    const cloudSettingSuffix = dpgContext.arm
+      ? ` ?? ${resolveReference(CloudSettingHelpers.getArmEndpoint)}(options.cloudSetting)`
+      : "";
+    coreEndpointParam = `options.endpoint${cloudSettingSuffix}`;
+  } else {
+    // unbranded does not have the deprecated baseUrl parameter
+    coreEndpointParam = `options.endpoint`;
+  }
   // Special case: endpoint URL not defined
   const endpointParam = getClientParameters(client, dpgContext, {
     onClientOnly: true,