Skip to content

Commit 4bdba75

Browse files
Remove obsolete Invoke-TypeSpecDataPlaneGenerateSDKPackage.ps1 script and modernize Azure.Template for TypeSpec (#53543)
* Initial plan * Remove obsolete Invoke-TypeSpecDataPlaneGenerateSDKPackage.ps1 script and update documentation - Deleted eng/scripts/automation/Invoke-TypeSpecDataPlaneGenerateSDKPackage.ps1 as it is not using the new emitter path - Updated doc/DataPlaneCodeGeneration/AzureSDKPackage_Setup.md to recommend using tsp-client init or manually creating tsp-location.yaml - Added guidance on required emitterPackageJsonPath property for new services Co-authored-by: JoshLove-msft <[email protected]> * Delete redundant AzureSDKPackage_Setup.md and update reference - Deleted doc/DataPlaneCodeGeneration/AzureSDKPackage_Setup.md as requested - content is covered in AzureSDKCodeGeneration_DataPlane_Quickstart.md - Updated reference in AzureSDKGeneration_Prerequistites.md to point to the quickstart guide instead Co-authored-by: JoshLove-msft <[email protected]> * Remove circular link from prerequisites doc - Removed link from AzureSDKGeneration_Prerequistites.md that was linking back to AzureSDKCodeGeneration_DataPlane_Quickstart.md - The quickstart already references the prerequisites, so this created a circular reference Co-authored-by: JoshLove-msft <[email protected]> * Update template and prerequisites doc for TypeSpec - Added link to Azure.Template in AzureSDKGeneration_Prerequistites.md as an example - Removed autorest.md from Azure.Template (obsolete for TypeSpec) - Added tsp-location.yaml to Azure.Template with placeholder values as a template for new services Co-authored-by: JoshLove-msft <[email protected]> * Remove IncludeAutorestDependency from Azure.Template csproj - Removed IncludeAutorestDependency property since template now uses TypeSpec with tsp-location.yaml instead of autorest.md Co-authored-by: JoshLove-msft <[email protected]> * Delete swagger folder from Azure.Template - Removed sdk/template/Azure.Template/src/swagger folder as it's no longer needed for TypeSpec-based generation Co-authored-by: JoshLove-msft <[email protected]> * Update tsp-location.yaml to reference widget example - Updated directory to point to specification/widget/data-plane/WidgetAnalytics as a concrete example instead of placeholder values Co-authored-by: JoshLove-msft <[email protected]> * Reference azure-rest-api-specs PR 38490 in tsp-location.yaml - Added TODO comment to update commit once PR 38490 is merged - Updated placeholder commit reference to indicate it should come from PR 38490 Co-authored-by: JoshLove-msft <[email protected]> * Delete custom code from Azure.Template causing build failures - Removed src/TemplateClient.cs (custom convenience methods for old swagger-based code) - Removed src/Models/ directory (SecretBundle and TemplateModelFactory) - These files referenced old autorest/swagger generated code that no longer exists after TypeSpec migration Co-authored-by: JoshLove-msft <[email protected]> * Remove tests and samples referencing deleted custom code - Deleted tests/TemplateClientLiveTests.cs (referenced GetSecretValueAsync and SecretBundle) - Deleted tests/Samples/Sample1_HelloWorld.cs and Sample1_HelloWorldAsync.cs (referenced GetSecretValue methods) - Deleted samples/Sample1_HelloWorld.md and Sample1.HelloWorldAsync.md (contained old code examples) - Deleted api/Azure.Template.net8.0.cs and Azure.Template.netstandard2.0.cs (API surface for deleted code) - Updated README.md to be a generic TypeSpec template without specific code examples - Updated samples/README.md to be a template guide All removed files referenced the old swagger/autorest-based custom code that no longer exists after TypeSpec migration. Co-authored-by: JoshLove-msft <[email protected]> * Restore and adapt doc and tests as generic TypeSpec templates - Restored doc/DataPlaneCodeGeneration/AzureSDKPackage_Setup.md with three options: 1. Copy Azure.Template project (recommended for complete setup) 2. Use tsp-client init 3. Manual setup - Restored and adapted test files as generic templates: - TemplateClientLiveTests.cs: Removed specific implementation, added TODO comments with [Ignore] attribute - Sample1_HelloWorld.cs and Sample1_HelloWorldAsync.cs: Updated to be generic template samples with [Ignore] attribute - TemplateClientTestEnvironment.cs: Changed from KeyVaultUri to generic Endpoint - All restored files now serve as templates that developers should adapt for their specific generated clients Co-authored-by: JoshLove-msft <[email protected]> * Fix tsp-client init command to include required --tsp-config parameter Updated the documentation to show the correct usage of tsp-client init with the required --tsp-config parameter pointing to the tspconfig.yaml in the spec repo. Co-authored-by: JoshLove-msft <[email protected]> * Fix CS1998 warning in TemplateClientLiveTests.cs Added await Task.CompletedTask to the async ExampleTest method to suppress the CS1998 compiler warning about async method lacking await operators. Co-authored-by: JoshLove-msft <[email protected]> * Update test templates to be buildable code with [Ignore] attributes Converted tests and samples to be buildable without runtime exceptions: - TemplateClientLiveTests.cs: Moved CreateClient() to comment as template example - Sample1_HelloWorld.cs: Commented out client instantiation line - Sample1_HelloWorldAsync.cs: Commented out client instantiation line All tests remain marked with [Ignore] attribute so they won't run until developers update them for their specific generated clients. Co-authored-by: JoshLove-msft <[email protected]> * Generate TypeSpec client and update tests with actual generated code - Updated tsp-location.yaml with merged commit hash 4ce7306 - Generated WidgetAnalyticsClient and related classes from the widget sample spec - Updated tests to use the actual generated client: - Renamed TemplateClientLiveTests.cs to WidgetAnalyticsClientLiveTests.cs - Updated test code to use WidgetAnalyticsClient, WidgetAnalyticsClientOptions - Updated samples to reference actual AzureWidgets and WidgetSuite types - Fixed SA1028 trailing whitespace in TemplateClientTestEnvironment.cs - Removed generated Samples_TemplateClient.cs (referenced non-existent TemplateClient) The Azure.Template now contains actual generated code from the widget TypeSpec spec and buildable tests that reference the real generated client classes. Co-authored-by: JoshLove-msft <[email protected]> * Reorder options to make tsp-client init the first (recommended) option Reordered the SDK package setup options in AzureSDKPackage_Setup.md: - Option 1 (Recommended): Using tsp-client init - Option 2: Copy the Azure.Template project - Option 3: Manual Setup Co-authored-by: JoshLove-msft <[email protected]> * Remove Option 3 from setup doc and update API/snippets - Removed "Option 3: Manual Setup" section from AzureSDKPackage_Setup.md per reviewer feedback - Updated samples/README.md with actual snippet examples for GetWidgets and GetWidgetsAsync - Added generated API surface files (Azure.Template.net8.0.cs, Azure.Template.netstandard2.0.cs) - Ran Export-API.ps1 and Update-Snippets.ps1 to ensure generated code is up to date Co-authored-by: JoshLove-msft <[email protected]> * regen * Uncomment test code in WidgetAnalyticsClientLiveTests Uncommented the actual test code for GetWidgetsTest method since the WidgetAnalyticsClient is now generated and available. The test still has [Ignore] attribute since the widget service isn't available for live testing. Co-authored-by: JoshLove-msft <[email protected]> * Improve package description for Azure.Template Updated the description and assembly title in Azure.Template.csproj to better describe the Widget Analytics template project and its purpose for demonstrating TypeSpec-based SDK generation patterns. Co-authored-by: JoshLove-msft <[email protected]> * api * Update sdk/template/Azure.Template/src/Azure.Template.csproj --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: JoshLove-msft <[email protected]> Co-authored-by: jolov <[email protected]>
1 parent 657d641 commit 4bdba75

File tree

62 files changed

+3193
-1199
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

62 files changed

+3193
-1199
lines changed

doc/DataPlaneCodeGeneration/AzureSDKGeneration_Prerequistites.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,4 @@ Make sure you have a TypeSpec project in the `main` branch of the public API spe
1616

1717
## Set up SDK Project Folder
1818

19-
You will need to generate the SDK library under an SDK project folder following the repository [guidelines](https://github.com/Azure/azure-sdk-for-net/blob/main/doc/DataPlaneCodeGeneration/AzureSDKPackage_Setup.md).
19+
You will need to generate the SDK library under an SDK project folder following the repository guidelines. You can use the [Azure.Template](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/template/Azure.Template) as an example.

doc/DataPlaneCodeGeneration/AzureSDKPackage_Setup.md

Lines changed: 26 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -18,31 +18,40 @@ sdk\<service name>\<package name>\<package name>.sln
1818

1919
## Create sdk package
2020

21-
We will use the Azure SDK template [Azure.Template](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template) to create the initial project skeleton for SDKs generated from TypeSpec.
21+
You have several options to create the initial project skeleton for SDKs generated from TypeSpec:
2222

23-
You can run `eng\scripts\automation\Invoke-TypeSpecDataPlaneGenerateSDKPackage.ps1` to generate the starting SDK client library package directly as following:
23+
### Option 1: Using tsp-client init (Recommended)
2424

25-
```powershell
26-
eng/scripts/automation/Invoke-TypeSpecDataPlaneGenerateSDKPackage.ps1 -sdkFolder <sdk-folder-path> -typespecSpecDirectory <relativeTypeSpecProjectFolderPath> -commit <commitId> [-repo <specRepo>] [-additionalSubDirectories <relativeFolders>]
25+
You can use the `tsp-client init` command to initialize the TypeSpec configuration. This tool automatically sets up the correct emitter path for new services. You must pass the `--tsp-config` parameter pointing to the tspconfig.yaml in the spec repo:
26+
27+
```bash
28+
tsp-client init --tsp-config https://github.com/Azure/azure-rest-api-specs/blob/<commit>/specification/<service>/<typespec-project-folder>/tspconfig.yaml
2729
```
2830

29-
e.g.
30-
Use git url
31+
**Example:**
3132

32-
```powershell
33-
pwsh /home/azure-sdk-for-net/eng/scripts/automation/Invoke-TypeSpecDataPlaneGenerateSDKPackage.ps1 -sdkFolder /home/azure-sdk-for-net/sdk/anomalyDetector/Azure.AI.AnomalyDetector -typespecSpecDirectory specification/cognitiveservices/AnomalyDetector -commit ac8e06a2ed0fc1c54663c98f12c8a073f8026b90 -repo Azure/azure-rest-api-specs
33+
```bash
34+
tsp-client init --tsp-config https://github.com/Azure/azure-rest-api-specs/blob/c226a37cdb9a3f756aff9edb33435ba7c90a5b91/specification/ai/ContentUnderstanding/tspconfig.yaml
3435
```
3536

36-
**Note**:
37+
This will initialize the `tsp-location.yaml` file with the correct configuration. After running this command, you'll still need to create the project structure and files manually.
38+
39+
### Option 2: Copy the Azure.Template project
40+
41+
You can copy the [Azure.Template](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/template/Azure.Template) project as a starting point. This template includes the complete project structure with:
3742

38-
- `-sdkFolder` take the address of the sdk folder in azure-sdk-for-net repo. e.g. /home/azure-sdk-for-net/sdk/anomalyDetector/Azure.AI.AnomalyDetector. [Required]
39-
- `-typespecSpecDirectory` takes the relative path of the typespec project folder in spec repo. e.g. specification/cognitiveservices/AnomalyDetector [Required]
40-
- `-additionalSubDirectories` takes the relative paths of the additional directories needed by the typespec project, such as share library folder, separated by semicolon if there is more than one folder. [Optional]
41-
- `-commit` takes the git commit hash (e.g. ac8e06a2ed0fc1c54663c98f12c8a073f8026b90) [Required]
42-
- `-repo` takes the `<owner>/<repo>` of the REST API specification repository. (e.g. Azure/azure-rest-api-specs), [Optional], default is `Azure/azure-rest-api-specs`
43+
- Project files (`.csproj`, `.sln`)
44+
- TypeSpec configuration (`tsp-location.yaml`)
45+
- Test infrastructure
46+
- Sample structure
47+
- CI/CD configuration
4348

44-
When you run `eng\scripts\automation\Invoke-TypeSpecDataPlaneGenerateSDKPackage.ps1`, it will:
49+
**Steps:**
50+
1. Copy the `sdk/template/Azure.Template` directory to your new location `sdk/<service name>/<package name>/`
51+
2. Rename the project files and namespaces to match your service
52+
3. Update the `tsp-location.yaml` file to point to your TypeSpec specification
53+
4. Update the package name, version, and other metadata in the `.csproj` file
4554

46-
- Create a project folder, install template files from `sdk/template/Azure.Template`, and create `.csproj` and `.sln` files for your new library.
55+
These files are created following the guidance for the [Azure SDK Repository Structure](https://github.com/Azure/azure-sdk/blob/master/docs/policies/repostructure.md).
4756

48-
These files are created following the guidance for the [Azure SDK Repository Structure](https://github.com/Azure/azure-sdk/blob/master/docs/policies/repostructure.md).
57+
For more information on code generation, see the [Azure SDK Code Generation Quickstart Tutorial](https://github.com/Azure/azure-sdk-for-net/blob/main/doc/DataPlaneCodeGeneration/AzureSDKCodeGeneration_DataPlane_Quickstart.md).

eng/scripts/automation/Invoke-TypeSpecDataPlaneGenerateSDKPackage.ps1

Lines changed: 0 additions & 91 deletions
This file was deleted.

sdk/template/Azure.Template/README.md

Lines changed: 10 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,13 @@
11
# Azure Template client library for .NET
22

3-
Azure Template is a managed service that helps developers get secret simply and securely.
3+
Azure Template is a template project for creating Azure SDK libraries generated from TypeSpec.
44

5-
Use the client library for to:
5+
Use this template as a starting point for:
66

7-
* [Get secret](https://learn.microsoft.com/azure)
7+
* Creating new TypeSpec-based Azure SDK client libraries
8+
* Understanding the project structure for TypeSpec-generated SDKs
89

9-
[Source code][source_root] | [Package (NuGet)][package] | [API reference documentation][reference_docs] | [Product documentation][azconfig_docs] | [Samples][source_samples]
10-
11-
[Source code](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/src) | [Package (NuGet)](https://www.nuget.org/packages) | [API reference documentation](https://azure.github.io/azure-sdk-for-net) | [Product documentation](https://learn.microsoft.com/azure)
10+
[Source code](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/src) | [Package (NuGet)](https://www.nuget.org/packages) | [API reference documentation](https://azure.github.io/azure-sdk-for-net) | [Product documentation](https://learn.microsoft.com/azure)
1211

1312
## Getting started
1413

@@ -61,20 +60,13 @@ We guarantee that all client instance methods are thread-safe and independent of
6160

6261
You can familiarize yourself with different APIs using [Samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/template/Azure.Template/samples).
6362

64-
### Get secret
65-
66-
The `GetSecret` method retrieves a secret from the service.
67-
68-
```C# Snippet:Azure_Template_GetSecret
69-
string endpoint = "https://myvault.vault.azure.net";
70-
var credential = new DefaultAzureCredential();
71-
var client = new TemplateClient(endpoint, credential);
63+
### Basic usage example
7264

73-
SecretBundle secret = client.GetSecretValue("TestSecret");
65+
Replace this section with examples specific to your generated client library methods.
7466

75-
Console.WriteLine(secret.Value);
76-
```Python
77-
things = client.list_things()
67+
```C#
68+
// Example code will be generated based on your TypeSpec definition
69+
// See the samples directory for complete examples
7870
```
7971

8072
## Troubleshooting

0 commit comments

Comments
 (0)