Create Copilot Skill for Ambient Properties
- Dominant language
- C#
- Stars
- 4.9k
- Forks
- 1.1k
- Avg merge
- 1d 13m
- Merged PRs (30d)
- 85
Description
## Background
WinForms has a concept of **ambient properties** properties that cascade from a parent control to all its children unless a child explicitly overrides the value. The canonical example is `DataContext` (introduced in .NET 7 via PR #7143), but the pattern also applies to properties like `Font`, `BackColor`, `ForeColor`, `Cursor`, and `BindingContext`.
When adding new APIs to WinForms controls, contributors sometimes need to implement ambient properties. The current `new-control-api` Skill covers standard property patterns but explicitly defers ambient properties to a separate, dedicated Skill.
## Motivation
1. **Standardize the pattern.** The existing `DataContext` implementation may not fully follow the canonical ambient property approach. A Skill would codify the correct pattern for future APIs.
2. **Constructor ordering hazard.** In WinForms, virtual methods (e.g., `CreateParams`) are called from the base class constructor *before* the derived class constructor body runs. Ambient properties must handle this safely the Skill should document the pitfalls.
3. **PropertyStore integration.** Ambient properties use `PropertyStore.TryGetValue` with a parent-fallback chain. The Skill should prescribe the exact getter/setter pattern, including when to store vs. remove values.
4. **Propagation pattern.** The `OnParent[Property]Changed` method must propagate changes to children. The Skill should define the canonical implementation, including disposal guards and child iteration.
5. **DataContext retrofit.** The existing `DataContext` implementation should be reviewed against the codified Skill pattern to identify any gaps that should be addressed in .NET 11.
## Core Issues to Address in the Skill
- [ ] Define the canonical getter pattern: `PropertyStore.TryGetValue` with `ParentInternal?.Property` fallback
- [ ] Define the canonical setter pattern: store only when different from parent, remove when equal to parent (to re-enable inheritance)
- [ ] Define `ShouldSerialize` / `Reset` methods that use `PropertyStore.ContainsKey`
- [ ] Define `On[Property]Changed` must guard against disposal, invoke event handler, then iterate children calling `OnParent[Property]Changed`
- [ ] Define `OnParent[Property]Changed` must check whether child has an explicit value before propagating
- [ ] Document the constructor ordering hazard and how PropertyStore avoids it
- [ ] Document which existing WinForms properties are ambient (Font, BackColor, ForeColor, Cursor, BindingContext, DataContext) as reference implementations
- [ ] Review `DataContext` implementation for conformance and identify .NET 11 retrofit items
## Acceptance Criteria
- A new Skill file at `.github/skills/ambient-properties/SKILL.md`
- The Skill is self-contained and can be used by Copilot agents to implement new ambient properties
- The Skill references concrete code examples from the WinForms codebase
- Any `DataContext` retrofit items are tracked as separate issues
Contributor guide
Assessment
This issue has not been assessed yet.