Getting Started

Wisej.NET 4 introduces significant improvements driven by two main factors:

• The adoption of a .NET Core-only designer

• The replacement of GDI+ with our managed graphics system

The .NET Core-only designer, in addition to the existing .NET Framework 4.8 designer enables projects to use the latest .NET Core libraries without maintaining .NET Framework compatibility.

Replacing GDI+ with our managed System.Drawing library standardizes font measurements across platforms and removes the need for libgdiplus on Linux systems.

.NET Core Designer

Rebuilding Wisej.NET designers for the out-of-process .NET Core Designer required substantial changes and may present challenges in upcoming builds. Please be prepared to troubleshoot potential issues as we refine the implementation.

Because Visual Studio uses the .NET Framework, Microsoft divided the designer into two parts: the "client" component running on the .NET Framework within Visual Studio and the "server" component running in a hidden .NET Core process. These components connect through an interprocess communication framework. For details on these Visual Studio changes, visit Microsoft's documentation.

For details on the .NET Core designer in Wisej.NET 4, visit:

Managed Graphics

System.Drawing in .NET Framework and System.Drawing.Common In .NET Core wrap Windows GDI+, the graphics device interface is used to render graphics and load fonts on Windows. System.Drawing.Common extends to Linux using libgdiplus. Microsoft provides no graphic support in .NET Core for iOS or Android platforms.

In Wisej.NET 3.5, font loading used different libraries per platform. .NET Framework 4.8 used System.Drawing with Windows GDI+. .NET Core used System.Drawing.Common with libgdiplus on Linux. Wisej.NET Hybrid applications used an early System.Drawing reimplementation using ImageSharp for iOS and Android. This caused font measurement differences across platforms.

Read below to understand how these changes affect your projects and potential issues to avoid:

Fluent Markup

Microsoft introduced Fluent Markup extensions for .NET Multi-platform App UI (MAUI), which are documented at Fluent Markup Extensions. These extensions streamline declarative UI development in code.

Wisej.NET 4 incorporated comprehensive support for Fluent Markup syntax in both C# and VB.NET, enabling consistent coding across programming languages.

For an introduction to Wisej.Web.Markup extensions, visit:

Markdown Support

Wisej.NET controls with labels include the AllowHtml property for HTML tags in text.

We've added the AllowMarkdown property to complement AllowHtml. This property enables markdown text rendering across Wisej.NET controls - expanded text formatting options.

Enhancements and Changes

Service Provider

Application.Services methods are now chainable, allowing concise syntax like Application.Services.AddService<Service1>().AddService<Service2>().

The new AddOrReplaceService method replaces a service without requiring prior removal.

HttpOnly Cookies

We now fully support HttpOnly cookies. Previously, developers could use HttpOnly cookies through the native HttpContext. The Wisej.Base.Cookie class now includes a property for managing HttpOnly cookies.

ControlRendered and ControlUpdated Events

All controls now include the ControlRendered and ControlUpdated events. This allows applications to modify control JSON rendering and handle browser updates without subclassing.

These events enable Wisej.AI to add AI capabilities to any Wisej.NET control.

Updated Templates

All C# templates have been revised to incorporate the latest C# syntax enhancements, specifically utilizing file-scoped namespaces and top-level statements.

The updated file-scoped namespace declaration is now implemented across all .cs files. However, the transition to top-level statements is applied exclusively to the Startup.cs file. This modern approach simplifies the code structure, making it cleaner and easier to read.

Upgrade from 3.x

Some Wisej.NET projects need changes in .resx (resource) and .Designer.cs (designer) files for Wisej.NET 4 and managed System.Drawing compatibility.

To facilitate this transition, we have provided an upgrade tool that automatically implements these changes across your project files.

For detailed instructions, visit:

.NET Framework and VB.NET Support

Wisej.NET continues to support .NET Framework 4.8 (and newer) and VB.NET at both runtime and design time. As with all preceding versions, we will maintain this support for the foreseeable future.

Wisej.NET 3.5 Support

To facilitate a smooth transition from Wisej.NET version 3.5 to version 4.0, we will continue to maintain the 3.5 branch by providing bug fixes and enhancements for at least one year following the initial stable release of version 4.0. This ensures ongoing support and stability for existing users during their upgrade process.

Overview

.NET (formerly .NET Core) version 7.0.0 and later no longer supports System.Drawing.Common on Linux. This change leaves Linux users without a direct, Microsoft-provided alternative.

Additionally, .NET code running on iOS or Android platforms has never supported any version of System.Drawing.Common. Microsoft recommends using alternative libraries such as ImageSharp or SkiaSharp for these platforms.

In Wisej.NET 3, there are three graphics implementations: GDI+ on Windows, libgdiplus on Linux, ImageSharp on iOS and Android. All three implementations provide different font measurements, leading to inconsistencies across platforms.

Our new System.Drawing.Managed implementation delivers consistent performance across all platforms and aligns much more closely with the browsers' font measurements. This ensures a uniform experience regardless of the deployment platform.

Wisej.NET 4 Usage

Wisej.NET requires a graphics library for loading images from files or embedded resources and measuring text on the server side for controls AutoSize set to true. No painting functionality is needed within Wisej.NET.

Applications built on Wisej.NET can use the Paint event to draw on controls or within grid cells, enabling complex UI features.

The Wisej.NET 4 package includes this dependency:

<PackageReference Include="Managed.System.Drawing" Version="4.0.*-*" />

The namespace remains System.Drawing, so no code changes are needed. All primitives like Point, Size, and Color come from System.Drawing.Primitives. System.Drawing.Managed classes like Font and Image can cast to and from their System.Drawing.Common (GDI+) counterparts.

Platforms Support

System.Drawing.Managed (and ImageSharp) has two major implementations: Font and Graphics. Font handles loading, measuring, and rendering fonts. Graphics handles loading, saving, and drawing images, providing operations available in System.Drawing.Graphics.

Only the Font implementation is available on the .NET Framework because ImageSharp's Graphics implementation relies on graphics acceleration primitives exclusive to .NET Core.

In Wisej.NET 4 for .NET Framework, we shield developers from this difference. Although Font and Image come from System.Drawing.Common, all font measurements use the managed System.Drawing.Font internally, ensuring compatibility with .NET Core deployments.

As explained on the .NET Core Designer page, using the Visual Studio Designer required building a version of Wisej.Framework compatible with "net8.0-windows". This build uses System.Drawing.Common for public properties.

For deployment, we recommend using the non-OS-specific net8.0 target instead of "net8.0-windows" as it uses only managed code.

As shown above, System.Drawing (GDI+) is only used for deployment on Windows servers using the .NET Framework.

Namespace Collision

Wisej.NET imports System.Drawing on .NET Framework targets and System.Drawing.Common on .NET Core targets to enable multi-targeting. It also imports System.Drawing.Managed. Since all three use the same namespace, failing to alias them may cause compiler errors, such as the Font class being available in multiple assemblies.

Since all three use the same namespace, failing to reference one of the assemblies correctly may cause compiler errors, such as the Font class being available in multiple assemblies.

In Wisej.NET 4, we reference and alias System.Drawing.Common like this:

<!-- NETCORE:
	Include aliased System.Drawing.Common, it's almost never used. It's a required dependency for
	Managed.System.Drawing on netcore to provide optional implicit casting to/from native GDI+ types.
-->
<ItemGroup Condition="!$(TargetFramework.Contains(`-windows`)) And '$(TargetFramework.TrimEnd(`0123456789`))'!='net'">
	<PackageReference Include="System.Drawing.Common" Version="$(_TargetFrameworkVersionWithoutV).0" Aliases="sdc" ExcludeAssets="compile"/>
</ItemGroup>

Alternative Libraries

Here are Microsoft's four alternatives and our assessment of each:

ImageSharp

Fully Managed Code: With no native dependencies or interop code, ImageSharp simplifies development and can be installed anywhere supports.NET 6+- anything from external devices to embedded/IoT scenarios.

ImageSharp is a managed graphics library that handles various graphic formats, including WebP. Combined with its Fonts library, it provides a foundation for implementing a cross-platform version of System.Drawing.

We licensed the ImageSharp source code and worked with SixLabors' founder to create System.Drawing.Managed. This single, self-contained, managed .NET library replaces System.Drawing.Common on all platforms, ensuring consistent font measurements across browsers and platforms.

SkiaSharp

SkiaSharp is a cross-platform 2D graphics API for .NET platforms based on Google's Skia Graphics Library. It provides a comprehensive 2D API for rendering images for mobile, server, and desktop models.

Developed by the Mono team, this library offers classes built around Google's native Skia library. It requires different native assets for platforms and differs from System.Drawing basic operations like reading font size or measuring text. It cannot measure wrapping lines of text without extensions. Our tests showed font measurements that differed from those of Chromepite Chrome using Skia; it appears to use many extensions and modifications.

Aspose.Drawing

The Aspose.Drawing package provides a completely managed re-implementation of System.Drawing. While it offers excellent GDI+ compatibility, it uses a different namespace and requires a commercial license.

Microsoft.Maui.Graphics

Provides interfaces, classes, and supporting types for .NET MAUI Graphics, the abstracted, unified drawing APIs that work cross-platform.

A thin wrapper with limited functionality around Microsoft.Graphics.Win2D (a wrapper around UWP and WinUI platforms) and Microsoft.Maui.Graphics.Skia (a wrapper around SkiaSharp, which wraps Skia).

It provides minimal functionality to replace System.Drawing.Font or Image and gives different results on different platforms. It requires many dependencies and native bindings from various sources.

Overview

Fluent Markup is a collection of helper methods and classes aimed at simplifying the creation of declarative .NET App UI in code.

While Wisej.NET allows you to use the designer to build rich UI components, there are many occasions where it is necessary to build or modify visual components through code. The new Wisej.Web.Markup extensions make this task significantly more enjoyable.

Examples

Currently, if you want to add a Button with a label, a data-bound text with binding events, and attach a "click" event to the button, you would need to write code similar to the following:

var textBox = new TextBox
{
	LabelText = "Name:",
	Location = new Point(20, 20),
	Size = new Size(150, 24)
};
var binding = textBox.DataBindings.Add("Text", dataSource, "FirstName");
binding.Format += (s, e) => { 
	e.Value = e.Value.ToString().ToUpper();
};
var button = new Button
{
	Text = "Click me",
	Location = new Point(20, 50),
	Size = new Size(80, 32),
};
button.Click += (s, e) => { 
	// Do something on click.
};
page.Controls.Add(button);
page.Controls.Add(textBox);

With the new Wisej.Web.Markup extensions, the same code can be written as follows:

using Wisej.Web.Markup;

page.Controls(
	new TextBox()
		.LabelText("Name:")
		.Location(20, 20)
		.Size(154, 24)
		.Bind("Text", dataSource, "FirstName", 
			format: v => v.Value.ToString().ToUpper()),
	new Button()
		.Text("Click me")
		.Location(20, 50)
		.Size(80, 32)
		.OnClick(b =>
		{
			// Do something on click.
		}
));

Properties are added as methods with the same name as the property. Events are added with the prefix ".On" followed by the name of the event.

Events that use the EventArgs type is represented by simple methods that only use the sender as a single argument. Events that pass an argument are represented by actions that take both the sender and the arguments.

For example:

// Closing event uses CancelEventArgs
form.OnClosing((f, e) => e.Cancel = false);

// Closed event uses EventArgs
form1.OnClosed(f => Debug.WriteLine($"{f.Text} is closed."));

' Closing event using CancelEventArgs
form.OnClosing(Sub(f, e) e.Cancel = False)

' Closed event using EventArgs
form.OnClosed(Sub(f) Debug.WriteLine($"{f.Text} is closed."))

Due to the extensive range of properties and events in Wisej.NET controls, we are excited to enhance the markup extensions. Additional properties and methods will be included in upcoming builds.

Overview

Transitioning to Wisej.NET 4 and the .NET Core Designer requires replacing these two classes:

1. System.Resources.ResourceManager ⇒ Wisej.Resources.ResourceManager

2. System.ComponentModel.ComponentResourceManager ⇒ Wisej.Resources.ComponentResourceManager

The rationale behind this change is that the implementation of System.Resources.ResourceManager in .NET loads the specific type specified in the resources file without providing a way to override its behvior. Consequently, when dealing with embedded images, this approach fails on Linux systems without the installation of libgdiplus, and it is inherently incompatible with iOS and Android devices, resulting in failure on those platforms as well.

Our re-implementation maintains full compatibility with all existing resources and is flexible enough to adapt to the target platform seamlessly. On Windows, it utilizes System.Drawing (GDI+), while on all other platforms, it leverages our newly developed System.Drawing.Managed, which is based on ImageSharp.

The new ResourceManager will be included in a future update of Wisej.NET 3.5 to ensure backward compatibility.

ResXFileCodeGenerator

Since the .Designer.cs or .Designer.vb file associated with a project's resources is automatically generated by Visual Studio using the ResXFileCodeGenerator tool, we have replaced it to ensure that the generated code utilizes the updated types introduced with Wisej.NET 4.

Update Tool

The Upgrade Tool is designed to automate the migration of .Designer.cs/vb files by replacing the ResourceManager references.

The tool applies the following modifications:

1. ComponentResourceManager Replaces all references to System.ComponentModel.ComponentResourceManager to Wisej.Resources.ComponentResourceManager. These are commonly found nested under the project's .resx files.

2. ResourceManager

   • Replaces all references to System.Resources.ResourceManager to Wisej.Resources.ResourceManager. These are commonly found in the designer files related to visual components.

Overview

Wisej.NET 4 now offers Markdown support alongside HTML. This enhancement benefits Wisej.AI by aligning with the preferences of LLMs for formatting responses in Markdown.

The conversion from Markdown to HTML occurs server-side, ensuring the browser receives HTML data without client-side JavaScript conversion.

For developers, we've added the AllowMarkdown property to complement the existing AllowHtml property. We also provide the System.Markdown class with a ToHtml(string) method. This method lets applications convert Markdown text to HTML format at any point.

How to Use

To use Markdown in your application, set the AllowMarkdown property to "true". Then assign the Markdown text to the "Text" property for standard controls, or to the "Value" property for DataGridViewCell objects.

The example below shows a button in the designer and the "Text" property editor. You can mix Markdown and HTML.

To convert Markdown to HTML programmatically, use the Markdown.ToHtml(text) method from the System.Markdown class:

this.label1.AllowMarkdown = true;
this.label1.Text = Markdown.ToHtml("**Bold**");

Overview

In Wisej.NET 4, we have reimplemented all designers and editors to be compatible with the new out-of-process Visual Studio designer for .NET Core. We will support both sets of designers and editors for .NET Framework and .NET Core, providing flexibility and functionality for developers in various environments.

The design experience remains unchanged, with one exception: a slight delay at startup occurs because Visual Studio needs to load the hidden DesignToolsServer.exe process. The overall functionality and user experience remain consistent.

How to Use

To maintain compatibility with the .NET Framework, you can leave your multi-targeting unchanged:

<TargetFrameworks>net48;net8.0</TargetFrameworks>

To eliminate dependencies on the .NET Framework and switch to using only the .NET Core designer, you will need to employ multi-targeting exclusively with .NET Core targets:

<TargetFrameworks>net8.0-windows;net8.0</TargetFrameworks>

⚠️ Replace your target framework from "net48" to "net8.0-windows"and leave the rest unchanged.

Replace your target framework from "net48" to "net8.0-windows", and leave the rest unchanged.

The net8.0-windows target is required to load the Visual Studio designer because it relies on Windows controls. You won't deploy net8.0-windows itself. Instead, deploy net8.0 on both Windows and Linux platforms.

New Startup Wizard

When you choose one of the updated templates, categorized under Project Type as either Wisej.NET 4 or Wisej.NET 4 Hybrid, you will be presented with the new startup wizard shown below.

The primary change is that you can now independently choose .NET Framework and .NET Core versions. Additionally, under the .NET Framework option, you can select "(None)". The project will be configured with the specific settings relative to each target, either included or excluded, based on your selection.

Image Changes

If your projects use local and global embedded images in .resx files, you will need to update the type attribute in all .resx files and change all casts from System.Drawing.Bitmap to Wisej.Base.ResourceImage.

If you are using System.Drawing.Bitmap, System.Drawing.Image, or relying on image names, no changes are necessary.

Refer to the page below for instructions on how to update your projects manually or using the provided tool:

Compatibility

Please be aware that .NET Core is capable of reading all designer files initially created with .NET Framework. However, if the designer code is subsequently updated in .NET Core, it may become incompatible with the .NET Framework designer. Specifically, the .NET Core designer modifies the serialized code in the following ways:

1. It removes the this keyword. For example, the line this.button1.Text = "button1" is simplified to button1.Text = "button1".

2. It also eliminates the use of the delegate class when attaching to events. For example, this.button1.Click += new System.EventHandler(this.button1_Click); is simplified to button1.Click += button1_Click;.

The first change, which involves the removal of the this keyword, maintains compatibility between .NET Core and .NET Framework.

However, if you open the designer code that has been updated in .NET Core using the .NET Framework designer, all the event handlers will be lost. This is due to the change in how delegate instances are created and attached to events.

Architecture

With .NET Framework, everything, including your application, Wisej.NET designers, editors, and serializers, was integrated and run within Visual Studio. With .NET Core, this integration isn't feasible because Visual Studio cannot directly load .NET Core code.

Microsoft divided the designer system into two main components:

• A "client" component running on .NET Framework within Visual Studio

  • Manages Visual Studio elements like "menus," "toolbars," "property editors," "edit windows," and the "property grid."

• A "server" component running in a hidden .NET Core process

  • Loads your Wisej.NET code and executes it to render designer windows

  • "Injects" these windows into Visual Studio through the DesignToolsServer.exe process

• These components communicate through an interprocess framework:

  • The client sends request packets for themes, classes, and application data

  • The server processes these through handlers and returns responses

For details on these Visual Studio changes, visit Microsoft's documentation.

Custom Designers

If you have developed a custom designer, contact us for support on making it compatible with the .NET Core out-of-process designer system.