microsoft / microsoft/typespec

[http-client-csharp] Do not include internal union variant types in the generated property description

Open
#11,843 0 comments 1 reaction 0 assignees View on GitHub
bug emitter:client:csharp
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

## Describe the bug

For a property backed by a TypeSpec union, the C# emitter generates a `BinaryData` property with a "Supported types" list in the XML docs, built from the union item types. That list includes **internal** variant types, which is not useful to a consumer: they cannot name or construct the type being suggested.

`PropertyDescriptionBuilder.GetUnionTypesDescriptions` emits a cref for every union item with no accessibility filter:

```csharp
description = new XmlDocStatement("description", [$"{item:C}"]);
```

and `CodeWriter.AppendTypeForCRef` only falls back to plain text when the type was removed from the output (`ProviderReferenceMapAnalyzer.IsRemovedTypeReference`), not when it is internal.

The result compiles — an in-assembly cref to an internal type is legal — but it documents an API surface the caller cannot reach.

## Example

In `Azure.AI.Projects.Agents`, `DeclarativeAgentDefinition.ToolChoice` is a public `BinaryData` property whose union variants are all `internal`:

```csharp
///
/// Supported types:
///
///
/// .
///
///
/// .
///
///
///
public BinaryData ToolChoice { get; set; }
```

`InternalToolChoiceParam` is `internal abstract`, so a consumer cannot construct one to assign to `ToolChoice`.

## Expected behavior

Internal union variant types should be omitted from the generated "Supported types" list. If every variant is internal, the list should be omitted entirely rather than emitted empty, while the surrounding `BinaryData` guidance (`FromObjectAsJson` / `FromString` and the examples) is preserved.

## Reproduction

Not playground-reproducible; this is emitter output behavior. It reproduces on any library with a public `BinaryData` union property whose variants are internal, for example a spec with `@access(Access.internal)` on the union variant models. A concrete instance is `sdk/ai/Azure.AI.Projects.Agents/src/Generated/Models/DeclarativeAgentDefinition.cs` in Azure/azure-sdk-for-net#62649.

Note this is independent of API compatibility processing — it is not specific to regenerated libraries with a last contract.

## Related

- #11839 — where this was raised in review
- #11842 — the related question of whether internal union variants should be kept in the output at all

Contributor guide

Open the contributing guide

Research direction

Search for PropertyDescriptionBuilder.GetUnionTypesDescriptions and read how it builds union item descriptions, then inspect CodeWriter.AppendTypeForCRef and the accessibility information available for referenced types. Verify the generated XML docs for DeclarativeAgentDefinition.ToolChoice: internal variants are absent, the list is omitted when none are public, and the surrounding BinaryData guidance remains.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.