Add documentation and in-code awareness for shared WinForms/WPF clipboard/OLE infrastructure

[Copilot]

Completed: Shared WinForms/WPF Clipboard/OLE Documentation

• Create comprehensive documentation file docs/shared-wpf-infrastructure.md (11KB, 189 lines) explaining:
  • Which components are shared (System.Private.Windows.Core)
  • How sharing works (transport package, ingestion via WindowsDesktop SDK)
  • Concrete case studies (WPF Regression in .NET 10: CFG violation (Indirect call guard check) when accessing Clipboard #14308/[release/8.0] Update dependencies from dotnet/arcade #11402 and WinForms Fix bugs in the shared Clipboard code for WPF #11401 and #11402. #14257/[release/10.0]: Avoid double free of STGMEDIUM while fetching stream data from clipboard #14296)
  • Advantages (consistency, single fix benefits both) and liabilities (coupling, regression risk)
  • Detailed guidance for contributors with validation checklist
  • References to issues Document shared Clipboard/OLE architecture between WinForms and WPF (advantages and risks) #14304 and Add explicit comments in shared clipboard/OLE code warning that it is used by both WinForms and WPF #14305
• Add explicit in-code comments to shared OLE/clipboard code:
  • Composition.NativeToManagedAdapter.cs - Core data object adapter
  • Composition.cs - Main composition class
  • Comments clearly state code is shared between WinForms and WPF
  • Comments reference the new documentation
• Update docs/developer-guide.md to reference new shared infrastructure doc
• Address code review feedback from @JeremyKuhne:
  • Remove servicing complexity statement (backports flow naturally)
  • Update ComScope disposal guidance
  • Add comprehensive code review considerations
  • Add WPF validation guidance with local testing options

Summary

This PR adds critical documentation and in-code awareness about the shared clipboard/OLE implementation used by both WinForms and WPF. The documentation provides detailed case studies of recent issues (WPF #14308/#11402 fixed via WinForms #14257), explains the packaging and ingestion mechanism, and gives clear contributor guidance for working with shared code.

References:

• Addresses Document shared Clipboard/OLE architecture between WinForms and WPF (advantages and risks) #14304
• Addresses Add explicit comments in shared clipboard/OLE code warning that it is used by both WinForms and WPF #14305
• Related: WPF issues Regression in .NET 10: CFG violation (Indirect call guard check) when accessing Clipboard #14308, Regression: Clipboard.GetText() returns empty string or corrupted text (mojibake) randomly in .NET 10 #14322
• Related: WinForms PRs Fix bugs in the shared Clipboard code for WPF #11401 and #11402. #14257 (merged), [release/10.0]: Avoid double free of STGMEDIUM while fetching stream data from clipboard #14296 (draft backport)

Original prompt

Create documentation in dotnet/winforms to explain the shared Clipboard/OLE implementation used by both WinForms and WPF, and add explicit in-code comments to raise awareness of the shared usage.

Repository: dotnet/winforms
Base branch: main

Context / motivation:

• Recent fixes in dotnet/winforms PR Fix bugs in the shared Clipboard code for WPF #11401 and #11402. #14257 (“Improve clipboard/OLE data handling and test coverage”, merged 2026-01-31) addressed WPF issues Regression in .NET 10: CFG violation (Indirect call guard check) when accessing Clipboard #14308 and Regression: Clipboard.GetText() returns empty string or corrupted text (mojibake) randomly in .NET 10 #14322 because the underlying code is shared (via System.Private.Windows.Core). This included:
  • Preventing double-release of IStream in TryGetIStreamData when using STGMEDIUM TYMED_ISTREAM (avoid ComScope because ReleaseStgMedium releases the stream).
  • Returning null instead of corrupted data when GetData fails (clipboard contention between QueryGetData and GetData).
  • Hardening UTF-8 HGLOBAL string reading.
  • Adding tests/mocks and adding CLIPBRD_E_CANT_OPEN constant.
• A follow-up draft PR [release/10.0]: Avoid double free of STGMEDIUM while fetching stream data from clipboard #14296 targets release/10.0 as a focused backport for WPF Regression in .NET 10: CFG violation (Indirect call guard check) when accessing Clipboard #14308, demonstrating that changes in this repo can be necessary to fix WPF-reported issues, increasing the need for explicit guidance.
• The repo contains packaging/transport docs indicating WPF consumes artifacts from this repo (pkg/Microsoft.Private.Winforms/README.md) and tooling that states System.Private.Windows.Core is used by both WPF and WinForms.

Work items:

1. Add a new documentation file under docs/ that explicitly explains:

   • Which components are shared (focus on System.Private.Windows.Core, especially src/System.Private.Windows.Core/src/System/Private/Windows/Ole/).
   • How sharing works at a high level (transport package, WindowsDesktop shared framework ingestion into WPF and WindowsDesktop).
   • Concrete examples/case studies:
     • WPF Regression in .NET 10: CFG violation (Indirect call guard check) when accessing Clipboard #14308 / WinForms Fix bugs in the shared Clipboard code for WPF #11401 and #11402. #14257 and [release/10.0]: Avoid double free of STGMEDIUM while fetching stream data from clipboard #14296 (double-release of IStream / STGMEDIUM).
     • WPF Regression: Clipboard.GetText() returns empty string or corrupted text (mojibake) randomly in .NET 10 #14322 / WinForms Fix bugs in the shared Clipboard code for WPF #11401 and #11402. #14257 (GetData failure leading to uninitialized STGMEDIUM reads/corrupted data).
   • Advantages: consistent behavior, single fix benefits both stacks, shared test coverage.
   • Liabilities/risks: coupling, regressions affecting both, servicing/backport complexity, validation requirements.
   • Guidance for contributors:
     • When touching shared code, consider WPF impact, add/adjust tests.
     • Prefer small, targeted changes for release branches; larger changes can land in main.
     • Add cross-repo references in PRs when a bug is tracked in WPF.
     • Suggested validation matrix.
   • Link to existing packaging doc: pkg/Microsoft.Private.Winforms/README.md.
   • Reference the two new issues to be addressed:
     • Document shared Clipboard/OLE architecture between WinForms and WPF (advantages and risks) #14304
     • Add explicit comments in shared clipboard/OLE code warning that it is used by both WinForms and WPF #14305

2. Add explicit comment(s) in the shared clipboard/OLE code to make the shared usage obvious to maintainers and contributors.

   • At minimum, add a clear, visible comment near the relevant shared area, such as at the top of:
     src/System.Private.Windows.Core/src/System/Private/Windows/Ole/Composition.NativeToManagedAdapter.cs
     noting that this code path is used by both WinForms and WPF, and pointing to the new docs file.
   • Keep comments factual, concise, and non-noisy.

3. Update any docs index/TOC if the repo has one in docs/ (only if appropriate and existing).

4. PR should:

   • Be titled clearly (e.g., “Add docs and in-code guidance for shared WinForms/WPF clipboard OLE implementation”).
   • Mention issues Document shared Clipboard/OLE architecture between WinForms and WPF (advantages and risks) #14304 and Add explicit comments in shared clipboard/OLE code warning that it is used by both WinForms and WPF #14305 in the PR description.
   • Ensure docs are accurate, neutral tone, and actionable.

Notes:

• Use four-backtick fenced blocks for Markdown files if needed.
• The goal is awareness and guidance; do not attempt to change behavior beyond adding comments and docs.

Relevant file references:

• pkg/Microsoft.Private.Winforms/README.md
• pkg/Microsoft.Private.Winforms/sdk/dotnet-wpf/* (ingested by WPF)
• src/System.Private.Windows.Core/src/System/Private/Windows/Ole/Composition.NativeToManagedAdapter.cs

No images provided.

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Microsoft Reviewers: Open in CodeFlow

[KlausLoeffelmann]

@JeremyKuhne, Copilot created this PR for the documentation.
This is NOT time critical.
If you get to it, please take a quick look if this can go in, or if Copilot pointed anything out incorrectly.

@Shyam-Gupta, @merriemcgaw FYI.

[Shyam-Gupta]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.24067%. Comparing base (dc6c73b) to head (0459a02).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@                 Coverage Diff                 @@
##                main      #14306         +/-   ##
===================================================
+ Coverage   77.18299%   77.24067%   +0.05767%     
===================================================
  Files           3279        3279                 
  Lines         645137      645107         -30     
  Branches       47730       47731          +1     
===================================================
+ Hits          497936      498285        +349     
+ Misses        143518      143126        -392     
- Partials        3683        3696         +13     

Flag	Coverage Δ
Debug	77.24067% <ø> (+0.05767%)	⬆️
integration	19.10189% <ø> (+0.10594%)	⬆️
production	52.17876% <ø> (+0.11781%)	⬆️
test	97.41577% <ø> (+0.01097%)	⬆️
unit	49.55146% <ø> (+0.05630%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[KlausLoeffelmann]

Looks plausible to me as it is.

[JeremyKuhne]

Left some feedback. I'm the original implementer of this logic.

[JeremyKuhne]

@KlausLoeffelmann it might be useful to task @copilot to create another PR and document to detail step-by-step how to manually consume the shared changes in the WPF repo.