Installation

To install Wisej.NET 4, you will need two files: the "Wisej.NET-4-VS2022.vsix" extension and the "Wisej-4.4.0.0-beta.#.nupkg" package. The most current "Wisej.NET-4-VS2022.vsix" can be downloaded from the link provided below.

Meanwhile, the latest beta versions of the Wisej-4 package, and all the Wisej-4 extensions, will be accessible on NuGet.

Be sure to obtain both files for a successful setup and to enjoy the full feature set offered by Wisej.NET 4, incorporating advancements like managed System.Drawing, the .NET Core out-of-process designer, and the new fluent markup extensions.

Known Issues

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.

• DataGridViewColumnCollection

• TreeNodeCollection

ImageSource Editor

The ImageSourceEditor is presently unable to load icons from icon packs. However, this functionality will be completed and available before the official release.

DataGridViewCellStyle Editor

The cell style editor is functional but incomplete. It does not provide a preview of the style changes being made. Additionally, any modifications are applied directly to the DataGridViewCellStyle instance. Consequently, if you press the Cancel button, the edits will still be committed.

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.

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

The documentation is organized in multiple cross-linked books. This one is the most extensive, being about the concepts and features for each one of the many available controls.

There is also a full API book, and a book for the extension, integration, deployment, and more.

The first thing to do, now that you have installed Wisej.NET, is to launch Visual Studio and create a new project. Or, launch Visual Studio and open one of our many examples.

Sometimes Visual Studio decides not to show the new project templates. If that happens, please follow the instructions in the missing templates section.

The first time you open the designer, you will get the license activation dialog. Enter your developer (or trial) license and everything should work.

Visual Studio Requirements

The Wisej.NET library can be used with any version of Visual Studio or Visual Studio Code. However, the designer plug in is supported on Visual Studio 2019 and 2022 (Community, Professional, or Enterprise) on Windows.

Make sure that you have installed these 2 workloads:

• ASP.NET and web development

• .NET desktop development (needed for the designer)

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.

For instructions on how to download the Wisej.NET 4.0 Beta packages, please refer to the Public Beta section.

.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

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:

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:

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.

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:

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:

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.

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

// 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

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.AllowHtml = true;
this.label1.Text = Markdown.ToHtml("**Bold**");

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.

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.

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.

Once you add validation rules to a control, the Validation component will automatically attach to the control's Validating and Validated events and invoke the rules in sequence. When a rule fails to validate, it will set the InvalidMessage property of the control being validated, and set the e.Cancel property of the event to true.

👉 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

Validation messages are typically displayed in an error tooltip by setting the InvalidMessage property of an editor control. A second way to show validation errors, is to use the ErrorProvider extender. However, an application would have to explicitly set the error message in code when processing the Validating event.

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.

• Using the ErrorProvider extender.

• On any custom implementation of the new IErrorProvider interface: i.e, a MessageBox, a slide-in Panel, any logger, etc.

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

• IErrorProvider. Exposes the same two public methods implemented by the existing ErrorProvider component. Allows an application to have full control of where an how to show error information related to data field validation. The Label control now implements IErrorProvider.

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.

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.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 latest Wisej.NET 3.5 is available on NuGet.

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 3.5 is now able to run on iOS, Android, and MacOS devices using the EmbedIO server in a new Wisej.NET Hybrid shell build using MAUI's native integrations.

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

• ListViewItem gained the new Visible property. It allows the application to hide items without having to remove and add them back to the Items collection.

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

• The Validation extender now supports the IDataErrorInfo interface and data binding. We also added the Enabled property to the base ValidationRule class to allow the code to disable a specific validation rule without removing it from the Validation extender.

• DataGridView exposes the CreateSummaryRow, CreateDataBoundColumn, and CreateDataGridViewColumnFromType methods as public virtual to allow an application to customize the grid's inner behavior and fully control the automatica creation of rows and columns.

• The ErrorProvider extender allows a derived class to override its methods and fires the new ErrorChanged event to allow an application to customize error message and icons in a single location.

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

// Previous syntax.
var button1 = new Button
{
    Text = "Click Me",
    Size = new Size(100, 24),
    Location = new Point(10, 10)
});
button1.Click += (s, e) => { AlertBox.Show("Clicked!"); };
this.Controls.Add(button1);

// New syntax.
this.Controls.Add(
    new Button(
        "Click Me",
        new Point(10, 10),
        new Size(100, 24),
        (s, e) => { AlertBox.Show("Clicked!"); })
);

Common Method Chaining

All basic methods in Control now return this to allow code to chain calls:

this.textBox1.Show().CenterToParent().BringToFront();

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.

See documentation: https://docs.wisej.com/extensions/extensions/signature

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

The new Dynamsoft Barcode & Scanning premium extension gives developers an enterprise-ready option for barcode scanning and text (OCR) scanning on the web.

Developers are required to purchase the following licenses from Dynamsoft:

• Dynamsoft Barcode Reader – JavaScript Web SDK

• Dynamsoft Document Normalizer – JavaScript Web SDK

Mobiscroll Premium Extension

The new Mobiscroll premium extension gives developers a suite of mobile-friendly controls and components to use in Wisej.NET applications.

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

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.

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.

• All non-numeric values are in strings. Including Point, Size, Color, Font, etc. The ViewBuilder uses the property's TypeConverter to parse the string.

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

Wisej.NET supports the IExtenderProperty system at design time. Now it supports it also in this new ViewBuilder model. There are usually two kinds of extenders: a component and a container.

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.

If the Source is not specified, the current container (this or Me) is assumed to be the source. When the Source is specified, it's also relative to this or Me, unless it's a reference to a component, a BindingSource, for example.

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.

Event handlers are resolved through the ViewBuilder.ResolveEventHandler function , which is overridable. The default resolver looks up the method and returns its MethodInfo object.

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

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

Your ResolveEventHandler implementation (see Custom Resolution) receives the string assigned t the "click" event and it's up to you to return the MethodInfo to attach to the event.

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;
}

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:

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.

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.

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.

Missing Templates

1. Verify the templates are located in

   • My Documents\Visual Studio 2022\Templates\Project Templates\Visual C#

   • My Documents\Visual Studio 2022\Templates\Project Templates\Visual Basic

2. Close all instances of Visual Studio.

3. Run devenv /updateconfiguration as Administrator in the Developer Command Prompt.

4. Reopen Visual Studio.

Docker

Your Docker server host is configured for 'Linux', however your project targets 'Windows'...

Ensure that you are targeting the correct framework. This error will occur when net48 is the first-listed framework in TargetFrameworks. Temporarily switch net48 with your Docker runtime target (net5 / net6).

There were build errors. Would you like to continue and run the latest successful build?

Ensure that you are targeting the correct framework. This error will occur when an incorrect framework is loaded into the Docker container. Temporarily switch the first-listed TargetFramework with your Docker runtime target (net5 / net6).

Designer Errors

Missing Designer

Occasionally when creating a new Wisej.NET 3 project using .NET48 and .NET6+ the designer will not be visible upon project creation. Rebuild the project and then restart Visual Studio.

Designer Error

The most common designer error is "Unable to cast object of type ‘Wisej.Web.Page’ to type ‘Wisej.Core.IWisejControl’ (or another base type).

This issue occurs when trying to loading multiple versions of Wisej.NET into one Visual Studio instance. Visual Studio loads the Wisej.NET designer assembly for the first page that is shown in the designer. If you open a page from a different project using a different version of Wisej, you will get this error.

Simply restart Visual Studio and re-open the new page.

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.

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.

Existing Wisej.NET 2 applications should be able to run on Wisej.NET 3 mostly unchanged. Hopefully, all you need to update is the Visual Studio project format to the new "Sdk" project format.

The designer in Visual Studio is not available for the .NET Core targets and relies on the dual target approach, with the added benefit that Wisej.NET applications can be deployed on .NET Framework 4.8 on Windows and .NET Core on Windows, Linux and MacOS.

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.

Multitargeting will inevitably require the use of conditional compilation and excluding certain source code files from some platforms. In our sources we use conditional properties and partial classes to neatly separate code keeping the same class structure.

.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

All the Application.Download, and Application.DownloadAndOpen methods have a new optional argument: a callback function, invoked when the file has been downloaded by the client.

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

Wisej.NET supports all sorts of very powerful layouts (impossible to achieve with any other web platform). However, all the layouts are implemented in layout engines and are "permanent": you have to set layout properties for the children and the container manages the layout using the specific layout engine.

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.

Calling LayoutChildren without the controls collection and without the viewArea argument, arranges all the direct children using the control's DisplayRectangle as the bounding area.

Otherwise you can specify only a subset of the child controls and define a view area to limit the layout space. You can also try this new automatic layout functionality at design time using the new AutoLayout Panel.

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

We have introduced a new experimental feature to extend the current data binding model to make it compatible with MAUI's Commanding approach. In our implementation, commands work seamlessly with the existing data binding and have access to the full context of the command source. In MAUI the command's code is limited to a single parameter.

In this first implementation, Button and SplitButton have a new Command property and CommandChanged event. The Command property can be data-bound to ICommand properties of the data source.

When ICommand.CanExecute returns false, the command source button automatically disables itself. Clicking the button invokes the method attached to the command.

Use the new Command class or Command<T> class to wrap the implementation of a command and to cast the data item coming from the data source.

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:

• ILabel. Implemented by all controls that have the Label property.

• IImage. Implemented by all controls that have the various Image (ImageIndex, ImageKey, ImageSource) properties.

• IReadOnly. Implemented by all controls that have the ReadOnly property.

• IModified. Implemented by all controls that have the Modified property.

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.

The Application class now is an IServiceProvider and has two new methods to manage services: AddService and GetService with several overloads.

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

Our DataGridView control can handle an unlimited number of rows thanks to its built-in virtual scrolling and page caching on the client side. As the user scrolls the rows, the control manages a client-side cache of pages or rows and requests from the server only the pages that are needed to render the current view.

You can control the size of the client-side cache using the BlockSize and MaxCachedBlocks properties. When the DataGridView is in VirtualMode, it doesn't hold any data and can manage any number of rows with minimal memory usage. Your code provides the data as needed handling the CellValueNeeded and CellValuePushed events.

However, the VirtualMode events are fired every single time the application code uses a cell in the grid (in VirtualMode the grid doesn't hold any data). Usually, implementations of a virtual DataGridView must implement some kind of cache management on the server.

The new DataRead event makes this task a lot easier. It is fired when the client requests a page allowing an application to build and manage a small server-side cache in sync with the client scrolling, resulting in a much simpler usage of the VirtualMode events.

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

This property has been available as an experimental feature for a while and it's now a supported property. It takes an HTML string and it displays filling the entire grid space when there grid contains no rows.

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.

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

Wisej.NET is now easier to use than ever before. It is available as a VSIX installer through the Visual Studio Marketplace or via the Visual Studio Extension Manager. Without using the GAC, the new VSIX installer automatically registers Application Templates and the Wisej.NET designer.

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

Previously, the data binding system in Wisej.NET only supported the BindingList<> class for advanced data binding. However, MAUI and WPF support the simpler ObservableCollection<> type for their data binding.

Now Wisej.NET seamlessly supports both. Support for the INotifyPropertyChanged is identical in all data binding implementations.

Together with the Commanding support introduced as an experimental feature in 3.0, it now supports most 3-letter or 4-letter binding models.

Commanding

The Commanding implementation introduced with 3.0 is now fully supported.

Dependency Injection

Services and Dependency Injection are now first-class citizens in Wisej.NET 3.1.

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.

We have moved the Tour Panel Extension's Templates to the Marketplace and added new Navigation App Templates similar to the Blazor startup templates.

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

We have selected new automation tools as we built our new automated test suite, which we’ve decided to share using TestProject.io, an end-to-end automation solution for Web and Mobile apps with all the latest browser drivers.

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

The extension enables developers to add external and platform-specific authenticators into Wisej.NET applications. You can read more about the new extension in our blog post here.

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.

Application.OpenWindow() opens the url in a new popup window. If you specify the onclose callback method, it is invoked when the user closes the popup window.

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.

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.

Upgrading from Wisej.NET 1.X to recent Wisej.NET versions is extremely easy. All you need to do is replace the references and make sure some "using" statements referring to design-time features are updated.

Upgrade Checklist

• Set target .NET Framework to 4.8

• Replace project references to Wisej.Web.dll and Wisej.Core.dll with a NuGet Package reference

• Replace .resx namespaces to Wisej.Web. and Wisej.Core. with Wisej.Framework. You can do that by doing a mass replacement. From Visual Studio, go to Edit > Find and Replace > Replace in Files or simply use the Ctrl+Shift+H Hotkey.\

• Change using Wisej.Core.Design to using Wisej.Design using the same process as the previous step, although this time change the File type from RESX files to CS files.

• Change calls from ApplicationBase. to Application, again following the same process as the previous step.

• Modify Web.config and replace "Wisej.Core" with "Wisej.Framework"

<?xml version="1.0" encoding="utf-8"?>
<!--
  For more information on how to configure your ASP.NET application, please visit
  http://go.microsoft.com/fwlink/?LinkId=169433
  -->
<configuration>
  <appSettings>
    <add key="Wisej.LicenseKey" value="" />
    <add key="Wisej.DefaultTheme" value="Bootstrap-4" />
  </appSettings>
  <system.web>
    <compilation debug="true" />
    <httpRuntime targetFramework="4.8" maxRequestLength="1048576" />
    <httpModules>
      <add name="Wisej" type="Wisej.Core.HttpModule, Wisej.Framework" />
    </httpModules>
  </system.web>
  <system.webServer>
    <validation validateIntegratedModeConfiguration="false" />
    <handlers>
      <add name="json" verb="*" path="*.json" type="System.Web.HttpForbiddenHandler" />
      <add name="wisej" verb="*" path="*.wx" type="Wisej.Core.HttpHandler, Wisej.Framework" />
    </handlers>
    <security>
      <requestFiltering>
        <requestLimits maxAllowedContentLength="1073741824" />
      </requestFiltering>
    </security>
    <defaultDocument enabled="true">
      <files>
        <add value="Default.html" />
      </files>
    </defaultDocument>
  </system.webServer>
  <!--
	Uncomment the trace listener below to enable logging to a log file.
	-->
  <!--
	<system.diagnostics>
		<trace autoflush="true" indentsize="4">
		  <listeners>
			<remove name="Default" />
			<add name="Default" type="System.Diagnostics.TextWriterTraceListener" initializeData="Trace.log" />
		  </listeners>
		</trace>
	</system.diagnostics>
	-->
</configuration>
<!--ProjectGuid: f56c9a70-bc66-49ef-957b-6de7ca9980d5-->

New SDK Format

Wisej.NET 3.0 introduced the ability to target .NET 6, with this change came the need to introduce the new SDK Project Format.

If you're aiming to migrate to .NET 6 or newer, click here for more info.

Designer and Templates

Starting with Wisej.NET 3.0, we're now shipping the Designer and Templates as VSIX installers. This gives you the ability to manage updates directly from Visual Studio's Extension Manager.

For Wisej.NET 2.X , you can install the designer as its own NuGet Package.

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

The new DataRepeater container is a sort of a custom data grid. Instead of rows it repeats a template panel containing child controls in any layout. Child controls are automatically data-bound to the current record.

The infrastructure is virtual, which means that the DataRepeater only creates the visible panels and updates the controls as the user scrolls them into view, allowing the management of an unlimited numbers of records.

It can scroll its items vertically or horizontally, supports touch scrolling, can hide the scrollbar, and it can adapt to the user's device layout. You can use the DataRepeater to build data-bound lists of any kind for mobile or desktop devices.

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

This is a new simple time editor, based on the UpDownBase class.

This is a new editor similar to the existing DomainUpDown and NumericUpDown. Handles a TimeSpan value in different localized formats. Supports minimum and maximum values, it’s bindable, nullable, and supports the quick increase of the time part under the cursor using the arrow keys.

Shape Control

It is an all-purpose shape control that can represent simple shapes with different styles.

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

This new extender component (drop it on a design surface to use it) adds a new property TabOrder to all containers. If your page or form contains other containers (i.e. Panel, GroupBox) each one can manage the tab order of its children independently.

Supports 3 options: Default, AcrossFirst and DownFirst. Once set, the TabIndex of all the children is set automatically, and it’s updated automatically when adding or removing children.

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

We have added a simple new feature to play system and custom 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"

You may also save the newly created theme to /Themes to make it available to all users through Application.LoadTheme(name).

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())

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.

Read more: ResponsiveProperties

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.

Read more: about Brotli.

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.

See Load Balancing for more information.

Enhanced Themes

• Theme Settings

  Themes now can contain system and value settings. See Theme Settings.

• Stylesheet Rules

  Theme designers now can embed custom css rules directly in theme. This new feature allows for fine tuning a theme and for greater design flexibility. See Theme Stylesheet.

New Templates

• Inherited Control

  Adds a custom control based on any visual Wisej.NET class. Use it to create you extended controls without having to use the UserControl container.

• 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

  Enables enhanced load balancing support in your application. See Load Balancing.

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!

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

Example with name "Admin" creates:

• Admin.html

• Admin.json

• Admin.cs

The Admin.cs file mirrors Program.cs:

Running

Wisej.NET sub-applications start with the .json file, not the .html file. Even when accessing a URL with .html, Wisej.NET looks for the corresponding .json file (rules explained below).

For the "Admin" example, Admin.json contains:

This file provides two key pieces of information:

• url - Which .html file to display in browser

• startup - Which server-side method to execute

When accessing http://myApp.com/Admin, Wisej.NET:

1. Locates Admin.json

2. Reads the url key and loads Admin.html

3. Invokes the startup method specified in Admin.json

Entry Point

Wisej.NET needs the server-side startup method - in this case [ProjectName].Project.Main in assembly [ProjectName].

To instantiate an AdminPage instead of executing Main, modify Default.json:

Startup Workflow

The Wisej.NET startup process follows these steps:

1. Locate .json file

2. Direct browser to load/display the url HTML file

3. Execute server-side action based on .json file:

   • Run the startup method, or

   • Instantiate the mainWindow view

Rules for Finding the .json File

1. Replace Extension with .json

   • For URLs ending with an extension (e.g., http://myserver.com/Startup.php)

   • Wisej.NET looks for matching .json file (\Startup.json)

   • If .json not found and Wisej.NET loaded, wisej.wx reloads current page

2. Append Default.json to Folder Path

   • For folder URLs:

     • Root folder (http://myserver.com) → \Default.json

     • Folder path (http://myserver.com/Suppliers/) → \Suppliers\Default.json

3. Handle URLs Without Extensions

   • For URLs like http://myserver.com/Customers, Wisej.NET:

     1. Tries \Customers.json

     2. If not found, treats "Customers" as folder and tries \Customers\Default.json

Default Document Configuration

The Web.config file in Wisej.NET project templates includes:

This defaultDocument setting isn't required because:

• Website root URLs are treated as folder paths

• Wisej.NET automatically looks for \Default.json in the project root

• Rule 2 above handles folder path resolution

There are several different licenses:

• Developer

  One developer license is required for each developer using Wisej.NET.

• Server

  One server license is required for each server running Wisej.NET applications.

• Community

  One license is required for each developer or each server using Wisej.NET.

• Trial

  The trial license works for both: developer and server activations.

Developer License

Wisej.NET will ask you to enter the developer (or trial) license key the first time you open a window in the designer.

Enter the Developer License Key or the Trial License Key and click the ACTIVATE button.

Changing a Developer License

If you already have a Trial License and want to register the Developer License, open the Registration form by clicking on the small Wisej.NET icon in the designer's toolbar (all the way to the right) at the bottom. It will reopen the registration window where you can enter the new license.

Server License

The web server must have write permissions to the project directory or to "C:\ProgramData" to be able to properly activate the license and generate the wisej-server.lic file.

Wisej.NET saves a copy of the activated server license into the project's folder and to "C:\ProgramData\IceTeaGroup\Wisej".

License Renewal

You don't need to do anything else. There is no need to re-register or to change the license key in Web.config.

License Troubleshooting

Here are some common issues that users encounter:

Deprecated Wisej.NET Server Community edition

Minimum version for Wisej.NET Server Express edition

Unsure where to view the license(s) that you already have

WrongProductName error message

Make sure that the key you enter into web.config is a server license, not a developer license.

Everything is set up correctly and you are still getting an "Invalid License" error

If you run into this issue, rebuild your project.

PWA Support

A new PWA project template includes a set of professionally-designed offline pages end the required manifest file. The worker process script is embedded in the Wisej.NET loader. Wisej.NET will automatically pre-cache locally all the resources and offline pages. Enable PWA support in Default.json by setting enablePWA: true.

The improved offline detection process automatically switches to the offline pages when it detects a disconnection and restores the application when the connection is restored.

A new event Application.BeforeInstallPrompt allows the application to detect when it can be installed as a PWA, and a new client-side method Wisej.showPWAPrompt() displays the browser's PWA installation prompt. Using the Application.BeforeInstallPrompt event allows the application to display a custom notification to the user (the browser's default PWA notification is just a tiny + symbol in the address bar.)

Additionally, the application can attach a client side event to a button or an icon to show the PWA installation prompt when the user clicks the control.

When the application goes offline, Wisej.NET loads the /Offline/Default.html page. The image below is one of the pages included with the project template. However, you can put an entire JavaScript application inside the /Offline folder. Wisej.NET will pre-cache locally all the files at all level.

Wisej.NET will switch back to the application as soon as it detects that the connection is restored. Unless the session expired, the entire previous state is reloaded and the user is able to keep working from where the disconnection occurred.

iOS and Android Integration

Our integration packages create a hybrid application, where the Wisej.NET web application is able to interact with all native-only features of the mobile device.

The Wisej.NET app can: show native alerts, use the camera, use the microphone, use the GPS, read the magnetometer read the gyroscope, read the accelerometer, play sounds, switch the flashlight, push notifications, read and write NFC chips, authenticate using TouchID or FaceID, create a native Toolbar, create a native TabBar, manage the StatusBar, read all the device information, handle multiple screens, lock the screen orientation, manage the screen brightness, brew coffee, and more…

For example, this is all the code you need to authenticate a user using FaceID in C# or VB.NET from the server side.

A Wisej.NET hybrid application can also push notifications, read any property of the device, store files locally, and manage a native toolbar, a tabbar, the status bar, and all the available sensors through the Device object.

Wisej.NET 2.2 also greatly improves virtual scrolling and touch integration.

DataGridView

There are two important enhancements in the Wisej.Web.DataGridView control:

Virtual Rows

Starting from Wisej.NET 2.2, the DataGridView doesn't create any row when the grid is data-bound or running with VirtualMode set to true. It instead gets the values directly from the data source or the CellValueNeeded event when virtual.

As the code requests rows, the framework converts virtual rows into real rows transparently. However, if the application is changed to use dataGrid.GetValue(col, row ) and dataGrid.SetValue(col, row, value) instead of addressing the cells directly, it will read and save from/to the data source and will not create any row.

Selection Modes

Now the DataGridView supports all the standard selection modes (CellSelect, FullRowSelect, FullColumnSelect, RowHeaderSelect, NoSelection) and adds a new mode: RowColumnHeaderSelect.

You can use the SelectedCells, SelectedRows and SelectedColumns collection to read the selected objects.

Toast Notifications

Unlike the MessageBox and AlertBox, which are static classes, the Toast is a component that you create and can hold on to in your application. You can reuse it and you can update the content while the Toast is visible.

It can be located in any of the 9 standard locations. By default it appears at the TopCenter location. It contains an icon and a text that can display any HTML content (by setting the AllowHtml property to true).

Toasts auto close by default after 5 seconds but they do not auto dispose. To auto dispose a toast instance when it's closed, set the AutoDispose property to true. You can detect when the user clicks on a Toast by handling the Click event, and handle the Close event to run code when the Toast is closed.Populate a ComboBox without keeping the binding link with the data source.

DataRepeater

Now the DataRepeater supports items of variable height (when in vertical mode) and width (when in horizontal mode). It can auto size the child items to fit the content, or you can set the size of each item programmatically.

Additionally, the virtual scrolling, mobile scrolling, and prefetching have been improved considerably. The DataRepeater can now handle unlimited items seamlessly without a glitch.

Data Binding

All controls that support data binding have been improved with two new methods:

• Fill

  Populates the control from a data source object without keeping the control linked to the data source.

• Append

  Appends the data source object to a previously populated control without keeping the control linked to the data source.

These new methods allow a control to retrieve the data from the data source without keeping the bidirectional binding link. All the properties that specify the fields to bind to are still used, making the population of list controls much easier.

Wisej.NET 2.2 also adds full data binding support to the ListView control, including support for the new Fill and Append methods.

The new ListView control supports the following data binding properties:

• DataSource

  Returns or sets the data source for the ListView control.

• DataMember

  Returns or sets the name of the list or table in the data source for which the ListView is displaying data.

• ColumnHeader.DisplayPropertyName

  Returns or sets the property to display in the ListView items.

• ListViewItem.DataBoundItem

  Returns the data-bound object for the ListViewItem.

Integrations

Lazy Loading

The ComboBox and the ListBox control have a new LazyLoading property, similar to the existing TreeNode.LazyLoading.

When LazyLoading is set to true, the list items (or child nodes in a TreeNode) are sent to the client the first time the ComboBox is dropped down, or when the ListBox "appears" on the client browser. It reduces the size of the data sent to the browser when creating a page and speeds up the initial loading of pages and windows.

All Controls

All controls in Wisej.NET 2.2 have some enhancement:

• Control.ToolTipText

  All controls have a new ToolTipText property. It allows an application to set the tooltip text on any control without having to add the Wisej.Web.ToolTip provider.

  However, if the application needs to modify some additional aspects of tooltips, it should still use the Wisej.Web.ToolTip provider which exposes the additional tooltip properties.

• PictureBox.Filter
• TabControl.ScrollStep

  Sets the number of pixels to scroll when the scroll buttons are pressed to bring a tab into view.

• ListBox.IncrementalSelection

  When true (default) the ListBox caches keystrokes for less than a second allowing a user to type and incrementally select the list items, i.e. typing "ab" selects the first item that start with "ab". When false, typing "ab" will select the first item that starts with "b".

• TextBoxBase.SelectOnEnter, ComboBox.SelectOnEnter, DateTimePicker.SelectOnEnter, UpDownBase.SelectOnEnter

  When SelectOnEnter is true, the entire content in the editable area is always selected when the control gains the focus.

• TreeView.RighClickSelection, ListBox.RightClickSelection

  When true, right clicking a TreeNode or a ListBox item (i.e. to show a ContextMenu) will select the item.

• TagTextBox.KeepWatermark

  When true, the TagTextBox keeps showing the Watermark text in the editable portion of the control after the tags.

• DataGridView.SelectionDelay

  When set to a value greater than 0 (the default), the grid waits the specified number of milliseconds before notifying the server that the selected element has been changed using the keyboard.

  This property prevents the server from being flooded with row selection events when a user rapidly navigates and selects different rows using the up/down keys.

• FileDialog.LoadPath, FolderBrowserDialog.LoadPath

  The file and folder dialogs expose a new LoadPath event. It is fired for each file and each folder loaded by the dialogs. An application can handle this event and set the icon to display, the size, and the dates related to the file or folder. The event is cancelable, allowing the handler to set e.Cancel to true to filter out specific files or folders from the list.

• Application.SetSessionTImeout

  Changes the session timeout for the current session only.

Application Events

The Application object exposes two new global events:

• ActiveWindowChanged

  This event is fired when the active floating window changes. Allows an application to react to the change of the active window globally.

• FocusedControlChanged

  This even is fired when the focused control changes, regardless of where it's located. Allows an application to process changes to the currently focused control.

Configuration

There are two new settings that are supported in the Default.json configuration file:

• threadPool
• enablePWA

  Enables PWA support. When set to true, the Wisej.NET bootstrapper will include the built-in service worker. It will preload and cache locally the Wisej.NET libraries and all the assets found in the /Offline directory.

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.