1 of 8

What's new in 3.0

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.

Wisej.NET 3 for .NET Framework 4.8 replaces Wisej.NET 2.5 while Wisej.NET 3 for .NET Core 6 is a new build for ASP.NET Core applications that can run 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 is the Visual Studio to the new "Sdk" project format.

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

The new Sdk project format has many properties that are not available in the project property panel. You'll have to get comfortable editing the .csproj or .vbproj files directly. See for an example if the ones we added to our templates.

Multi Targeting

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

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

.NET 6+ Windows, Linux, MacOS

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

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

Wisej.NET supported the OWIN middleware approach since 1.5, based on Microsoft's Katana.

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

All ASP.NET pages and all ASP.NET controls will NOT work on ASP.NET Core.

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

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

Auto Layout

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

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

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

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

Commanding

This new feature is still experimental and may change in future builds.

New Interfaces

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

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

Service Container

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

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

Global. Only one instance (singleton) is shared among all sessions.
Session. Each session gets its own instance.
Transient. Each request gets a new instance.

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

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

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

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

DataGridView.DataRead

DataGridView.NoDataMessage

Shows like this when the grid is empty.

General Improvements

Rolled up all bug fixes.
Layout speed improvements on the client and server.
Refreshed all icons in designer and Theme Builder.

FAQs

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.

Update Existing Projects

Wisej.NET 3 introduces a new approach for creating and working with projects based on ASP.NET Core. The changes include a new SDK Project Format, Kestrel Web Server, and more.

There is no need to change the project format if you are staying with .NET 4.8! Wisej.NET 3 supports both .NET Framework and .NET Core. You only need to change the project format to the SDK format if you are going to use .NET Core and ASP.NET Core.

The Basics

Change Project Format to SDK

When migrating a Wisej.NET 2.x project to Wisej.NET 3, it's not recommended to change the existing project but rather create a new Wisej project using the new templates and copy over files.

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

Take note of all embedded resources, references and build customizations within the Project.
Unload the Project.
Delete the content of the .csproj file.
Copy the following text into the .csproj file.

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFrameworks>net48;net6.0</TargetFrameworks>
    <PlatformTarget>AnyCPU</PlatformTarget>
    <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
    <EmbeddedResourceUseDependentUponConvention>true</EmbeddedResourceUseDependentUponConvention>
    <RootNamespace>$(MSBuildProjectName.Replace(" ", "_").Replace("-", "_"))</RootNamespace>
    <NoWarn>CA1416</NoWarn>
  </PropertyGroup>

  <PropertyGroup Condition="'$(TargetFramework.TrimEnd(`0123456789`))'=='net'">
    <OutputPath>bin\</OutputPath>
    <StartupObject></StartupObject>
    <OutputType>Library</OutputType>
    <RunCommand>$(ProgramFiles)\IIS Express\iisexpress.exe</RunCommand>
    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
    <RunArguments>/path:"$(MSBuildProjectDirectory)" /port:5000</RunArguments>
  </PropertyGroup>

  <PropertyGroup Condition="'$(TargetFramework.TrimEnd(`0123456789`))'!='net'">
    <StartupObject>$(RootNamespace).Startup</StartupObject>
  </PropertyGroup>

  <ItemGroup Condition="'$(TargetFramework.TrimEnd(`0123456789`))'=='net'">
    <Reference Include="Microsoft.CSharp" />
    <Reference Include="System.Windows.Forms"><Aliases>swf</Aliases></Reference>
    <Reference Include="System.Data.DataSetExtensions" />
    <Compile Remove="Startup.cs" />
    <Content Include="Startup.cs"/>
  </ItemGroup>

  <ItemGroup>
    <Folder Include="Themes\" />
  </ItemGroup>

  <ItemGroup>
    <Content Update="Default.json">
      <CopyToOutputDirectory>Never</CopyToOutputDirectory>
    </Content>
    <Content Update="Web.config">
      <CopyToOutputDirectory>Never</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <None Remove="Default.html" />
    <None Remove="favicon.ico" />
  </ItemGroup>

  <ItemGroup>
    <Content Include="Default.html">
      <CopyToPublishDirectory>Always</CopyToPublishDirectory>
    </Content>
    <Content Include="favicon.ico">
      <CopyToPublishDirectory>Always</CopyToPublishDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Wisej-3" Version="3.0.*" />
    <PackageReference Include="System.Data.SqlClient" Version="4.*" />
  </ItemGroup>

</Project>

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFrameworks>net48;net6.0</TargetFrameworks>
    <PlatformTarget>AnyCPU</PlatformTarget>
    <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
    <EmbeddedResourceUseDependentUponConvention>true</EmbeddedResourceUseDependentUponConvention>
  </PropertyGroup>

  <PropertyGroup Condition="'$(TargetFramework.TrimEnd(`0123456789`))'=='net'">
    <OutputPath>bin\</OutputPath>
    <StartupObject></StartupObject>
    <OutputType>Library</OutputType>
    <RunCommand>$(ProgramFiles)\IIS Express\iisexpress.exe</RunCommand>
    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
    <RunArguments>/path:"$(MSBuildProjectDirectory)" /port:5000</RunArguments>
  </PropertyGroup>

  <PropertyGroup Condition="'$(TargetFramework.TrimEnd(`0123456789`))'!='net'">
    <StartupObject>$(RootNamespace).Startup</StartupObject>
  </PropertyGroup>

  <ItemGroup Condition="'$(TargetFramework.TrimEnd(`0123456789`))'=='net'">
    <Reference Include="Microsoft.CSharp" />
    <Reference Include="System.Windows.Forms" />
    <Compile Remove="Startup.vb" />
    <Content Include="Startup.vb"/>
  </ItemGroup>

  <ItemGroup>
    <Folder Include="Themes\" />
  </ItemGroup>

  <ItemGroup>
    <Content Update="Default.json">
      <CopyToOutputDirectory>Never</CopyToOutputDirectory>
    </Content>
    <Content Update="Web.config">
      <CopyToOutputDirectory>Never</CopyToOutputDirectory>
    </Content>
  </ItemGroup>
  
  <ItemGroup>
    <PackageReference Include="Wisej-3" Version="3.*" />
  </ItemGroup>

</Project>

5. Reload the Project

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

Files that are Embedded Resources are reset to Content, don't forget to set them again to Embedded Resource.

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

It's likely that your projects don't have any Wisej.Framework reference in the .resx files.

Add Startup.cs

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

Right-Click the Project.
Click Add > Class.
Set the name to Startup.cs.
Click Add.
Copy the following content into the Startup.cs file or download the file below.

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.Configuration;
using Wisej.Core;

namespace $safeprojectname$
{
	/// <summary>
	/// The Startup class configures services and the app's request pipeline.
	/// For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940.
	/// </summary>
	public class Startup
	{
		public Startup(IConfiguration configuration)
		{
			Configuration = configuration;
		}
		public IConfiguration Configuration { get; }

		public static void Main(string[] args)
		{
			var builder = WebApplication.CreateBuilder(new WebApplicationOptions
			{
				Args = args,
				WebRootPath = "./"
			});

			var app = builder.Build();
			app.UseWisej();
			app.UseFileServer();
			app.Run();
		}
	}
}

Imports Microsoft.AspNetCore.Builder
Imports Microsoft.AspNetCore.Hosting
Imports Microsoft.Extensions.Configuration
Imports Microsoft.Extensions.DependencyInjection
Imports Microsoft.Extensions.Hosting
Imports Wisej.Core

''' <summary>
''' The Startup class configures services and the app's request pipeline.
''' For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940.
''' </summary>
Public Class Startup

	Public Sub New(configuration As IConfiguration)
		Me.Configuration = configuration
	End Sub
	Public ReadOnly Property Configuration As IConfiguration

	Public Shared Sub Main(args As String())

		Host.CreateDefaultBuilder(args).ConfigureWebHostDefaults(
			Sub(builder)
				builder.UseWebRoot("./")
				builder.UseStartup(Of Startup)()
			End Sub).Build().Run()
	End Sub

	'' This method gets called by the runtime. Use this method to add services to the container.
	Public Sub ConfigureServices(services As IServiceCollection)

	End Sub

	'' This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
	Public Sub Configure(app As IApplicationBuilder, env As IWebHostEnvironment)
		app.UseWisej()
		app.UseFileServer()
	End Sub

End Class

Don't forget to update the Namespace.

Add launchSettings.json

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

Right-Click the project on the \Properties folder.
Click Add > New Item > JSON File.
Name the file launchSettings.json.
Copy the following text into the file.

launchSettings.json

{
    "iisSettings": {
        "windowsAuthentication": false,
        "anonymousAuthentication": true,
        "iisExpress": {
            "applicationUrl": "http://localhost:54429",
            "sslPort": 0
        }
    },
    "profiles": {
        "MyProjectName": {
            "commandName": "Project",
            "launchBrowser": true,
            "applicationUrl": "http://localhost:5000"
        }
    }
}

Profiles define the startup behavior for the application. Don't forget to update the profile names.

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:

GenerateAssemblyInfo = false
EmbeddedResourceUseDependentUponConvention = true
AppendTargetFrameworkToOutputPath = false (.NET Framework)
OutputPath = bin/ (.NET Framework)

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.

Multi Targeting

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

To add multiple targets to your Wisej.NET application, ensure the project uses the format and add the following tag.

net48 must always come first in the csproj file to load the Wisej.NET designer.

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.

Visual Studio Designer

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.

Unfortunately Visual Studio still doesn't support toolbox icons for nuget components. You can always install a custom tab and drag & drop /net48/Wisej.Framework.dll to the toolbox to see the icons. Don't use "Wisej.NET 3" for the tab name or nuget will replace your toolbox content.

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.

Referencing Assemblies

Class Libraries

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

App.csproj

<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>

All referenced assemblies should be copied automatically in .NET Framework.

Dynamic Assemblies

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

In .NET Framework, any assembly referenced by the main Wisej.NET project would have it's dependencies loaded into the App Domain.

For example:

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

Docker Support

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.

When building and running a Docker project, the first TargetFramework is always used. If Docker can't run the first TargetFramework, it will target the second or third listed framework.

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.

Be sure to update the Dockerfile if the TargetFramework is not .NET5.0.

Troubleshooting

Missing Templates

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
- If the \Wisej.NET 3 directory is missing, run the installer again or download the templates from this .

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

Ensure that you restore net48 to the first listed framework in TargetFrameworks to load the designer.

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

Ensure that you restore net48 to the first listed framework in TargetFrameworks to load the designer.

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.

What's new in 3.0

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.

Wisej.NET 3 for .NET Framework 4.8 replaces Wisej.NET 2.5 while Wisej.NET 3 for .NET Core 6 is a new build for ASP.NET Core applications that can run on Windows, Linux and MacOS.

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

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

Wisej.NET supported the OWIN middleware approach since 1.5, based on Microsoft's Katana.

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

app.UseWisej();

app.UseWisej()

All ASP.NET pages and all ASP.NET controls will NOT work on ASP.NET Core.

New Features

Download Callback

All the , and 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 (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 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 .

Commanding

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

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

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

Use the new 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;
      });
  }
}

This new feature is still experimental and may change in future builds.

New Interfaces

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

. Implemented by all controls that have the Label property.
. Implemented by all controls that have the various Image (ImageIndex, ImageKey, ImageSource) properties.
. Implemented by all controls that have the ReadOnly property.
. 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 and has two new methods to manage services: and with several overloads.

Global. Only one instance (singleton) is shared among all sessions.
Session. Each session gets its own instance.
Transient. Each request gets a new instance.

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 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 is in , 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 and events.

However, the events are fired every single time the application code uses a cell in the grid (in 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 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 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 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.

Update Existing Projects

Wisej.NET 3 introduces a new approach for creating and working with projects based on ASP.NET Core. The changes include a new SDK Project Format, Kestrel Web Server, and more.

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.

Take note of all embedded resources, references and build customizations within the Project.
Unload the Project.
Delete the content of the .csproj file.
Copy the following text into the .csproj file.

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFrameworks>net48;net6.0</TargetFrameworks>
    <PlatformTarget>AnyCPU</PlatformTarget>
    <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
    <EmbeddedResourceUseDependentUponConvention>true</EmbeddedResourceUseDependentUponConvention>
    <RootNamespace>$(MSBuildProjectName.Replace(" ", "_").Replace("-", "_"))</RootNamespace>
    <NoWarn>CA1416</NoWarn>
  </PropertyGroup>

  <PropertyGroup Condition="'$(TargetFramework.TrimEnd(`0123456789`))'=='net'">
    <OutputPath>bin\</OutputPath>
    <StartupObject></StartupObject>
    <OutputType>Library</OutputType>
    <RunCommand>$(ProgramFiles)\IIS Express\iisexpress.exe</RunCommand>
    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
    <RunArguments>/path:"$(MSBuildProjectDirectory)" /port:5000</RunArguments>
  </PropertyGroup>

  <PropertyGroup Condition="'$(TargetFramework.TrimEnd(`0123456789`))'!='net'">
    <StartupObject>$(RootNamespace).Startup</StartupObject>
  </PropertyGroup>

  <ItemGroup Condition="'$(TargetFramework.TrimEnd(`0123456789`))'=='net'">
    <Reference Include="Microsoft.CSharp" />
    <Reference Include="System.Windows.Forms"><Aliases>swf</Aliases></Reference>
    <Reference Include="System.Data.DataSetExtensions" />
    <Compile Remove="Startup.cs" />
    <Content Include="Startup.cs"/>
  </ItemGroup>

  <ItemGroup>
    <Folder Include="Themes\" />
  </ItemGroup>

  <ItemGroup>
    <Content Update="Default.json">
      <CopyToOutputDirectory>Never</CopyToOutputDirectory>
    </Content>
    <Content Update="Web.config">
      <CopyToOutputDirectory>Never</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <None Remove="Default.html" />
    <None Remove="favicon.ico" />
  </ItemGroup>

  <ItemGroup>
    <Content Include="Default.html">
      <CopyToPublishDirectory>Always</CopyToPublishDirectory>
    </Content>
    <Content Include="favicon.ico">
      <CopyToPublishDirectory>Always</CopyToPublishDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Wisej-3" Version="3.0.*" />
    <PackageReference Include="System.Data.SqlClient" Version="4.*" />
  </ItemGroup>

</Project>

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFrameworks>net48;net6.0</TargetFrameworks>
    <PlatformTarget>AnyCPU</PlatformTarget>
    <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
    <EmbeddedResourceUseDependentUponConvention>true</EmbeddedResourceUseDependentUponConvention>
  </PropertyGroup>

  <PropertyGroup Condition="'$(TargetFramework.TrimEnd(`0123456789`))'=='net'">
    <OutputPath>bin\</OutputPath>
    <StartupObject></StartupObject>
    <OutputType>Library</OutputType>
    <RunCommand>$(ProgramFiles)\IIS Express\iisexpress.exe</RunCommand>
    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
    <RunArguments>/path:"$(MSBuildProjectDirectory)" /port:5000</RunArguments>
  </PropertyGroup>

  <PropertyGroup Condition="'$(TargetFramework.TrimEnd(`0123456789`))'!='net'">
    <StartupObject>$(RootNamespace).Startup</StartupObject>
  </PropertyGroup>

  <ItemGroup Condition="'$(TargetFramework.TrimEnd(`0123456789`))'=='net'">
    <Reference Include="Microsoft.CSharp" />
    <Reference Include="System.Windows.Forms" />
    <Compile Remove="Startup.vb" />
    <Content Include="Startup.vb"/>
  </ItemGroup>

  <ItemGroup>
    <Folder Include="Themes\" />
  </ItemGroup>

  <ItemGroup>
    <Content Update="Default.json">
      <CopyToOutputDirectory>Never</CopyToOutputDirectory>
    </Content>
    <Content Update="Web.config">
      <CopyToOutputDirectory>Never</CopyToOutputDirectory>
    </Content>
  </ItemGroup>
  
  <ItemGroup>
    <PackageReference Include="Wisej-3" Version="3.*" />
  </ItemGroup>

</Project>

5. Reload the Project

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

Files that are Embedded Resources are reset to Content, don't forget to set them again to Embedded Resource.

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

It's likely that your projects don't have any Wisej.Framework reference in the .resx files.

Add Startup.cs

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

Right-Click the Project.
Click Add > Class.
Set the name to Startup.cs.
Click Add.
Copy the following content into the Startup.cs file or download the file below.

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.Configuration;
using Wisej.Core;

namespace $safeprojectname$
{
	/// <summary>
	/// The Startup class configures services and the app's request pipeline.
	/// For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940.
	/// </summary>
	public class Startup
	{
		public Startup(IConfiguration configuration)
		{
			Configuration = configuration;
		}
		public IConfiguration Configuration { get; }

		public static void Main(string[] args)
		{
			var builder = WebApplication.CreateBuilder(new WebApplicationOptions
			{
				Args = args,
				WebRootPath = "./"
			});

			var app = builder.Build();
			app.UseWisej();
			app.UseFileServer();
			app.Run();
		}
	}
}

Imports Microsoft.AspNetCore.Builder
Imports Microsoft.AspNetCore.Hosting
Imports Microsoft.Extensions.Configuration
Imports Microsoft.Extensions.DependencyInjection
Imports Microsoft.Extensions.Hosting
Imports Wisej.Core

''' <summary>
''' The Startup class configures services and the app's request pipeline.
''' For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940.
''' </summary>
Public Class Startup

	Public Sub New(configuration As IConfiguration)
		Me.Configuration = configuration
	End Sub
	Public ReadOnly Property Configuration As IConfiguration

	Public Shared Sub Main(args As String())

		Host.CreateDefaultBuilder(args).ConfigureWebHostDefaults(
			Sub(builder)
				builder.UseWebRoot("./")
				builder.UseStartup(Of Startup)()
			End Sub).Build().Run()
	End Sub

	'' This method gets called by the runtime. Use this method to add services to the container.
	Public Sub ConfigureServices(services As IServiceCollection)

	End Sub

	'' This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
	Public Sub Configure(app As IApplicationBuilder, env As IWebHostEnvironment)
		app.UseWisej()
		app.UseFileServer()
	End Sub

End Class

Don't forget to update the Namespace.

Add launchSettings.json

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

Right-Click the project on the \Properties folder.
Click Add > New Item > JSON File.
Name the file launchSettings.json.
Copy the following text into the file.

717B

launchSettings.json

{
    "iisSettings": {
        "windowsAuthentication": false,
        "anonymousAuthentication": true,
        "iisExpress": {
            "applicationUrl": "http://localhost:54429",
            "sslPort": 0
        }
    },
    "profiles": {
        "MyProjectName": {
            "commandName": "Project",
            "launchBrowser": true,
            "applicationUrl": "http://localhost:5000"
        }
    }
}

Profiles define the startup behavior for the application. Don't forget to update the profile names.

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:

GenerateAssemblyInfo = false
EmbeddedResourceUseDependentUponConvention = true
AppendTargetFrameworkToOutputPath = false (.NET Framework)
OutputPath = bin/ (.NET Framework)

Implementation Changes

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.