skills.rest
dotnet
dotnetOFFICIAL
Explore all skills by this author →
Website𝕏@dotnetfdnGitHub

using-and-extending-gdi-plus

Guides GDI+ drawing practices and System.Drawing API additions in WinForms.

1.2k|337|Updated Oct 13, 2022
Search Tags:#graphics#Caching#winforms#GDI+#DotNet#system.drawing#drawing api
One-click install
npx skills add https://github.com/dotnet/dotnet --skill using-and-extending-gdi-plus
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: using-and-extending-gdi-plus
Source: https://github.com/dotnet/dotnet/tree/main/src/winforms/.github/skills/using-and-extending-gdi-plus
Command: npx skills add https://github.com/dotnet/dotnet --skill using-and-extending-gdi-plus

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

WinForms developers need consistent rules for using GDI+ efficiently (caching pens and brushes, managing graphics state, disposing resources) and a strict pattern for adding new drawing APIs to System.Drawing without breaking versioning or documentation conventions.

Core Features & Use Cases

  • Performance-oriented drawing rules: Use cached pen/brush scopes, SystemPens/SystemBrushes, and GraphicsInternal to reduce allocation overhead in control painting.
  • State and resource management: Save and restore graphics state (SmoothingMode, clip, transform) and correctly dispose non-cacheable GDI+ objects like GraphicsPath.
  • New API authoring pattern: Add Draw/Fill primitives and GraphicsPath methods with .NET version guards, integer/float overload pairs, and proper XML documentation.
  • Use Case: When adding a DrawRoundedRectangle API to System.Drawing, follow the checklist to guard it with #if NET11_0_OR_GREATER, provide both Rectangle and RectangleF overloads, and place it adjacent to DrawRectangle.

Quick Start

Ask the AI to review or write WinForms painting code that uses cached pens and brushes and properly restores graphics state.

Frequently Asked Questions about using-and-extending-gdi-plus

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I cache pens and brushes in WinForms drawing code?▼

Use SystemPens and SystemBrushes for system colors, or call GetCachedPenScope() and GetCachedSolidBrushScope() on a Color for custom colors. Always use var with a using declaration, and never dispose objects from SystemPens or SystemBrushes.

How do I add a new drawing API to System.Drawing Graphics?▼

Guard the API with #if NET11_0_OR_GREATER, provide integer and float overloads where the integer overload delegates to the float one, add Draw and Fill pairs, and add a matching GraphicsPath Add method. Document the float overload fully and use inheritdoc on the integer overload.

Should I use Graphics or GraphicsInternal in WinForms paint handlers?▼

Prefer e.GraphicsInternal in control painting because it avoids unnecessary state saves. Do not pass GraphicsInternal to other methods, and if you modify clip or transform, save the state and restore it in a finally block.

When can I not use cached pens in GDI+ code?▼

Cached pens cannot be used when the pen needs additional configuration during its lifetime, such as DashStyle, CustomStartCap, or Inset. In those cases create a non-cached Pen and dispose it explicitly with using.

Why must new System.Drawing APIs have a .NET version guard?▼

System.Drawing.Common ships as part of the shared framework, so version guards like #if NET11_0_OR_GREATER ensure new APIs only appear on the approved .NET version. This prevents accidental use on older runtimes during servicing or before a new version branch snaps.

Related Skills

Explore More Software Engineering Skills→
microsoftmicrosoft
19

managing-winforms-rendering

Implement custom painting and rendering for WinForms applications using GDI and GDI+ APIs.

Official
Advanced
code-review-benchmarkcode-review-benchmark

forge-stencil-testing

Implement stencil buffer testing in SDL GPU projects for per-pixel masking and portal effects.

Official
Advanced
microsoftmicrosoft
19

creating-winforms-custom-controls

Construct custom WinForms controls with rendering, theming, and designer support.

Official
Advanced
alexFrankfurtalexFrankfurt

rich-edit-fraction

Render two-dimensional fractions on Windows Rich Edit controls using GDI overlay.

Community
Advanced