Azure / Azure/azure-sdk-tools

[APIView][.NET] Enable Cross-Language Support for C#

Open
#14,096 0 comments 0 reactions 0 assignees View on GitHub
.NET APIView needs-triage
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 1h
Merged PRs (30d)
144

Description

Enable cross-language linking for C# packages in APIView, allowing users to view the same API across Python, JavaScript, Java, and C# side-by-side.

## What Needs Fixing

Two changes required:

### 1. Emitter Fix (azure-sdk-for-net repo)

**Location:** `eng/packages/http-client-csharp/emitter/src/emitter.ts`

**Problem:** `generateMetadataFile()` only writes API version, not cross-language mappings.

**Current:**
```json
{ "apiVersion": "2024-05-01" }
```

**Required:**
```json
{
"apiVersion": "2024-05-01",
"crossLanguageDefinitions": {
"CrossLanguagePackageId": "ContentSafety",
"CrossLanguageDefinitionId": {
"Azure.ContentSafety.ContentSafetyClient": "ContentSafety.ContentSafetyClient"
}
}
}
```

**Note:** Infrastructure already exists! `ManagementInputLibrary.cs` has `ModelsByCrossLanguageDefinitionId` - just needs to write it to file.

### 2. Parser Fix
**Location:** `tools/apiview/parsers/csharp-api-parser/`

**Problem:** Parser doesn't read metadata or set `CrossLanguageId`.

**Fix:**
- Accept optional metadata file path argument
- Load and parse the metadata JSON
- Set `CrossLanguageId` on ReviewLines when LineId matches mapping
- Set `CrossLanguageMetadata` on CodeFile

---

## Expected Output

```json
{
"PackageName": "Azure.ContentSafety",
"Language": "C#",
"CrossLanguageMetadata": {
"CrossLanguagePackageId": "ContentSafety",
"CrossLanguageDefinitionId": {
"Azure.ContentSafety.ContentSafetyClient": "ContentSafety.ContentSafetyClient"
}
},
"ReviewLines": [
{
"LineId": "Azure.ContentSafety.ContentSafetyClient",
"CrossLanguageId": "ContentSafety.ContentSafetyClient"
}
]
}
```

---

[C# Cross-Language: Implementation Guide](https://gist.github.com/AlitzelMendez/61c83dd7db205ef66a9ea85ad28bf9fe#file-csharp-md)

Contributor guide

Open the contributing guide

Research direction

Start with eng/packages/http-client-csharp/emitter/src/emitter.ts and the existing ModelsByCrossLanguageDefinitionId data in ManagementInputLibrary.cs, then inspect tools/apiview/parsers/csharp-api-parser/. Verify how the parser receives arguments and represents ReviewLines and CodeFile. Done means metadata is emitted, parsed, and reflected in CrossLanguageMetadata and matching CrossLanguageId values like those in the expected output.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, typescript
Domain
developer-experience, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.