customizing-client-tsp.md: Add Scenario for renaming operations aliased in @client interface
- 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
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