# 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.