Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Wisej.NET 3 is the first release of Wisej 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 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 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 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 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 Project Properties for an example if the ones we added to our templates.
New projects can target multiple .NET platforms. When you create a new Wisej 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.
Now that Wisej 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 supported the OWIN middleware approach since 1.5, based on Microsoft's Katana.
This is how you add Wisej to a standard ASP.NET Core application:
All ASP.NET pages and all ASP.NET controls will NOT work on ASP.NET Core.
While the vast majority of the work in Wisej 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.
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.
This is a powerful new feature that allows an additional level of control that was not possible before.
Wisej 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.
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.
This new feature is still experimental and may change in future builds.
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.
Wisej 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 will automatically try to instantiate the service class on first use (on demand). As soon as the service goes out of scope, Wisej 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.
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.
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.
Rolled up all bug fixes.
Layout speed improvements on the client and server.
Refreshed all icons in designer and Theme Builder.
Yes.
There are two sets of templates available in Wisej 3.
One set of templates uses Wisej 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.
No. Wisej 3 was designed for .NET 5+.
Yes.
Yes, but you will lose access to the designer.
All Wisej projects must target .NET Framework v4.8 to use the designer.
Yes but you have to create the docker file. We only provide a basic docker file for Ubuntu.
Yes. We provide a basic docker file for Ubuntu.
Yes, unlike standard ASP.NET Core projects, which have dropped VB.NET, Wisej features VB.NET templates for .NET 6.
There is no need to change the project format if you are staying with .NET 4.8! Wisej 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.
When migrating a Wisej 2.x project to Wisej 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 to Wisej 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.
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.
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.
A Startup.cs file is required for ASP.NET Core projects (Wisej projects targeting .NET 6+).
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.
Don't forget to update the Namespace.
Wisej 3 projects targeted for .NET 6+ require adding a launchSettings.json file to the /Properties directory of the project.
Click Add > New Item > JSON File.
Name the file launchSettings.json.
Copy the following text into the file.
Profiles define the startup behavior for the application. Don't forget to update the profile names.
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:
Wisej 3 introduces a new approach for creating and working with projects based on ASP.NET Core. The changes include a new , Kestrel Web Server, and more.
Right-Click the project on the \Properties folder .
= false
= true
= false (.NET Framework)
= bin/ (.NET Framework)
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 3 applications can be packaged and run in these containers.
When creating a cross-platform Wisej 3 application, Visual Studio will prompt the user to add Docker support to the project.
To run the Wisej 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.
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 3 application that targets .NET 5.
Be sure to update the Dockerfile if the TargetFramework is not .NET5.0.
Beginning with Wisej 3, projects will be able to target multiple frameworks.
To add multiple targets to your Wisej application, ensure the project uses the SDK-Project format and add the following tag.
net48 must always come first in the csproj file to load the Wisej designer.
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:
Multitargeting will inevitably require the use of conditional compilation and excluding certain source code files from some platforms.
In our sources we used Shared Projects and conditional property groups in the project file to compile "net48/Test.cs" only on .NET 4.8 and "net6.0/Test.cs" only on .NET 6.
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.
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.
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.
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.
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.
Occasionally when creating a new Wisej 3 project using .NET48 and .NET6+ the designer will not be visible upon project creation. Rebuild the project and then restart Visual Studio.
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 into one Visual Studio instance. Visual Studio loads the Wisej 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.
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:
All referenced assemblies should be copied automatically in .NET Framework.
If a project or assembly reference is not used in the main Wisej 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 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 project, you will need to call Application.LoadAssembly() on Wisej.Web.Ext.Bubbles to load the custom library's dependency into the Wisej project.
If the \Wisej 3 directory is missing, run the installer again or download the templates from this .
You may also need to clear the .
The Visual Studio designer in Wisej 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.
Wisej 3 components are available in the toolbox under the "Wisej 3" tab name. Since Wisej 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 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 3 Extension" tab name.
If the toolbox doesn't show the Wisej tab and tools, make sure that the Automatically Populate Toolbox option is set to true.