Azure / Azure/azure-sdk-tools

customizing-client-tsp.md: Add Scenario for renaming operations aliased in @client interface

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

Description

## Problem

The reference doc (`eng/common/knowledge/customizing-client-tsp.md`) is missing a critical pattern: when a `@client` interface declares operations via `is` aliases, decorators like `@@clientName` and `@@scope` must target the **interface member**, not the source operation. Applying them to the source will silently have no effect.

## Proposed Change

Add a new **Scenario 7** to `customizing-client-tsp.md`:

---

### Scenario 7: Rename or scope operations inside a `@client` interface that uses `is` aliases

When a `@client` interface uses `is` aliases to include operations from the service namespace, each interface member is a **new operation node** — not the same reference as the source. Decorators like `@@clientName` and `@@scope` must target the **interface member**, not the source operation.

```typespec
@client({ name: "BlocklistClient", service: MyService })
interface BlocklistClient {
removeBlocklistItems is MyService.TextBlocklists.removeBlocklistItems;
createOrUpdateTextBlocklist is MyService.TextBlocklists.createOrUpdateTextBlocklist;
}

// ✅ CORRECT: target the interface member
@@clientName(BlocklistClient.removeBlocklistItems, "deleteBlocklistItems", "java")

// ❌ WRONG: targeting the source operation has no effect on the custom client
@@clientName(MyService.TextBlocklists.removeBlocklistItems, "deleteBlocklistItems", "java")
```

This rule applies to all TCGC decorators: `@@clientName`, `@@scope`, `@@access`, `@@clientDoc`, etc.

```typespec
// ✅ CORRECT: exclude an aliased operation from Java
@@scope(BlocklistClient.createOrUpdateTextBlocklist, "!java")

// ❌ WRONG: has no effect on BlocklistClient
@@scope(MyService.TextBlocklists.createOrUpdateTextBlocklist, "!java")
```

**Rule of thumb**: If an operation appears inside a `@client` interface body via `is`, always qualify it with the client interface name (e.g., `BlocklistClient.removeBlocklistItems`), not the original namespace path.

---

## Files to Update

- `eng/common/knowledge/customizing-client-tsp.md` (canonical copy in `azure-sdk-tools`, synced to `azure-rest-api-specs` and `azure-sdk-for-python`)

Contributor guide

Open the contributing guide

Research direction

Open eng/common/knowledge/customizing-client-tsp.md, review the existing scenario structure, and add the requested Scenario 7 about decorators targeting members declared with is aliases in a @client interface. Done means the canonical document explains both correct and incorrect targets for the listed decorators and includes the provided examples.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.