# Concepts

### Overview

**System.Drawing.Managed** is a fully managed, cross-platform implementation of the classic `System.Drawing` API.

It is designed as a **drop-in replacement** for Microsoft’s **System.Drawing.Common**, which has been **deprecated on non-Windows platforms** and lacks any official successor.

Developed by [**IceTeaGroup**](https://iceteagroup.com/) **and** [**SixLabors**](https://sixlabors.com/), `System.Drawing.Managed` re-implements nearly all functionality of the original library in **pure C#**, removing any dependency on native GDI+ or platform-specific imaging components. It was created **primarily to support Wisej.NET 4**, ensuring that it runs consistently on **all platforms** while **removing any dependency on native libraries** such as GDI+ or libgdiplus.

\
The library re-implements nearly all functionality of the original `System.Drawing.Common` in **pure C#**, eliminating interop and native calls. This makes it ideal for **server-side rendering, cross-platform UI frameworks, image manipulation, and reporting** scenarios that require predictable behavior across all operating systems.

***

### Background

Microsoft’s `System.Drawing.Common` originated from the Windows-specific `System.Drawing` assembly, which wraps the unmanaged **GDI+** graphics subsystem.\
While this design worked well on Windows, it was never portable:

* On **Linux and macOS**, it depended on **libgdiplus**, which has always been incomplete and inconsistent with GDI+ behavior.
* On **iOS and Android**, `System.Drawing.Common` was never supported.
* Starting with **.NET 6**, Microsoft deprecated it outside of Windows.

This left developers without a compatible 2D graphics library that follows the familiar `System.Drawing` programming model.

**System.Drawing.Managed** fills that gap.

***

### Architecture

#### Fully Managed Engine

At its core, `System.Drawing.Managed` is powered by a **pure C# graphics and imaging engine** built upon a customized and integrated version of [**ImageSharp**](https://sixlabors.com/products/imagesharp/).\
The entire implementation is contained within a **single assembly (`System.Drawing.Managed.dll`)**, ensuring easy deployment and zero native dependencies.

Key architectural goals:

* **No interop** — no calls to GDI+, libgdiplus, or other native APIs.
* **Deterministic behavior** — identical results on every supported platform.
* **Self-contained assembly** — all imaging and font rendering logic resides within the library.
* **Compatible namespace** — maintains `System.Drawing.*` for seamless porting.

#### Dual-Mode Behavior (Managed + NETFX Wrapper)

When targeting **.NET Framework (NETFX)**, certain imaging classes (such as `Bitmap`, `Graphics`, and `Image`) are **wrappers around native System.Drawing (GDI+)** for performance and memory efficiency.\
However, **all font rendering and measurement** is performed using the managed engine to guarantee consistent text layout across platforms.

When targeting **.NET (Core / 5+ / 6+ / 8+)**, the entire library runs in **fully managed mode**, using only the internal ImageSharp-based backend.

This hybrid approach ensures:

* Cross-platform parity in rendering results.
* Seamless compatibility with legacy Windows code.
* Maximum performance under .NET Framework.

***

### Key Benefits

| Feature             | System.Drawing.Common         | System.Drawing.Managed                                       |
| ------------------- | ----------------------------- | ------------------------------------------------------------ |
| Cross-platform      | ❌ Limited (Windows only)      | ✅ Fully cross-platform (Windows, Linux, macOS, iOS, Android) |
| Native dependencies | ❌ Requires libgdiplus or GDI+ | ✅ None — 100% managed C#                                     |
| Deployment          | ❌ Platform-specific           | ✅ Single self-contained DLL                                  |
| Consistent results  | ❌ Varies per OS               | ✅ Identical on all OS                                        |
| Font rendering      | ❌ Platform-dependent          | ✅ Managed, identical metrics everywhere                      |
| Future-proof        | ❌ Deprecated                  | ✅ Actively maintained                                        |

***

### Using System.Drawing.Managed

#### Installation

Install the NuGet package:

```bash
dotnet add package Managed.System.Drawing
```

> The package name is `Managed.System.Drawing` because NuGet reserves the `System.*` prefix.\
> The assembly name is **System.Drawing.Managed.dll**, and it defines the namespace **System.Drawing**.

#### Code Compatibility

No code changes are required for most applications.\
Simply reference `System.Drawing.Managed` instead of `System.Drawing.Common`, and rebuild.

Example:

{% code overflow="wrap" %}

```csharp
using System.Drawing;

var image = new Bitmap(200, 200);
using (var g = Graphics.FromImage(image))
{
    g.Clear(Color.White);
    g.DrawEllipse(Pens.Blue, 10, 10, 180, 180);
    g.DrawString("Hello, Managed!", new Font("Arial", 16), Brushes.Black, new PointF(30, 90));
}

image.Save("test.png");
```

{% endcode %}

This code runs identically on **Windows, Linux, macOS, iOS, and Android**.

No additional dependencies or configuration are required.

#### Font Consistency

Fonts are rendered through the integrated managed font engine (derived from ImageSharp), ensuring consistent text metrics and layout across platforms.\
This allows server-side text rendering and client-side rendering to match exactly, which is critical for applications that generate reports or images dynamically.

***

### Limitations

While the goal is full API compatibility, some rarely used features are still being implemented or differ by design:

* Certain advanced GDI+ imaging effects and region operations are not yet supported.
* GDI+ specific features (e.g., metafiles, DC handles, printer contexts) are not applicable.
* On .NET Framework, the imaging layer uses the system GDI+ engine — results are identical, but not fully managed.

These differences are generally minor and only affect low-level interop code.

***

### Integration Scenarios

#### Drop-in Replacement for Existing Applications

If your project references `System.Drawing.Common`, simply replace it with `System.Drawing.Managed`.\
In most cases, no code changes are necessary.

#### Cross-Platform Applications

For cross-platform libraries and frameworks (such as **Wisej.NET**, **ASP.NET**, or **MAUI**), use `System.Drawing.Managed` to ensure consistent rendering across Windows and non-Windows platforms.

#### Server-Side Rendering

Ideal for scenarios such as:

* Generating images or thumbnails.
* Rendering charts or PDF content.
* Creating dynamic UI previews or reports.

Because it’s fully managed, it can run safely in **Docker containers**, **cloud services**, or **restricted environments** without native dependencies.

***

### Alternatives and Why They Fall Short

| Alternative                         | Description                                      | Limitation                                                |
| ----------------------------------- | ------------------------------------------------ | --------------------------------------------------------- |
| **Microsoft System.Drawing.Common** | Original GDI+ wrapper                            | Deprecated and unsupported on non-Windows OS              |
| **SkiaSharp**                       | Cross-platform 2D graphics library based on Skia | Different API — not compatible with `System.Drawing`      |
| **ImageSharp**                      | Pure C# imaging library                          | Excellent but not API-compatible; requires rewriting code |
| **CairoSharp / libgdiplus**         | Bindings to native libraries                     | Requires native dependencies; inconsistent behavior       |

`System.Drawing.Managed` combines the **API familiarity of System.Drawing** with the **portability and safety of** [**ImageSharp**](https://sixlabors.com/products/imagesharp/), making it the only practical **drop-in** alternative.

***

### Summary

`System.Drawing.Managed` provides a **future-proof**, **cross-platform**, and **fully managed** implementation of the familiar `System.Drawing` API. It lets developers write once and run anywhere — without worrying about missing native libraries, inconsistent metrics, or unsupported platforms.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.wisej.com/system.drawing.managed/concepts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.