Skip to content

Commit 3b213c5

Browse files
jorgerangel-msftjorgerangel-msft
authored
docs: add developer onboarding guide (Azure#53305)
1 parent 847fdf3 commit 3b213c5

File tree

1 file changed

+232
-0
lines changed

1 file changed

+232
-0
lines changed

‎eng/packages/http-client-csharp/doc/DEV_ONBOARDING.md‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
# Getting Started with the TypeSpec C# Generator
2+
3+
Welcome to the TypeSpec C# Generator project! This guide will help SDK developers understand the generator ecosystem and get started with generating .NET libraries from TypeSpec definitions.
4+
5+
## Table of Contents
6+
7+
- [Overview](#overview)
8+
- [Generator Variants](#generator-variants)
9+
- [Key Concepts](#key-concepts)
10+
- [Generating a Library](#generating-a-library)
11+
- [Resources](#resources)
12+
- [Getting Help](#getting-help)
13+
- [Quick Reference](#quick-reference)
14+
15+
## Overview
16+
17+
The TypeSpec C# Generator (also known as Microsoft TypeSpec Generator or MTG) is a tool that generates .NET client libraries from TypeSpec service definitions. This replaces the legacy AutoRest-based code generation pipeline and provides improved type safety, better API design, and enhanced maintainability.
18+
19+
## Generator Variants
20+
21+
There are three variants of the C# emitter, each serving different scenarios:
22+
23+
### 1. Unbranded Emitter (`@typespec/http-client-csharp`)
24+
25+
- **Purpose**: Generates unbranded HTTP client libraries
26+
- **Repository**: [microsoft/typespec](https://github.com/microsoft/typespec/tree/main/packages/http-client-csharp)
27+
- **Use Case**: Non-Azure services or generic HTTP APIs
28+
- **Package.json Artifact**: `eng/http-client-csharp-emitter-package.json`
29+
30+
### 2. Azure Data Plane Emitter (`@azure-typespec/http-client-csharp`)
31+
32+
- **Purpose**: Generates Azure-branded data plane client libraries
33+
- **Repository**: [Azure/azure-sdk-for-net](https://github.com/Azure/azure-sdk-for-net/tree/main/eng/packages/http-client-csharp)
34+
- **Use Case**: Azure data plane services (e.g., Azure Storage, Cognitive Services)
35+
- **Package.json Artifact**: `eng/azure-typespec-http-client-csharp-emitter-package.json`
36+
37+
### 3. Azure Management Plane Emitter (`@azure-typespec/http-client-csharp-mgmt`)
38+
39+
- **Purpose**: Generates Azure Resource Manager (ARM) client libraries
40+
- **Repository**: [Azure/azure-sdk-for-net](https://github.com/Azure/azure-sdk-for-net/tree/main/eng/packages/http-client-csharp-mgmt)
41+
- **Use Case**: Azure management plane services (ARM resources)
42+
- **Package.json Artifact**: `eng/azure-typespec-http-client-csharp-mgmt-emitter-package.json`
43+
44+
## Key Concepts
45+
46+
### tsp-client
47+
48+
**tsp-client** is the orchestration tool that partners and build pipelines use to invoke the TypeSpec compiler and emitters.
49+
50+
- **Repository**: [Azure/azure-sdk-tools](https://github.com/Azure/azure-sdk-tools/tree/main/tools/tsp-client)
51+
- **Key Behavior**: Expects a corresponding `package.json` file to install the correct emitter and compile TypeSpec definitions
52+
- **Integration**: Automatically invoked by the .NET SDK build system when generating code
53+
54+
### Configuration Files
55+
56+
#### tspconfig.yaml
57+
58+
Defines the TypeSpec compilation settings and emitter configuration.
59+
60+
**Required Configuration for .NET Generation:**
61+
```yaml
62+
options:
63+
"@azure-typespec/http-client-csharp":
64+
emitter-output-dir: "{output-dir}/{service-dir}/{namespace}"
65+
namespace: Azure.Data.AppConfiguration
66+
model-namespace: false
67+
```
68+
69+
**Key Options:**
70+
- `emitter-output-dir`: Directory where generated code will be placed
71+
- `namespace`: The .NET namespace for the generated client
72+
- `model-namespace`: Whether to use a separate namespace for models (typically `false`)
73+
74+
#### tsp-location.yaml
75+
76+
Maps the library to its TypeSpec specification and emitter configuration.
77+
78+
**Key Properties:**
79+
- `directory`: Path to the TypeSpec specification (typically in azure-rest-api-specs repo)
80+
- `commit`: Git commit SHA of the spec version to use
81+
- `repo`: Repository containing the TypeSpec specification
82+
- `emitterPackageJsonPath`: Path to the emitter package.json artifact
83+
84+
**Example:**
85+
```yaml
86+
directory: specification/cognitiveservices/OpenAI.Inference
87+
commit: abc123def456
88+
repo: Azure/azure-rest-api-specs
89+
emitterPackageJsonPath: eng/azure-typespec-http-client-csharp-emitter-package.json
90+
```
91+
92+
#### Library .csproj Configuration
93+
94+
To exclude legacy AutoRest dependencies, add:
95+
96+
```xml
97+
<PropertyGroup>
98+
<IncludeAutorestDependency>false</IncludeAutorestDependency>
99+
</PropertyGroup>
100+
```
101+
102+
> **Note**: Currently defaults to `true` for backward compatibility. Track [Issue #53148](https://github.com/Azure/azure-sdk-for-net/issues/53148) for the planned default change.
103+
104+
## Generating a Library
105+
106+
Follow these steps to generate or regenerate a .NET library from TypeSpec:
107+
108+
### Prerequisites
109+
110+
- .NET SDK installed
111+
- Access to the TypeSpec specification (typically in azure-rest-api-specs)
112+
113+
### Step-by-Step Process
114+
115+
#### 1. Verify tspconfig.yaml Configuration
116+
117+
Ensure your library's `tspconfig.yaml` has the appropriate emitter options configured:
118+
119+
```yaml
120+
options:
121+
"@azure-typespec/http-client-csharp":
122+
emitter-output-dir: "{output-dir}/{service-dir}/{namespace}"
123+
namespace: Azure.YourService.YourClient
124+
model-namespace: false
125+
```
126+
127+
Replace `Azure.YourService.YourClient` with your actual .NET namespace.
128+
129+
#### 2. Configure tsp-location.yaml
130+
131+
Set the `emitterPackageJsonPath` to the appropriate artifact:
132+
133+
- For Azure data plane: `eng/azure-typespec-http-client-csharp-emitter-package.json`
134+
- For Azure management plane: `eng/azure-typespec-http-client-csharp-mgmt-emitter-package.json`
135+
- For unbranded: `eng/http-client-csharp-emitter-package.json`
136+
137+
**Example:**
138+
```yaml
139+
emitterPackageJsonPath: "eng/azure-typespec-http-client-csharp-emitter-package.json"
140+
```
141+
142+
#### 3. Update .csproj File
143+
144+
Add the following property to exclude AutoRest dependencies:
145+
146+
```xml
147+
<IncludeAutorestDependency>false</IncludeAutorestDependency>
148+
```
149+
150+
#### 4. Update Spec Version (if needed)
151+
152+
If the TypeSpec specification has been updated, modify the `commit` field in `tsp-location.yaml` to point to the latest commit SHA:
153+
154+
```yaml
155+
commit: <new-commit-sha>
156+
```
157+
158+
#### 5. Run Code Generation
159+
160+
From the library root directory (e.g., `sdk/openai/Azure.AI.OpenAI/`), execute:
161+
162+
```bash
163+
dotnet build /t:GenerateCode
164+
```
165+
166+
**What Happens:**
167+
1. tsp-client is automatically invoked by the build system
168+
2. The correct emitter is installed based on the package.json artifact
169+
3. TypeSpec compilation runs and generates the client code
170+
4. Generated files are placed in the appropriate directories
171+
172+
#### 6. Review Generated Code
173+
174+
- Check the generated files for correctness
175+
- Verify that API signatures match expectations
176+
- Run tests to ensure functionality
177+
178+
#### 7. Handle Generation Errors
179+
180+
If errors occur during generation:
181+
182+
1. **Analyze the Error**: Determine if it's a TypeSpec definition issue or a generator bug
183+
2. **Client.tsp Fixes**: Some issues can be resolved by customizing `client.tsp` (client customizations)
184+
3. **Generator Bugs**: If a generator fix is required, log a bug in the appropriate repository:
185+
- Unbranded: [microsoft/typespec](https://github.com/microsoft/typespec/issues)
186+
- Azure branded: [Azure/azure-sdk-for-net](https://github.com/Azure/azure-sdk-for-net/issues)
187+
188+
## Resources
189+
190+
### Documentation
191+
192+
- **MTG Contributing Guide**: [microsoft/typespec CONTRIBUTING.md](https://github.com/microsoft/typespec/blob/main/packages/http-client-csharp/CONTRIBUTING.md)
193+
- **Library Migration Inventory**: [Library_Inventory.md](https://github.com/Azure/azure-sdk-for-net/blob/main/doc/GeneratorMigration/Library_Inventory.md)
194+
- **TypeSpec Documentation**: [TypeSpec Official Docs](https://typespec.io/)
195+
196+
### Repositories
197+
198+
- **Unbranded Emitter**: [microsoft/typespec](https://github.com/microsoft/typespec/tree/main/packages/http-client-csharp)
199+
- **Azure Data Plane Emitter**: [Azure/azure-sdk-for-net (http-client-csharp)](https://github.com/Azure/azure-sdk-for-net/tree/main/eng/packages/http-client-csharp)
200+
- **Azure Management Emitter**: [Azure/azure-sdk-for-net (http-client-csharp-mgmt)](https://github.com/Azure/azure-sdk-for-net/tree/main/eng/packages/http-client-csharp-mgmt)
201+
- **tsp-client Tool**: [Azure/azure-sdk-tools](https://github.com/Azure/azure-sdk-tools/tree/main/tools/tsp-client)
202+
203+
## Getting Help
204+
205+
### Support Channels
206+
207+
- **Teams Channel**: Code Generation - .NET
208+
- **GitHub Issues**: File issues in the appropriate repository
209+
- Generator bugs: Use the repository corresponding to your emitter variant
210+
---
211+
212+
## Quick Reference
213+
214+
### Command Cheat Sheet
215+
216+
```bash
217+
# Generate code for a library
218+
dotnet build /t:GenerateCode
219+
```
220+
221+
### Configuration Quick Check
222+
223+
✅ **Before generating code, verify:**
224+
225+
- [ ] `tspconfig.yaml` has the correct emitter options configured (namespace, emitter-output-dir, etc.)
226+
- [ ] `tsp-location.yaml` has the correct `emitterPackageJsonPath`
227+
- [ ] `.csproj` has `<IncludeAutorestDependency>false</IncludeAutorestDependency>`
228+
- [ ] `tsp-location.yaml` has the correct spec `commit` SHA (if updating)
229+
230+
---
231+
232+
**Welcome to the team! Happy generating! 🚀**

0 commit comments

Comments
 (0)