Wisej.NET is the most advanced, enterprise-scale, ASP.NET and ASP.NET Core development system in .NET. It covers just about the entire spectrum of features that business developers need to build and manage complex web applications.

It is also a Rapid Web Development system, thanks to its unique WYSIWYG pixel-perfect designer integrated into Visual Studio, and its familiar component object model.

Developers can achieve in a few days what would take months, if at all possible, with any other web framework. The power and versatility of Wisej.NET also mean that it's a large and sophisticated system, with hundreds of features and several ways to accomplish most tasks.

Documentation

Overview

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.

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

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:

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.

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

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.

Visual Studio Requirements

Make sure that you have installed these 2 workloads:

• ASP.NET and web development

• .NET desktop development (needed for the designer)

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.

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

Diagnostic Tool

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.

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.

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

Managed Graphics

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

Fluent Markup

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

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

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

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.

Updated Templates

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.

Collection Editors

Editors, especially collection editors, present the most significant challenges when migrating to the out-of-process designer. As of now, we have integrated the following collection editors using the basic editor system that comes with the designer. However, we are planning to transition the more complex editors in an upcoming release.

• DataGridView columns editor

• TreeControl nodes editor

• Menu items editor

Data Binding

Data binding and the associated editors function as expected. However, it's worth noting that Microsoft has not yet provided an implementation for the typed DataSet editor. Currently, Microsoft suggests using the new Object Data Source Binding as an alternative to accommodate this gap.

BinaryFormatter and .NET 9

If you prefer to use .NET 9 or .NET 10 instead of .NET 8, you can do so with minimal issues. However, it's important to note that with .NET 9, Microsoft has completely removed the BinaryFormatter, as part of their ongoing initiative to improve developer security by protecting them from themselves.

Interestingly, they have reintroduced the same "unsafe" classes by offering them as a NuGet package.

This change affects all designer .resx files that contain values serialized with the BinaryFormatter. While these files are safe as internal .resx files — something even Microsoft acknowledges — they will not load properly in .NET 9 and above unless you include the following NuGet package reference in your project:

<PackageReference 
    Include="System.Runtime.Serialization.Formatters" 
    Version="9.0.0-*" />

Additionally, we are actively working on removing the binary serialization of custom snap lines and responsive properties to align with the latest security practices and ensure optimal compatibility with .NET 9 and new releases.

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:

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:

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

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 are 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:

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.

Wisej.NET 3.5 adds native support for hybrid applications running on all sorts of devices, including full offline support, and many enhancements to the .NET class library and the corresponding JavaScript widgets.

Getting Started

The Visual Studio 2019 and 2022 extension packages are linked below:

Wisej.NET Targets .NET 7

Wisej.NET 3.5 is now compiled against .NET 7. This means that existing .NET 6 projects that would like to use the latest version of 3.5 must update the target framework dependency.

Wisej.NET Hybrid and Offline Support

Wisej.NET Hybrid includes three new project templates for creating applications:

Client Application

This project template is used to create a Wisej.NET Hybrid Client. The Client project builds and runs an executable (.exe, .apk, .ipa, etc.) that can be deployed on any desktop or mobile platform.

Remote Application

Allows developers to build and deploy a traditional Wisej.NET application with the added ability of interacting with the Hybrid device's native functionalities.

This application is deployed to a remote web server such as IIS, Kestrel, or Nginx on Windows or Linux.

Local Application

Allows developers to build and deploy applications that run entirely on the Hybrid device. The project template contains similar features to the Remote application template such as a Page control.

API and Component Enhancements

In 3.5 we also focused on extending the programming side of Wisej.NET with a number of enhancements to the object model, data a binding, the various components.

New Features

• All controls that show a label gained a new AutoToolTip property. When set to true and the text is truncated, it will automatically use the title attribute to show the full label as a native tooltip.

• TextBox.Text now converts all \n to \r\n when Multiline is true. Previously Wisej.NET allowed the browser to strip \r\n and instead return only \n as a new line.

New Constructors

Most controls have gained several new constructors, some with optional and default arguments, that allow developers to use the controls in code adopting a more flexible and easier syntax:

Common Method Chaining

Bootstrap Dark Theme

Wisej.NET 3.5 includes a new theme for building dark-style applications. The new Bootstrap Dark theme (BootstrapDark-4) is based on the existing Bootstrap-4 light theme.

New Extensions

Chat Control

The new Chat control can be used to build conversations into an existing Wisej.NET application. The new chat control supports text and custom message types, allowing users to share any type of control or data in the conversation.

Signature Control

The new Signature control can be used to collect and export user signatures. The control includes undo, redo, image import/export, and line customization features.

Pull-to-Refresh Component

The new Pull to Refresh component can be used to trigger a refresh of a data source associated with a scrollable panel. All containers inheriting from ScrollablePanel support the Pull-to-Refresh component.

TesseractJS Component

The new TesseractJS component allows developers to add real-time OCR scanning to the Wisej.Web.Ext.Camera control.

New Premium Extensions

Dynamsoft Barcode & Scanning Premium Extension

• Dynamsoft Barcode Reader – JavaScript Web SDK

• Dynamsoft Document Normalizer – JavaScript Web SDK

Mobiscroll Premium Extension

Developers are required to purchase a license from Mobiscroll for use of any components. The Wisej.NET integration uses the Mobiscroll JavaScript integration.

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.

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.

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

Wisej.NET 3.2 adds new enterprise-grade features that simplify the development of complex Line of Business (LOB) cloud applications for the enterprise. Our goal is always to help improve developers productivity and make the applications using Wisej.NET more resilient and maintainable.

Getting Started

The Visual Studio 2019 and 2022 extension packages are linked below:

Validation System

We added a new Validation property extender to provide a modern, centralized, and flexible validation system to Wisej.NET applications.

Once you drop the new Validation component on a container at design time, all the controls are extended with a new property ValidationRules. You can assign multiple validation rules to any control.

JSON View Builder

With Wisej.NET 3.2 we are introducing a new concept to build views using a JSON representation. In the future we may add XML or any custom parser, and we are also planning to use the new View Builder as an optional serializer in the designer.

Enhanced Font Support

Font support has been enhanced in the JavaScript layer as well as the server side .NET layer in Wisej.NET. Now we support using theme fonts that are not installed on the server.

Premium Extension: DevExpress JavaScript Dashboard

The DevExpress Dashboard is a control that allows developers to create interactive and customizable dashboards for business intelligence (BI) purposes. The platform offers a wide range of data visualization tools and widgets, such as charts, graphs, maps, gauges, and pivot tables.

HTTPS Local Server

Added Enable HTTPS option to the new project wizard.

Now projects include the full applicationhost.config file in /Properties, or in /My Project for VB.NET, preconfigured to listen to https://localhost:44391, for IIS Express and .NET 4.8.

For .NET Core it listens to the same https://localhost:44391 URL and it doesn't need to use applicationhost.config.

General Improvements

• Speed improvements across the board.

• Consolidated bug fixes and enhancements to all controls.

• DataGridView memory footprint for large data sets has been reduced.

• New BindableComponent base class to enable data binding on components.

Advanced Design-Time Debug Mode

We added the option to enable the design-time debug mode in the Designer Options dialog. When enabled, Wisej.NET will show the Edge renderer(s) it uses to display each control in the pixel-perfect design view.

Font support has been enhanced in the JavaScript layer as well as the server side .NET layer in Wisej.NET 3.2. Now we support using theme fonts that are not installed on the server and can load all the different variations for a font family.

Private Fonts

• montserrat-bold.ttf

• montserrat-bolditalic.ttf

• montserrat-italic.ttf

• montserrat-regular.ttf

Wisej.NET will load all the montserrat-*.ttf files in a private Montserrat family and use it at runtime for autosizing and layout calculations.

Font CSS Rules

Font sources added to a theme now support specifying the font-style and font-weight properties. It allows a font family in the theme to use different sources (woff, woff2, ttf, etc.) for different styles and weights.

Until now Wisej.NET supported only the "normal" source and let the browser render the different styles and weights.

This is the definition in the theme file:

        "default": {
            "size": 13,
            "family": ["Open Sans"],
            "weight": 400,
            "sources": [{
                "fontWeight": "400",
                "fontStyle": "normal",
                "version": "1.2.3.4",
                "family": "Open Sans",
                "source": ["https://fonts.gstatic.com/s/opensans/v34/memSYaGs126MiZpBA-UvWbX2vVnXBbObj2OVZyOOSr4dVJWUgsiH0C4k.woff"]
            }]
        }

You can also reuse the same .tff files deployed in /Themes/Fonts in the sources for the font definition in the theme or theme mixin.

 "default": {
            "size": 13,
            "family": ["Montserrat"],
            "weight": 400,
            "sources": [{
                "fontWeight": "400",
                "fontStyle": "normal",
                "version": "1.2.3.4",
                "family": "Montserrat",
                "source": ["/Themes/Fonts/montserrat-regular.ttf"]
            }]
        }

Wisej.NET 3.1 enhances the milestone 3.0 release by adding several new unique features and a simplified installation procedure.

In addition to numerous bug fixes and considerable performance enhancements to our libraries, 3.1 includes the following notable new features:

Visual Studio Marketplace

Typed TextBox

A basic but very useful Typed TextBox is one of the most desired features in practically all web development platforms and is now available in our toolkit

You can use this new editor control to define the type of Value property to which the text should be parsed, a.NET format string (standard or custom), and whether the formatted string should be preserved when editing or removed when entering the editor.

You can also take over the parsing and formatting using the new events and virtual methods.

Tiny Tools in the Designer

New "Tiny Tool Icons" have been added to the Property Editor in the designer to indicate some of their attributes or reset New their value.

These new icons may save time for developers by providing information and features that needed several clicks to reach.

• Reset. Instead of having to right-click and select the Reset option (if enabled), this tiny tool allows developers to reset the value of a modified property with a single click.

• Data Bound. Indicates that a property is data-bound. This information was only available by opening the data binding dialog.

• Localizable. Indicates that the property can be localized. Previously, this information was unavailable without inspecting the source code or attempting to localize the value.

• Responsive. Indicates that the property is a Responsive Property and can hold multiple values associated with client profiles.

Horizontal ListBox

The new property ListBox.Orientation changes the layout of the items in the ListBox from the standard Vertical layout to the new Horizontal Flow layout.

Everything else remains the same, including horizontal scrolling, keyboard selection, and so on.

ObservableCollection Data Binding

Commanding

Dependency Injection

New Application Templates

Using the Visual Studio Marketplace allows us to provide new project and item templates. You can use the Visual Studio Extension Manager to install our new templates and automatically register them within Visual Studio.

F1 Integrated Help

When Wisej.NET is installed from the VSIX installer (Visual Studio Market Place or downloaded from our builds page), you can press F1 to get directed to our extensive online documentation.

The system can determine the Wisej.NET class, property, or method by the location of the cursor in the editor. This has support for the main API and all the extensions!

TestProject.io Integration

Our Wisej.NET extension helps in several ways like scrolling widgets into View, handling Tree Views, Keystrokes, counting Alert or Message Boxes, and much more.

WebAuthn Extension

We have added a new module to our open-source toolkit. The new extension employs the Web Authentication API (known as WebAuthn).

New OpenWindow Callback

This is a new experimental feature. We added a new Application.OpenWindow(url, ...) method with an optional onclose callback action, and added new onclose callback action to the existing Application.Navigate() method.

It can be used for several purposes:

• Dispose a resource (i.e. delete a file or close a handle) when the user closes the tab or the popup.

• Simulate detaching a specific window from the browser and allow the web application to work with multiple monitors.

private void Window1_ToolClick(object sender, ToolClickEventArgs e)
{
  var id = this.textBox1.Text;

  // hide Window1
  Hide();

  // launch sub-application /client passing custom args.
  Application.OpenWindow(
    $"{Application.StartupUrl}client#id={id}",
    id,
    "left=100,top=100,width=600,height=400",

    // onclose: reopen "detached" Window1.
    () => {
      Show();
    });
}

The same effect can be achieve using a browser tab that the user can detach and move to a second monitor.

When enabled, Wisej.NET will show the Edge renderer(s) it uses to display each control in the pixel-perfect design view.

You will see one or more small windows that show the renderers managed by the design view. When debugging the client side JavaScript, we recommend setting the Parallel Renderers to 1 - it's much easier to have only one Developer-Tools window open.

Click anywhere on the renderer window and press F12 to open the Developer Tools window.

With the Developer Tools open you can fully debug everything the designer renderer does on the JavaScript side. In Visual Studio you will also see the same debug view displayed in Chrome or Edge when showing the developer tools.

Using this powerful features allows widget developers to debug and test their JavaScript implementation at design time.

Wisej.NET 3 is the first release of Wisej.NET that supports both .NET Framework (4.8) and .NET Core (now .NET 6, will be 7...) and runs on Windows, Linux and MacOS.

Adding support for .NET Core and ASP.NET Core required changes to the HTTP/WebSocket layer and the implementation of a new Wisej.NET Middleware module. Everything else is fundamentally unchanged or enhanced: .NET Controls, JavaScript Widgets, Designer, Themes, Theme Builder.

We have been using Wisej.NET 3 on Linux internally on many test projects and we have run it on several Linux distributions as well as small devices like the Raspberry Pi for over a year. And we are in the process of testing it on even smaller embedded devices running custom Linux builds.

Multi Targeting

New projects can target multiple .NET platforms. When you create a new Wisej.NET 3 project, our wizard will allow you to select the target and enable certain options:

You can edit the .csproj or .vbproj at any time and change the <TargetFrameworks> tag. Just make sure that "net48" is always the first, if you want to use the designer.

.NET 6+ Windows, Linux, MacOS

Now that Wisej.NET applications can run on .NET 6+ they are standard ASP.NET Core applications. When running on .NET 4.8 they are standard ASP.NET applications.

ASP.NET Core applications don't use System.Web anymore and are not integrated with the IIS pipeline. They are all based on OWIN and Microsoft's Kestrel. Which means that they are almost always self-hosted web applications.

This is how you add Wisej.NET to a standard ASP.NET Core application:

app.UseWisej();

app.UseWisej()

New Features

While the vast majority of the work in Wisej.NET 3 has been to split the code between .NET Core and .NET Framework, replacing all of the ASP.NET code with ASP.NET Core, we have also added some cool new features.

Download Callback

Application.Download(
    Application.MapPath("Docs\\Manual.pdf"), null, (fileName) => {
        AlertBox.Show($"Thank you for downloading {fileName}");
    }
);

// Or

Application.Download(
    Application.MapPath("Docs\\Manual.pdf"), null, this.OnDownloadManual);
);

private void OnDownloadManual(string fileName) {
    AlertBox.Show($"Thank you for downloading {fileName}");
}

Application.Download(
    Application.MapPath("Docs\\Manual.pdf"), Nothing, 
        Sub (fileName As String)
            AlertBox.Show($"Thank you for downloading {fileName}")
        End Sub
)


' Or

Application.Download(
    Application.MapPath("Docs\\Manual.pdf"), Nothing, 
        AddressOf Me.OnDownloadManual)
)

Private Sub OnDownloadManual(fileName As String)
    AlertBox.Show($"Thank you for downloading {fileName}")
End Sub

This is a powerful new feature that allows an additional level of control that was not possible before.

Auto Layout

If you just need to apply a specific layout, or a combination of layouts, by code, without having to change containers, use the Control.LayoutChildren() methods:

• LayoutChildren(controls, dock, viewArea, spacing, useMargins, hAlign, vAlign)

• LayoutChildren(controls, direction, viewArea, spacing, useMargins, hAlign, vAlign)

Each method is overloaded with multiple variants and most parameters are optional using predefined values.

You can call this method as many times as you need and with as many combinations of rules as you like. It doesn't change the layout engine or the layout options, it only moves and resizes the child controls according to the specified arguments.

Commanding

public CommandDemoViewModel : BindingList<Person>
{
  public Wisej.Web.ICommand SaveCommand { get; }
  
  public CommandDemoViewModel()
  {
    this.SaveCommand = new Command<Person>(
      execute: args => {
        DB.Save(args.DataItem);
      },
      canExecute: args => {
        return  args.DataItem.Name != null &&
            args.DataItem.Age > 0;
      });
  }
}

New Interfaces

Added new interfaces that allow code to use common features across controls:

Using these interfaces eliminates the need to cast a control to the specific class.

((ILabel)control).LabelText = "Name:";

// instead of

if (control is TextBox)
    ((TextBox)control).LabelText = "Name:";
else if (control is ComboBox)
    ((ComboBox)control).LabelText = "Name:";

CType(control, ILabel).LabelText = "Name:"

' instead of

If control Is TextBox
    CType(control, TextBox).LabelText = "Name:"
Else If (control is ComboBox)
    CType(control, ComboBox).LabelText = "Name:"
End If

Service Container

Wisej.NET 3 adds a new experimental feature to support the dependency injection model natively.

Using this new feature is quite simple, flexible and very powerful. Use Application.AddService() to register a service and Application.GetService() to retrieve it. Services can be added with several scopes:

• Global. Only one instance (singleton) is shared among all sessions.

• Session. Each session gets its own instance.

• Transient. Each request gets a new instance.

When the services instance passed to AddService is null, Wisej.NET will automatically try to instantiate the service class on first use (on demand). As soon as the service goes out of scope, Wisej.NET will automatically dispose of it. If the service implements the IDisposable interface, it gets a call to IDisposable.Dispose()

A service can also be instantiated on demand in a callback.

Using the service is also quite simple. Regardless of the scope, the service consumer simply calls:

var service  = Application.GetService<ISaveService>();

// or

var service = (ISaveService)Application.GetService(typeof(ISaveService);

The return is just null if the requested service is unavailable.

DataGridView.DataRead

private void dataGridView_DataRead(object sender, DataGridViewDataReadEventArgs e)
{
    LoadRowsToCache(e.FirstIndex, e.LastIndex);
}

private void dataGridView_CellValueNeeded(object sender, DataGridViewCellValueEventArgs e)
{
    e.Value = GetValueFromCache(e.ColumnIndex, e.RowIndex);
}

Private Sub DataGridView_DataRead(sender As Object, e As DataGridViewDataReadEventArgs) Handles DataGridView1.DataRead
    LoadRowsToCache(e.FirstIndex, e.LastIndex)
End Sub

Private Sub DataGridView_CellValueNeeded(sender As Object, e As DataGridViewCellValueEventArgs) Handles DataGridView1.CellValueNeeded
    e.Value = GetValueFromCache(e.ColumnIndex, e.RowIndex)
End Sub

DataGridView.NoDataMessage

Shows like this when the grid is empty.

General Improvements

• Rolled up all bug fixes.

• Layout speed improvements on the client and server.

• Refreshed all icons in designer and Theme Builder.

We have added a new experimental extension to build all sorts of views using a plain JSON representation. It will eventually allow us to integrate it with the designer and optionally serialize views to JSON or XML rather than code in InitializeComponent.

The Wisej.Web.Ext.ViewBuilder source code is available in our public GitHub extensions repository and on NuGet.

As a simple start, this is what you can do with the ViewBuilder:

this.form1.LoadView(stream).Show();
this.form2.LoadView(model).Show();
this.form2.LoadView(jsonString).Show();

// or

ViewBuilder.Create(stream).Show();
ViewBuilder.Create(model).Show();
ViewBuilder.Create(jsonString).Show();

Me.Form1.LoadView(stream).Show()
Me.Form2.LoadView(model).Show()
Me.Form2.LoadView(jsonString).Show()

' Or

ViewBuilder.Create(stream).Show()
ViewBuilder.Create(model).Show()
ViewBuilder.Create(jsonString).Show()

In the code above you can see two ways to use the ViewBuilder: as an extension method on any ContainerControl type (Form, Page, UserControl) to create the child components inside the target control; or as a static method used to create a new view from the model.

You can also see three different input types: Stream, Object, and String:

• Stream is any stream that returns a JSON string.

• Model is any object of any kind, just like any data object or view model.

• String is a JSON string.

In all three cases, the input is an object model that is used to build the view. The code below shows a simple form with a TextBox and a Button:

// This is a JSON string.

{
  "_type": "Wisej.Web.Form",
  "text": "Builder Test",
  "windowState": "Maximized",
  "controls": [
    {
      "_type": "TextBox",
      "dock": "Top",
      "validating": "Program.OnTextBoxValidating",
      "toolTip1.ToolTip": "Type something"
    },
    {
      "_type": "Button",
      "name": "button1",
      "dock": "Top",
      "backColor": "Green",
      "click": "this.button1_OnClick"
    }
  ],
  "components": [
    {
      "_type": "Wisej.Web.ToolTip",
      "name": "toolTip1"
    }
  ]
}

// This is a .NET anonymous class.
// However, you can use any class of any kind as a model.
// The ViewBuilder will use any public property, like any data binding system.

new {
    _type = "Wisej.Web.Form",
    Text = "Builder Test",
    WindowState = "Maximized",
    Controls =
        new dynamic[] {
            new { _type = "TextBox", Dock = "Top",
                  Validating =
                      "Program.OnTextBoxValidating",
                  toolTip1_ToolTip = "Type something" },
            new {
                _type = "Button",
                Name = "button1",
                Dock = "Top",
                BackColor = "Green",
                Click = "this.button1_OnClick",
            },
        },
    Components =
        new dynamic[] {
            new { _type = "Wisej.Web.ToolTip",
                  Name = "toolTip1" },
        },

};

As you can see in the simple model above, the model is always the same. The representation can be JSON (could be XML or yaml or anything else) or directly a .NET object. These are the most important features to notice:

• Lower case field names. The ViewBuilder recognizes lowercase names and resolves them to the correct property. It allows JSON models to follow the JavaScript camel casing convention.

• Events are treated like properties. Assigning an handler is the same as calling += or AttachHandler.

• Extension properties, like the ToolTip extender", are addressed using the name of the extender component: i.e. "toolTip1.ToolTip". (Note that you don't need to use the ToolTip extender for tooltips, all Wisej.NET controls have the ToolTipText property.)

• When declaring a model property, extender properties use the underscore instead of the dot to address the component.

Model

The object model is simply the same model as the target component, with just one system property: _type. Use "_type" to define the class of the component to create. It can be a fully qualified type name or a simple name. If it's a single string, Wisej.NET will search in the Wisej.Web. namespace first.

Collections are assigned as arrays. The ViewBuilder detects what kind of collection is expected on the target and either assigns an array or calls the collection's AddRange method.

Use the components collection at the root level of the top-level container to add Wisej.NET components and extenders: Animation, ToolTip, ErrorProvider, etc.

The ViewBuilder can also resolve references to other components in the same container by name. If you set a property that expects another component, for example, ContextMenu, or DropDownControl, you can use the name of the component or control in any location of the model.

{
    "contextMenu": "contextMenu1"
}

The ViewBuilder will search for the component or control name at all levels and assign the reference to the property.

Extender Properties

For example, when you drop a control in a TableLayoutPanel, you will notice that the control has "gained" new properties at design time: Column, Row, RowSpan, ColumnSpan, and others.

The ViewBuilder model fully supports both, extender properties defined by another component and extender properties directly on the container.

{
    "_type": "TableLayoutPanel",
    "controls": [{
        "_type": "Button",
        "name": "button1",
        "text": "Click Me!",
        "columSpan": 2,
        "columm": 0,
        "row": 1,
        "animation1.name": "slideLeftIn",
        "animation1.event": "appear",
    }],
    "components": [{
        "_type": "Animation:,
        "name": "animation1"
    }]
}

In the JSON sample above you can see that button1 sets properties it doesn't have: columnSpan, column and row. These properties are extender properties provided by its TableLayoutContainer.

It also sets two more properties it doesn't have: animation1.name and animation1.event. These properties are provided by the animation1 component declared in the components collection.

Data Binding

Data binding is also fully supported. We used a syntax similar to WPF or MAUI. Any property in the model can be assigned a string that starts with "{Binding" to become a data-bound property.

The complete syntax is:

"{Binding Name, Source=Source, Format=Format, OnParse=OnParseHandler, OnFormat=OnFormatHandler, SourceUpdateMode=SourceUpdateMode, ControlUpdateMode=ControlUpdateMode}"

Everything is optional except Name.

Event Handlers

Attach handlers to any event by name. You can refer to static methods using their name or fully qualified type name, or you can attach to local methods simply by name or using this or Me.

You may also create your own, and attach to JavaScript handlers or compile the code on the fly!

{
    "_type": "Button",
    "click": "AlertBox.Show($\"{sender}\")"
}

Custom Resolution

The ViewBuilder class exposes two assignable methods: ResolveReference and ResolveEventHandler:

ResolveReference

It's invoked when the ViewBuiler needs to convert a string name to a reference to a component or a control. If you assign your resolver to this method then it's entirely up to your code to resolve those references.

ViewBuilder.ResolveReference = (container, component, propertyName, name) => {
    return null;
}

ResolveEventHandler

It's invoked when the ViewBuilder needs to convert a string to a MethodInfo reference in order to create a delegate and attach to the event.

If you assign your resolver to this method, then it's entirely up to your code to convert the string to a method. This handler allows you to attach any kind of handler, event one you build on the fly, to any event on any control created by the ViewBuilder.

ViewBuilder.ResolveEventHandler = (container, descriptor, name) => {
    return null;
}

We added a new Validation property extender to provide a modern, centralized, and flexible validation system to Wisej.NET applications.

Once you drop the new Validation component on a container at design time, all the controls are extended with a new property ValidationRules. You can assign multiple validation rules to any control.

There are 7 built-in validation rules:

1. Required: Validates the presence of any value.

2. Email: Validates an email entry.

3. Decimal: Validates a decimal value.

4. Integer: Validates an integer value.

5. Currency: Validates a currency value.

6. Telephone: Validates a phone number using a validation mask.

7. Regex: Validates any value using a custom regular expression.

Each built-in rule has a set of custom properties in addition to the basic properties inherited from the abstract ValidationRule class.

When design mode, you can add and manage the validation rules using Visual Studio's collection editor; it will automatically load the built-in rules and any custom rule you may have added to your solution.

👉 This is more or less what you do now in code when handling the Validating event. With the difference that now you can reuse the same validation rule for multiple controls in an easy way.

Custom Validation Rules

Build your own custom validation rule classes by extending Wisej.Web.ValidationRule. You can add any property and perform any validation procedure required by the application.

Using validation rule classes allows you to implement complex business rules for the validation of user-entered data in a single, reusable, place.

Example of a custom rule to enforce a minimum-age value:

// ValidationRule to enforce a minimum age.
public class AgeValidationRule : ValidationRule
{
    public bool MinimumAgeInYears {
        get;
        set;
    }
    
    public override bool OnValidating(Control control) {
    
        if (DateTime.TryParse(control.Text, out DateTime value)) {
            return value < value.AddYears(-this.MinimumAge);
        }
        
        return false;
    }
}

Error Providers

The Validation extender, and each Validation rule, expose the ErrorProvider property (accepting any implementation of the new IErrorProvider interface), allowing the validation system to display the error message anywhere!

• On the control itself, the default.

We have also added two new interfaces:

• IValidation. All controls Controls that support the InvalidMessage property and fire Validating and Validated now implement this interface. (it's similar to the IReadOnly or ILabel interfaces that normalize common features.)

Custom Error Providers

Now any class can implement the IErrorProvider interface and be connected to either the Validation component or to any (even multiple) ValidationRule implementation.

The Wisej.Web.Label control implements the IErrorProvider interface and it automatically shows or hides itself when an error message is set or cleard.

The code below shows a simple custom IErrorProvider that collects the errors and displays them in a list, all at once, in a MessageBox.

// Custom error provider
public class MyErrorProvider : IErrorProvider
{
    private Dictionary<Control, string> errors = new Dictionary<Control, string>();
    
    public void SetError(Control control, string error) {
        errors[control] = error;
    }
    
    public string GetError(Control control) {
        return errors.TryGet(control, out string message) ? message : null;
    }
    
    public string[] GetErrors() {
        return errors.Select(
            e => $"<li>{((ILabel)e.Key).LabelText}: {e.Value}</li>").ToArray();
    }
}

// In a page.
// errorProvider is assigned to validation.ErrorProvider.

private MyErrorProvider errorProvider = new MyErrorProvider();

private async void button_Click(object sender, EventArgs e)
{
    // ensure all children are validated.
    ValidateChildren();
    
    // display all the errors in a MessageBox.
    var errors = errorProvider.GetErrors();
    if (errors.Length > 0)
        await MessageBox.ShowAsync($"<ul>{String.Join("", errors)}</ul>");
}

Formatting Option

Validation rules are invoked twice, on Validating and on Validated events. A validation rule implementation may alter the text of a control while it's being validated or after it has been successfully validated.

For example, the built-in CurrencyValidationRule exposes a boolean Format property. When set to true, the rule will format the value of the control, if successfully validated, to display the currency symbol and the correct number of decimals.

Validation Extender Events

The Validation extender exposes the same Validating and Validated events that are available to any control. However, for the Validation extender these events are fired for the controls that have been associated to at least one validation rule.

Your handler code attached to the Validation extender will receive the array with all the validation rules associated with the control being validated. This feature allows an application to perform additional custom validation at the Validation extender level, for all the related controls.

Class Libraries

When building class libraries that target .NET 6+, the assemblies that are referenced via NuGet will not be copied to the bin folder unless the following element is added to the library's csproj file:

Dynamic Assemblies

If a project or assembly reference is not used in the main Wisej.NET project, the referenced project's dependencies will not be loaded into the App Domain automatically.

For example:

If you create a custom control library that implements a custom Bubbles notification that gets dynamically injected into the main Wisej.NET project, you will need to call Application.LoadAssembly() on Wisej.Web.Ext.Bubbles to load the custom library's dependency into the Wisej.NET project.

Beginning with Wisej.NET 3, projects will be able to target multiple frameworks.

Conditional Compilation

You use four preprocessor directives to control conditional compilation:

• #if: Opens a conditional compilation, where code is compiled only if the specified symbol is defined.

• #elif: Closes the preceding conditional compilation and opens a new conditional compilation based on if the specified symbol is defined.

• #else: Closes the preceding conditional compilation and opens a new conditional compilation if the previous specified symbol isn't defined.

• #endif: Closes the preceding conditional compilation.

When the C# compiler finds an #if directive, followed eventually by an #endif directive, it compiles the code between the directives only if the specified symbol is defined. Unlike C and C++, you can't assign a numeric value to a symbol. The #if statement in C# is Boolean and only tests whether the symbol has been defined or not. For example:

Partial Classes

Multitargeting will inevitably require the use of conditional compilation and excluding certain source code files from some platforms.

If you combine this technique with partial classes you can build very flexible classes that have code that compiles on different platforms:

Visual Studio will show you which targets apply for each file on a drop down at the top left.

References

Once your main project targets multiple frameworks, all the projects and the libraries it references must also provide their binaries for multiple targets.

This is all done automatically as long as the referenced projects build the binaries using the standard .NET naming convention, and libraries are added using NuGet packages that provide their binaries for multiple targets.

If you use a package only for .NET 6 or only for .NET 4.8 it will still work but you have to exclude the code in the target framework that cannot use the package.

The Visual Studio designer in Wisej.NET 3 has been upgraded to support Visual Studio 2022. Everything else is unchanged, and it requires the .NET Framework 4.8 target to work with Visual Studio.

Toolbox

Wisej.NET 3 components are available in the toolbox under the "Wisej.NET 3" tab name. Since Wisej.NET 2.5 we have stopped installing components in the toolbox and instead rely on the automatic installation of nuget components.

Extensions added to a project using the NuGet Package manager will show up under the "Wisej.NET 3 Extension" tab name.

If the toolbox doesn't show the Wisej.NET tab and tools, make sure that the Automatically Populate Toolbox option is set to true.

Can I use Wisej.NET 2.5 and Wisej.NET 3 simultaneously?

Yes.

Can I still use IIS Express and IIS?

There are two sets of templates available in Wisej.NET 3.

One set of templates uses Wisej.NET 3 with the old template style. This template format allows you to use IIS Express and Local IIS normally.

The templates based on the new SDK-Project format are more complicated.

Running a project in the new SDK Project format that is set to .NET Framework will start with IIS Express. Running a project in this format that targets .NET 6+ will use Kestrel.

How do I upgrade my Wisej.NET 2.5 application to Wisej.NET 3?

Does Wisej.NET 3 use .NET Core 3.0?

No. Wisej.NET 3 was designed for .NET 5+.

Will Wisej.NET 3 support future versions of .NET?

Yes.

How do I deploy my Wisej.NET 3 application?

Can I create a single-target project for .NET 6+?

Yes, but you will lose access to the designer.

All Wisej.NET projects must target .NET Framework v4.8 to use the designer.

Can I test my project with Windows Docker?

Yes but you have to create the docker file. We only provide a basic docker file for Ubuntu.

Can I test my project with Linux Docker?

Yes. We provide a basic docker file for Ubuntu.

Can I build .NET 6+ applications with VB.NET?

Yes, unlike standard ASP.NET Core projects, which have dropped VB.NET, Wisej.NET features VB.NET templates for .NET 6.

A Docker container image is a lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries and settings.

Using Visual Studio Docker Tools, Wisej.NET 3 applications can be packaged and run in these containers.

Project

Installing

When creating a cross-platform Wisej.NET 3 application, Visual Studio will prompt the user to add Docker support to the project.

Running

To run the Wisej.NET application in a Docker container, change the runtime target to Docker.

Dockerfile

Docker can build images automatically by reading the instructions from a Dockerfile. A Dockerfile is a text document that contains all the commands a user could call on the command line to assemble an image. Using docker build users can create an automated build that executes several command-line instructions in succession.

Below is a sample Dockerfile configured to run a Wisej.NET 3 application that targets .NET 5.

The Basics

Change Project Format to SDK

Moving from older versions of Wisej.NET to Wisej.NET 3 requires updating the project to the new SDK Project format.

1. Take note of all embedded resources, references and build customizations within the Project.

2. Unload the Project.

3. Delete the content of the .csproj file.

4. Copy the following text into the .csproj file.

5. Reload the Project

6. Add embedded resources, references, and build customizations back.

Upgrade Resource Files (.resx)

All the localization .resx files need to be upgraded to Wisej.Framework, Version=3.0.0.0. It's a simple task that can be completed using Visual Studio Search & Replace.

Replace "Wisej.Framework, Version=2.0.0.0" with "Wisej.Framework, Version=3.0.0.0".

Add Startup.cs

A Startup.cs file is required for ASP.NET Core projects (Wisej projects targeting .NET Core).

1. Right-Click the Project.

2. Click Add > Class.

3. Set the name to Startup.cs.

4. Click Add.

5. Copy the following content into the Startup.cs file or download the file below.

Add launchSettings.json

Wisej 3 projects targeted for .NET Core require adding a launchSettings.json file to the /Properties directory of the project.

1. Right-Click the project on the \Properties folder.

2. Click Add > New Item > JSON File.

3. Name the file launchSettings.json.

4. Copy the following text into the file.

Project Properties

The new SDK project format has many properties that are not available in the project property panel. You have to get used to editing the .csproj or .vbproj files directly.

Unfortunately, there isn't a comprehensive list anywhere and many properties are not standard and depend on build targets. All you can do is search around...

These are just a few that we have added to our templates:

Implementation Changes

With the release of Wisej.NET 3.0, which is the first version to support both .NET Framework and .NET Core, we have standardized all classes to ensure compatibility across these two environments. This means that any class differences between the two have been reconciled, and unique classes from either environment have been seamlessly integrated.

UITypeEditor

Originally, the class System.Drawing.Design.UITypeEditor was utilized. However, because it does not exist in .NET Core, we have reimplemented it as Wisej.Web.UITypeEditor.

Therefore, attributes that were previously declared as [Editor(typeof(MyEditor), typeof(System.Drawing.Design.UITypeEditor))] must be updated. You can now specify them as [Editor(typeof(MyEditor), typeof(UITypeEditor))] or [Editor(typeof(MyEditor), typeof(Wisej.Web.UITypeEditor))], depending on the namespaces defined in your using directives.

Http* Types

Previously, all Http* types were located in the System.Web namespace. However, in .NET Core, these types differ significantly. To address this, we have reimplemented a unified Http type system under Wisej.Core.Http*. This ensures consistency and compatibility when working across different .NET environments.

When transitioning from System.Web classes, you will likely encounter compilation errors, making it straightforward to identify where these classes are used in your code. Typically, these classes are utilized in the Upload control, within any implementation of the IWisejHandler interface, and in managing cookies collections. Identifying and updating these areas will be essential to ensure compatibility with the new system.

You can find Visual Studio templates for previous versions of Wisej.NET below:

For each of the below downloads, unblock the zip (this is important!) and expand into:

Documents\Visual Studio (2019|2022)\Templates\ProjectTemplates\Visual C#

Documents\Visual Studio (2019|2022)\Templates\ProjectTemplates\Visual Basic

Wisej.NET NavigationBar Template

Wisej.NET v3.0

Visual Studio 2019

Visual Studio 2022

Wisej.NET v2.5

Visual Studio 2019

Visual Studio 2022

Wisej.NET v2.2

Wisej.NET 2.0 includes a number of powerful new features that can enhance developers productivity, simplify deployment, customize browser widgets, implement responsive design, and speed up server communications.

Modernized Designer

The new designer adds custom ruler snap lines that can be user defined and saved with the container.

You can select the glyph color and take screenshots of your screens in design mode.

In addition to the action selector you can now also directly setup anchoring by using the arrow buttons.

Ruler Snap Lines

• You can create an infinite number of vertical or horizontal snap lines for your containers.

• Just click on the appropriate ruler position.

• Snap lines are saved with each container so they are reloaded the next time you design it.

Document Outline

This new button in the designer toolbar gives you a quick overview and access to all objects.

Responsive Properties

ResponsiveProperties and corresponding profiles simplify Responsive Design a lot.

Client Properties, Methods, and Events

Wisej.NET now supports many more client-side properties and methods on all controls. It makes it much easier to customize Wisej.NET widgets from server-side code.

• AutoShowLoader

  Buttons and MenuItems have a new property AutoShowLoader that automatically shows the loader when the widget is clicked - this is a client side event - and removes the loader when the processing on the server is completed.

  It is intended to be used on actions that typically require some time to complete and should give the user immediate feedback, i.e. a login button.

• CssClass

  Sets custom css class names to the widget. You can also manage the css class names using these methods: AddCssClass, HasCssClass, and RemoveCssClass.

• States

  Sets a custom array of states that can be used in a custom theme or theme mixin. You can also manage the list of states using these methods: AddState, HasState, and RemoveState.

• ClientEvents

  Collection of client-side events and JavaScriot event handlers that you can set from the server. You can use the collection directly or use these methods now available to all controls: AddClientEventListener, RemoveClientEventListener, and HasClientEventListener.

• InitScript

  Sets a custom script that Wisej.NET will execute in the context of the widget when it is first created in the browser.

• CssStyle

  Sets a custom css style string that is assigned to the widget.

Brotli Compression

• Wisej.NET already compresses all traffic packages (HTTP and WebSockets) above a certain threshold by default.

• We now switched from GZIP compression to the Brotli compression algorithm.

• Our internal tests showed that the compressed response stream is only half the size now.

Enhanced Load Balancing

A Wisej.NET server instance can now decide when to refuse a new session when it receives the first request from the load balance, allowing it to move on to the next instance seamlessly.

This new feature allows the Wisej.NET instance to accept only a certain number of sessions, or to check the memory usage and refuse a request when the memory reaches a certain threshold, or it can use an application-provided function that can refuse the initial request for any reason.

Enhanced Themes

• Theme Settings
• Stylesheet Rules

New Templates

• Inherited Control
• Custom Loader

  Replaces the initial loader with one of the new spinners or a custom spinners of your choice.

• Brotli

  Adds Brotli compression support to the application.

• Healthcheck

Wisej.NET 2.1 consolidates several new features from 2.0, while adding several new controls (including a powerful new DataRepeater) and reaches a high level of stability.

DataRepeater

Labels

All editors have a new Label property. It adds a responsive, localizable and themeable label next to the editor.

The Label supports 5 positions: top, left, bottom, right and inside (this is the material style that shrinks the label when there is content).

The size of the inner label and the inner editor can be set to proportional, fixed, or auto-sized. All the properties can automatically change according to the device profile (e.g. the label can be on top for mobile devices, and on the left for the desktop). Supports mnemonics focus, colors, and many other features.

TimeUpDown Editor

Shape Control

Use the Shape control to frame content, including images, and to handle the four borders of a plain DIV tag. It lets you rotate the item, display circles, ovals, rectangles, and triangles using a simple data-bindable all-purpose control.

You can place it behind the controls to frame, or use it as a container and place the controls inside.

TabOrderManager

Weak Events

We have changed all the static events exposed by the Application class to weak events. This new approach (also present in the WPF platform) prevents the source of the static event from holding on the instance handler. It will prevent applications from accidentally leaking memory when attaching to static events exposed by Wisej.

Virtual Prefetch

All controls that supports the VirtualScroll mode (TreeView, ComboBox, ListBox, ListView and DataRepeater) now have a new PrefetchItems property allowing the pre-loading of a items outside of the visible area to support smoother scrolling.

Infinite Sessions

This is a new configuration option in Default.json (sessionStorage: "local" | "session", the default is "session"). It allows the Wisej.NET application to select the browser's local storage ("local") to store the session id. When coupled with a longer or unlimited session timeout allows a user to reopen the browser, or the Wisej.NET desktop executable, and find their work exactly where they left it.

Impersonation

This is a new configuration option in Default.json. When set to true, it allows the server application to impersonate the user's Windows credentials on the server (e.g. access the DataBase, the File System, other services, etc.).

Sounds

// System sounds.
Application.Play(MessageBoxIcon.Error);

// Custom sounds.
Application.Play("sounds/invoice-saved.wav");
Application.Play("data:audio/wav;base64,//uQRAAA....");

' System sounds.
Application.Play(MessageBoxIcon.Error)

' Custom sounds.
Application.Play("sounds/invoice-saved.wav")
Application.Play("data:audio/wav;base64,//uQRAAA....")

Writable Themes

This new feature allows your application to modify any Wisej.NET theme at runtime by code. You can create themes on the fly for each specific user, or modify the global theme (shared by all users).

Example: Create a new there only for the current user by cloning the current theme and changing the background color of buttons.

var myTheme = new ClientTheme("MyTheme", Application.Theme);
myTheme.Colors.buttonFace = "red";
Application.Theme = myTheme;

Dim myTheme = New ClientTheme("MyTheme", Application.Theme)
myTheme.Colors.buttonFace = "red"
Application.Theme = myTheme

Example: Modify the current theme. If it is a shared theme (from the /Themes folder), the change will affect all users.

// Notice that when a member name that is also a keyword you can prefix it with @.
Application.Theme.Appearances.button.states.@default.properties.textColor = "red";

// Member names that cannot be used in C# or VB.NET can be addressed using them as strings.
Application.Theme.Appearances["button-info"].states["default"].properties.textColor = "red";

Application.Theme.Appearances.button.states.[default].properties.textColor = "red"
Application.Theme.Appearances("button-info").states("default").properties.textColor = "red"

var myTheme = new ClientTheme("MyTheme", Application.Theme);
myTheme.Colors.buttonFace = "red";

File.WriteAllText(Application.MapPath("Themes\\MyTheme.theme"), myTheme.ToJSON());

Dim myTheme = New ClientTheme("MyTheme", Application.Theme)
myTheme.Colors.buttonFace = "red"

File.WriteAllText(Application.MapPath("Themes\MyTheme.theme"), myTheme.ToJSON())

Edge Designer

Wisej.NET 2.5 can use the latest Edge/Chrome in the designer, introducing the following features:

• Multiple parallel rendering engines

• Use widgets based on the latest ES6 ECMAScript

• Use JavaScript arrow functions

• Accurate SVG positioning

• Faster rendering

• Visual Studio 2022 64bit

Always make sure that you have the latest WebView2 SDK installer from:

Learn more about WebView2 here:

Edge in Theme Builder

Theme Builder now can use the latest Edge/Chrome browser to show the preview controls and to run your applications while working on the theme.

As an added bonus, now you can detach the browser tab and work with your application running on a separate window while working on the theme at the same time!

DataGridView New Features

Summary Rows

This powerful addition allows you to aggregate and style rows using the standard functions or any custom formula you may need in your code. Aggregated rows are added either above the group, below the group, or can become parent rows in a hierarchical structure.

Frozen Rows

Improvements and Bug Fixes

Wisej.NET 2.5 consolidates several enhancements and bug fixes:

• JavaScript Optimization. We have removed all the JavaScript code that could cause the V8 engine to recompile a class improving client side speed.

• CharacterCasing Property. All controls that show a text (i.e. Label, Button, MenuItem, ...) have a new CharacterCasing property allowing an app to change the case if the text without having to alter the code.

• Design Rendering speed. Several improvements and the new parallel renderers improve the designer experience.

• New Bootstrap Theme. We have added a new bootstrap theme and the full bootstrap icon-set in a new Wisej.NET Icon Pack.

NuGet Deployment

This is a major change in the way we deploy Wisej.NET and it prepares for the next major Wisej.NET 3 release with support for dual framework targeting and .NET 6+.

Local NuGet Repo

Wisej.Framework.dll will be installed in a local NuGet repository at %ProgramFiles%/IceTeaGroup/Wisej.NET 2.5/nuget as a NuGet package named "Wisej.NET Local". It will not be copied to $ProgramFiles%/IceTeaGroup/Wisej.NET 2.5/bin anymore.

This change will allow developers to switch to any Wisej.NET version without having to run the installer again, or uninstalling and reinstalling. Simply open the NuGet Package Manager and select either "Wisej.NET Local" or nuget.org and filter for "Wisej-2".

Extensions NuGet Packages

All the extensions will only be available at NuGet.org.

Visual Studio Configuration

In order to use the new <PackageReference> syntax in your .csproj or .vbproj project files, instead of the old Packages.config file, make sure this option in Visual Studio is set to PackageReference:

Components in the Toolbox

Starting with Wisej.NET 2.5 you will not find the Wisej.NET components in the toolbox in Visual Studio like before. We have stopped installing the toolbox and instead rely on NuGet and Visual Studio automatic population of the toolbox.

Make sure that your Visual Studio has the "Automatically Populate Toolbox" feature turned on.

This change eliminates the common problem of the Wisej.NET toolbox disappearing, allows us to add Wisej.NET to multiple version of Visual Studio installed on the same machine, and gives us the flexibility to add and publish extensions more frequently.

Missing Icons in the Toolbox

A downside is that Microsoft still doesn't support toolbox icons for NuGet packages. If you really want to add Wisej.NET Components with their icon to the toolbox, follow these steps:

1. Add a new tab to the toolbox and name it "Wisej" (don't name it Wisej.NET 2.5 or it will be replaced by the NuGet Package).

2. Locate the Wisej.Framework.dll (or extension dll) and simply drag & drop it on the new toolbox tab.

Other Languages

Wisej.NET is not limited to C# or VB.NET! We have tested it with other .NET languages and made sure it works also with COBOL, x# (CLIPPER, dBase, Vulcan.NET) and F#.

COBOL

MicroFocus VisualCOBOL, NetCOBOL, Raincode COBOL can build single-page web apps with Wisej!

X# (Clipper, dBase, FoxPro)

CLIPPER, dBase, Vulcan.NET, XSharp can build single-page web apps with Wisej!

After launching Visual Studio, click Create a new Project, select your language (either Visual Basic or C#), then select Wisej, and you will see the list of Wisej.NET templates.

After you pick a project type, Visual Studio will create a new solution with the project template you have selected and will start up by showing our welcome page.

And that's pretty much it. Now you can compile the project and open Page1 in the designer.

Pick whatever control you need from the toolbox and you have a web application!

Project Types

Web Desktop Application

Creates a project containing a custom desktop container. Looks like your Windows desktop. You can add items to the taskbar, show floating windows, change the position of the taskbar, etc.

You are basically building a desktop environment in the browser.

Web User Control

Creates a library project with a custom Wisej.NET control that can be used in other projects.

Web Application

Creates a web application with a floating window shown in the browser. It's up to you to build a navigation system to manage your application's forms in the browser.

Web Page Application

Creates a web application with a main page where you can drop any control. The page fills the browser. You can navigate from page to page simply by creating more pages and calling their Show() method.

PWA Web Application

Creates a web application with a main page (similar to the Web Page Application). However, it adds the necessary JavaScript and manifest files to make the browser recognize the application as a PWA app.

The app can be installed on the client, and you can control some basic colors and icons in the manifest. Additionally, Wisej.NET creates the client-side web worker that caches locally all the Wisej.NET JavaScript files allowing the app to launch faster.

Wisej.NET applications are standard Web Projects in Visual Studio. All standard Web.config settings remain valid.

In addition to Web.config, Wisej.NET applications use individual JSON configuration files. A single project can define multiple Wisej.NET applications with one configuration file for each.

Web.config

• Wisej.LicenseKey

  The server license key required to activate the server. Located under appSettings.

• Wisej.DefaultTheme

  The default theme name (without extension: e.g. Blue-1) used by the Wisej.NET Designer and all project applications. Each application can override this in its JSON configuration file. Located under appSettings.

• <compilation debug="true" targetFramework="4.8">

  Wisej.NET reads the "debug" value to determine javascript library minification. When debug is false, Wisej.NET automatically bundles and minifies all required javascript libraries, including core libraries, extension libraries, and custom application libraries.

Wisej.NET requires the module and handler settings in Web.config. We recommend increasing allowed content size to maximum:

All default Wisej.NET settings are predefined in the Web.config file added by Wisej.NET project templates.

Default.json

Each Wisej.NET application defines its configuration using JSON format. The default application uses Default.json.

Configuration settings explained:

• startup

  Full name of the startup static method. Example: "MyApp.Program.Main, MyApp". Wisej.NET calls this when creating a new session. Define either a simple method without arguments or one with a single NameValueCollection argument to receive URL arguments. Optional - you can use mainWindow instead. If defined, you must create a component to show the user in the Main method: a main page, desktop, or window.

• mainWindow

  Full name of a view (Page or Form) created at startup. Example: "MyApp.MainView, MyApp". Wisej.NET automatically loads, creates, and shows the window class - either a Wisej.Web.Form or Wisej.Web.Page.

  If both startup and mainWindow are specified, Wisej.NET creates the main window and calls the startup method.

• theme

  Theme name to load at startup (without extension). Optional - overrides the Web.config theme setting at runtime.

• url

  The application's page URL. Optional - if omitted, users must type the page URL (e.g., http://server.com/admin.html), unless using Default.html with defaultDocument in Web.config.

  When specified, users can type the application name without extension (e.g., http://server.com/admin).

• allowedRoutes

  Defines URL routes separated by semicolons. Example: "api;admin;query/users".

  When specified, the application processes the main URL and child paths starting with specified routes. URL changes trigger the Application.ApplicationRefresh event. Check current URL using Application.Url.

• debug

  Enables logging to client browser console. Default: false. When enabled, Wisej.NET logs events in the browser's console.

• culture

  Application's default culture. Default: "auto" (detects browser culture).
• rightToLeft
• sessionTimeout

  Session timeout in seconds. Default: 120. Minimum: 60.

  Time without user activity before firing Application.SessionTimeout. If unhandled, shows built-in timeout countdown window.

  Note: Session expiration occurs either when the timeout window completes or after twice the sessionTimeout value (minimum 60 seconds).

  Handle Application.SessionTimeout with e.Handled = true to prevent expiration. Use Application.Exit() to terminate manually.

• sessionStorage

  Session ID storage location: "local" (localStorage) or "session" (sessionStorage). Default: "session".

  • "session": Clears when browser closes, abandoning user session

  • "local": Persists in browser storage, attempts session restoration on browser reopen

• responseTimeout

  Wisej.NET ajax request timeout in seconds. Default: 300. Minimum: 300.

  Increase for applications with long-running task responses to prevent timeouts.

• pollingInterval

  Automatic polling interval in milliseconds. Default: 0 (disabled). Minimum: 1000.

  Ignored with WebSocket connections. Use Application.StartPolling and Application.EndPolling for manual polling control.

• autoReload

  Automatically reloads application on session expiration or Application.Exit(). Default: false.

• secure

  Forces SSL usage. Default: false. Changes HTTP to HTTPS and WebSocket to WSS protocol.

• impersonate

  Enables automatic user identity impersonation at request start. Default: false.

  Use with <authentication mode="Windows"> for user credential resource access.

• showLoader

  Controls Wisej.NET ajax loader display. Default: true. When false, shows HTML content during library loading.

• loaderTimeout

  Ajax loader appearance delay in milliseconds. Default: 5000. Set 0 to disable.

• notAvailableUrl

  URL for page shown when server cannot create new session. Default: "resource.wx/NotAvailable.html,Wisej.Core".

  Wisej.NET checks maxSessions value and license concurrent user limits.

• notSupportedUrl

  URL for page shown when browser is unsupported. Default: "resource.wx/NotSupported.html,Wisej.Core".

  Wisej.NET verifies XMLHttpRequest support and custom checks via browserCheck.

• browserCheck

  Custom javascript expression returning true for supported browsers. Example:

• enableWebSocket

  Enables WebSocket connections when supported. Default: true.

• webSocketCompressionThreshold Since 3.5.5

  Response size (bytes) triggering server-side compression. Default: 2048. Use -1 to disable, 0 to always compress.

• maxSessions

  Maximum concurrent active sessions before redirecting to notAvailableUrl. Default: -1 (unlimited).

• maxModalStack

  Maximum nested modal states (dialogs/message boxes). Default: 10.

• validateClient

  Enables client request validation using browser's unique client ID. Default: true. Helps prevent session hijacking.

• validateResources Since 3.5.5

  Validates image, download, and resource requests. Default: false. Blocks non-browser requests.

• dropDuplicateClicks

  Drops "execute" client events during pending requests. Default: false. Prevents multiple executions from rapid clicking while maintaining other pointer events.

• disableClientObjectModel
• enablePWA

  Includes built-in worker process javascript in initial loader. Default: false. Preloads/caches Wisej.NET core scripts and \Offline folder files.

  Use PWA Application template with manifest.json or add it to enable PWA support.

• offlineUrl

  Navigation URL on connection failure. Default: "". Set to "Offline/Default.html" with enablePWA for cached offline pages.
• threadPool

  Configures thread pool without machine.config changes. Format: {minWorkerThreads, minCompletionPortThreads, maxWorkerThreads, maxCompletionPortThreads}. Uses system defaults for omitted values.

• embeddedResourcesCacheControl Since 2.5.23

  Cache-Control for embedded resources. Default: "browser" (1-month browser cache). Options:
• options
• settings

  Custom application settings map. Example: {jquery: "http://cdn...", rootPath: "c:\users..."}. Access via Application.Configuration.Settings.

[Application Name].json

Additional Wisej.NET applications use their own configuration files named [ApplicationName].json, using the same settings described above.

Missing Templates

In case Visual Studio decides not to show the new templates try this:

For Visual Studio 2017 and 2019, open the VS command line and run:

For Visual Studio 2022, open the VS command line and run:

Wisej.NET 2.5 and earlier:

• Documents\Visual Studio (2019|2022)\Templates\ProjectTemplates\Visual C#

• Documents\Visual Studio (2019|2022)\Templates\ProjectTemplates\Visual Basic

Wisej.NET 3.0 and above:

Starting with Wisej.NET 3.0, we took the approach of distributing the Designer and the templates in a Visual Studio Extension installer (.vsix).

The path to the templates can vary from one machine to another:

%LOCALAPPDATA%\Microsoft\VisualStudio\17.0_{id}\Extensions\{extension_id}

As an example, it can be something like this:

%LOCALAPPDATA%\Microsoft\VisualStudio\17.0_315d49d1\Extensions\x2rkvlci.xbt

Wisej.NET 4.0

With Wisej.NET 4, developers have access to two distinct designers: one for the .NET Framework (net48) and another for .NET Core (.NET 8.0-windows and later versions).

The designer for the .NET Framework is included in the VSIX installer, which also provides various templates and other Visual Studio add-ons. In contrast, the designer for .NET Core is distributed and updated through the NuGet package that includes Wisej.NET itself.

Download Templates

We also provide the templates to download as another option:

Clear Templates Cache

Designer Error

Occasionally you may start getting designer errors when opening a container in design mode. The most common error is "Unable to cast type..." It's a well-known issue related to Visual Studio having to load a shadow copy of the assemblies used at design time.

Since assemblies cannot be unloaded in .NET Framework, Visual Studio loads shadow copies of the assemblies loaded by the designer. Sometimes it ends up loading the same assembly multiple times, leading to the "Unable to cast" error because the same type is loaded more than once.

Clean and Rebuild

Usually, it's enough to:

1. Close all designer tabs

2. Close all Visual Studio instances

3. Delete /bin, /obj, /.vs

4. Open Visual Studio and reload the solution

5. Recompile

Clear Designer Assembly Cache

Visual Studio makes shadow copies of the assemblies loaded by the designer here:

%LOCALAPPDATA%\Microsoft\VisualStudio{version}\Designer\ShadowCache

Each installation of Visual Studio has a different unique ID. Visual Studio 2019 versions start with "16.0" and Visual Studio 2022 versions start with "17.0".

Wisej.NET applications are standard web applications that work seamlessly with load balancers.

However, Wisej.NET goes a step further and gives you additional features to manage the load across several servers. You can configure each server running a Wisej.NET application to accept a a maximum number of sessions, or to be available for the load balancer only if the CPU load is below a certain percentage and/or the memory usage is below a certain level.

Prepare your Wisej.NET App

Preparing Wisej.NET apps for load balancing mainly involves configuring healthcheck parameters. These determine when a server instance should return an error code signaling the load balancer to route requests elsewhere.

To configure healthcheck:

1. Use Add New Item and select Healthcheck from templates, or

2. Copy the configuration settings below, or

Place the file in your application's root folder and set "Copy to Output Directory" to "Copy if newer". The file must be in the /bin directory to be recognized.

Configuration

Wisej.NET requires client requests to route consistently to the same server instance. Configure your load balancer to use either:

• Sticky Sessions

• Other routing that ensures user-server instance consistency

Session

Wisej.NET requires load balancer session affinity: each user/session must route to the same server. This typically uses:

• Sticky session cookies

• Client IP hash

• Other consistent routing methods

Healthcheck

Load balancers periodically verify server instance availability using a "healthcheck" URL. Options:

• Custom HTML/ASPX page

• healthcheck.wx to verify Wisej.NET routing component status

HealthCheck.json

Wisej.NET applications automatically respond to initial Default.html (or subapplication URL) requests by either returning the page or returning "503 Service Unavailable" (configurable in HealthCheck.json).

The following properties in HealthCheck.json control server availability. Wisej.NET uses all configured properties in this order:

maxSessions

Maximum live sessions a Wisej.NET server can accept before refusing more. Returns "503 Service Unavailable" (or HTML page from Default.json) to new users instead of risking server overload.

Set to 0 to disable this check.

maxMemory

Maximum memory percentage before returning "503 Service Unavailable". Example: Value 70 means the server returns 503 when memory usage is 70% or higher during main page request.

Set to 0 to disable this check.

maxCPU

Maximum CPU load percentage before returning "503 Service Unavailable". Example: Value 100 means the server returns 503 when CPU usage is 100% during main page request.

Set to 0 to disable this check.

returnCode

503: The server is currently unable to handle the request due to temporary overloading or maintenance. This condition should be temporary. If known, the delay length MAY be indicated in a Retry-After header. Without Retry-After, the client SHOULD handle the response as a 500 response.

retryAfter

Minutes value for the Retry-After header sent with "503 Service Unavailable" response.

Note: Most load balancers currently ignore this header.

HealthCheck.IsServerAvailable

You can install a custom static method called by the healthcheck handler. Return true if the server should be available to the load balancer, false to return 503 (unavailable).

The IsServerAvailable method can check any values to determine server availability:

Wisej.NET applications typically have a single application in the broad sense. For clarity:

• "Sub-application" refers to an application in the strict sense

• Each Wisej.NET project requires at least one default sub-application

Startup Files

A new Wisej.NET project creates three startup files:

• Default.html

• Default.json

• Program.cs

Default.html maintains ASP.NET convention for startup pages.

Program.cs contains the static (Shared in VB) Main method.

The .html and .json filenames should match for simplicity but this isn't required.

Sub-Applications

Creating

Create sub-applications in the project's root or any project folder:

1. Right-click project/folder → Add → New Item

2. Select Wisej on left side

3. Click Application in list

4. Set application Name

5. Click Add