Create an application with Wisej.NET
Last updated
Last updated
© Ice Tea Group LLC, All Rights Reserved.
by Gabriele del Giovine, translated by Julie Hirt
Wisej.NET allows you to create a variety of types of Web Applications. There are several templates included with the installation of Wisej. Each of the templates is available for the classic .NET framework 4.8 and for .NET 5/6/7. Here is a brief description of each template:
Creates a web application with a page that fills the entire browser. Controls can be placed directly on the page. Page to page navigation happens simply by creating a new Page object and then invoking the Show() method.
Creates a web application with a window that is displayed within the browser. Controls are placed within the window. The window has the typical characteristics of an OS Desktop window. It contains a title bar with minimize, maximize and close buttons. The architecture of the application- that it consists of windows- is similar to that of a Winforms application. It implements the Multi-document interface (MDI) windows mechanism with a container window for the other windows.
Creates an application that reproduces a customizable desktop container. The look is that of a Windows desktop and its taskbar. You can add items to the taskbar, show floating windows etc. This template is useful when you need to create very complex applications rich in functions, such as applications that encompass the entire user work environment.
Creates a project of Wisej.NET objects (custom controls) that can be used in other Wisej.NET applications as components.
Creates a Web application with a main page similar to the Web Page Application. However, this template adds all the JavaScript parts and the manifest files necessary for the browser to recognize it as a Progressive Web Application (PWA). Some of the advantages of using a PWA include a decrease in loading time after the initial installation due to the caching of resources and an integrated look with the native client device. PWA applications can have a frame around them, so they look more integrated with the client device instead of having the visual look of a typical browser window.
Creates a Web application with a main page similar to the Web Page Application. However, this template includes the MobileIntegration extension. This allows you to write code that utilizes native device functionality such as the camera, device vibration, device orientation, and native UI components. Wisej mobile apps can run on Android and iOS.
Wisej.NET offers a variety of licensing options. The options range from Community up to the Enterprise level. Community is free but with some restrictions, intended for amateur developers or small businesses with up to 5 developers and operating revenues of less than $1 million. The Enterprise level offers direct named support and priority bugfixes. In terms of development, the main difference between community licenses and paid licenses is some integrations with third-party components via Premium Extensions. For a detailed explanation of the options visit:
Installing and configuring the development environment needed to work with Wisej.NET is simple enough. First you need to have Microsoft Visual Studio installed on your development machine. You can use Microsoft Visual Studio 2019 or 2022 in any of the distributed versions (Professional, Enterprise, Community). You will need the versions of .NET for which you want to develop applications.
You can download Visual Studio here: https://visualstudio.microsoft.com/
During the installation of Visual Studio, make sure to install the following under “Workloads”: ASP.NET and web development, .NET desktop development, and Visual Studio extension development. You can re-run the Visual Studio installer if you have already installed Visual Studio and wish to add these without a complete uninstall and reinstall of Visual Studio.
After installing Visual Studio, installing Wisej.NET consists of downloading and installing the Wisej.NET Visual Studio VSIX package. The package can be retrieved from both the Wisej.NET site and from the Visual Studio Marketplace. These are the download links:
Visual Studio Marketplace
After installation of the Wisej.NET VSIX package, you will have the Wisej.NET designer and its project templates installed in Visual Studio.
More information can be obtained here:
Video showing how to install Wisej:
As for including the Wisej.NET library in a Visual Studio project, Wisej.NET is distributed as a NuGet package. This allows you to simplify the management of Visual Studio projects in relation to the various versions of the components and libraries used. It also makes targeting of projects to various versions of .NET and operating system platforms very easy. Here is the link to the various Wisej.NET versions available on NuGet:
The installation of the runtime environment follows the same guidelines as ASP.NET and ASP.NET Core applications, so no special setup or configurations are required other than those specific to the target operating system.
More information can be obtained here:
Once Wisej.NET is installed in your Visual Studio development environment, you will find various templates available. As mentioned earlier, it is possible to create applications for the classic .NET Framework 4.8 and applications for the new cross-platform .NET 5/6/7. The templates distinguish between the types of .NET. The templates that mention (.NET Framework) are templates designed for the classic .NET Framework, while the other templates are for cross-platform versions of .NET. Visually, this is the difference between .NET Framework templates and cross-platform .NET templates:
Depending on the chosen .NET multitargeting we will have a window that guides us through the essential features of our project. In case of multitargeting we will have this dialog window:
In one visual studio solution, you can create projects that target different versions of .NET. Even inside a single project, you can target multiple .NET versions.
Read more information here:
Note: The versions of .NET may vary depending on the ones installed on your computer. It is important to note that the project is always referenced with at least the .NET Framework 4.8 target and optionally with various other installed versions of .NET; this behavior is normal because the current designer of Wisej.NET is made in .NET Framework 4.8. Visual Studio will manage all the compilation commands and component and library references (NuGet or direct) according to the chosen .NET targets.
After you have gone through the "New Project Setup screen, and you click "OK", Visual Studio will open with your project/solution:
Going to the "Solution Explorer" section, and looking under “Dependencies” you can observe how for each .NET target version, the entire set of configurations and references is managed. Note that both the net48 and net7.0 target versions have the Wisej.NET NuGet package.
Wisej.NET uses the NuGet package manager to facilitate its management, allowing for quick changes of referenced versions/builds and updates.
By going to the Visual Studio menu “Tools – NuGet Package Manager – Manage NuGet Packages for Solution” or by right-clicking on the root node of the project (ie "WisejWebApplication1") in the Solution Explorer and selecting the menu item "Manage NuGet Packages" you will be presented with this screen:
As you can see the default source of the packages is the NuGet online repository. If you want to have tighter control of NuGet package sources you can create your own local repositories and force the Visual Studio configuration to use only those repositories. Also note that you must check “Include prerelease” (located in the top middle) if you want to see the NuGet packages for beta versions of Wisej.NET.
When looking at the project properties (right-click on the root node of the project - ie "WisejWebApplication1"- and select "Properties") we observe this:
This project is therefore a "Class Library" targeting .NET 4.8 and .NET 7.
In the "Solution Explorer" section related to the "WisejWebApplication1" project, we can find a series of files that make up the common part of all Wisej.NET Web Applications. These include "Web.Config", "Default.html", "Default.json," "Program.cs" (or "Program.vb" if you use Vb.Net), "Startup.cs" (or "Startup.vb"), and the "Themes" folder. Here follows a description of each file:
Technically, a Wisej.NET application is server-side. Essentially Wisej is a library that works on the ASP.NET framework. Consequently, it shares several features with other ASP.NET applications: namely, being hosted within a Web Server (ie, Kestrel or IIS) and having the same configuration management system, which is based on the Web.Config file. The Web.Config file contains specific configurations for Wisej.NET in terms of Wisej licenses (in the "configuration - appSettings" section) and the various .NET modules and handlers used (in the httpModules, modules, handlers sections).
Default.html is used because a Wisej.NET application is an ASP.NET application. It can be hosted in a process along with other ASP.NET components and share objects such as security contexts, applications, and sessions. Default.html functions as a loader for the Wisej.NET application. It is not mandatory to call it Default.html since it follows the configuration related to the default documents present in the Web.Config.
Let's observe its standard content:
Look at <script src="wisej.wx"></script>. "wisej.wx" does the actual work of loading the Wisej application. The "wisej.wx" file contains the necessary JavaScript runtime for the client browser. The file is dynamically generated in memory at the first launch of the application.
This file contains the configuration parameters for the Wisej.NET application, including the timeout of the session in seconds ("sessionTimeout") and the default culture ("culture"). For a full list of parameters, see below:
Let's go over what this code snippet does:
This simple example consists of 2 keys ("url" and "startup") and their corresponding values. First, the value of the "url" key indicates that "Default.html" will be used as the default html page. This means that if a request is sent to the server for a URL that doesn't specify a file name, that the file "Default.html" will be sent. Second, the value of the "startup" key indicates what assembly will run once the Wisej application starts. We can break this up into two values (before and after the comma):
WisejWebApplication1.Program.Main is the fully qualified namespace (Look at the Program.cs file- this matches up perfectly).
WisejWebApplication1 is the name of the assembly.
The "Startup.cs" file is used for the .NET Core targets and contains the definitions of Wisej.NET .NET Core objects. The Startup.cs file will NOT be used if you run your application in .NET Framework 4.8.
app.UseWisej(); is the part of the code that calls the Wisej middleware, ultimately resulting in the loading of the Wisej application.
The Themes folder contains themes and mixins (theme fragments) created with the Wisej Themes Editor that need to override the default theme indicated in the Web.Config file or in the startup method for application purposes. Themes consist of a JSON file and can be created with the dedicated "Theme Builder" application that can be found at this link:
Wisej.NET is a .NET application and in particular an ASP.NET application in its server-side execution. During development, IISExpress (used by default) or the locally installed IIS server can be used as the web server. In terms of the file system, the application is located in a folder that contains the bootstrap files (Default.html, Default.json) and a "bin" subfolder with referenced .NET assemblies. In the case of our first Web Application, we will have this situation:
The folders "de", "es", "it", etc. present in the "bin" folder contain the Wisej resource files based on the language selected by the user.
When you have .NET multitargeting enabled, the corresponding files can be found in the "bin\Debug" folder. In this case, the project was only built for net7.0.
At runtime, the environment is similar to the development one with some differences:
In Windows environments the full IIS web server is used instead of the IISExpress version.
The Wisej server license key must be specified in the Web.Config file.
The file system structure should include only the bootstrap files (Web.Config, default.html, default.json, the Themes folder, and in the "bin" subfolder only the files necessary for execution).
Prerequisites: Install Visual Studio and the Wisej VSIX package. Then create a new Wisej project using the Wisej Web Application template.
Now let's add some UI and logic. The goal is to add a button to our "Windows1" form that, when pressed (Click event), will display a MessageBox containing the version of .NET with which our Wisej.NET application is running. Here are the steps to follow:
Double-click on the "Window1.cs" file to open it in design view.
Once you open “Window1.cs” in design view, your screen should look like this:
Open the toolbox. You can access the toolbox by going View -> Toolbox, or by clicking on the toolbox icon at the bottom of the design view window.
Select a button object from the Wisej3 control list in the toolbox. You can either click and drag the button into the designer, or you can click once on the button to select it and click again on the designer to place it. If you need to deselect the button, you can hit ”esc”.
4. Click on the button to select it (if it’s not already selected) and look at the “Properties” window. (If you cannot see the properties window, you can open it by clicking on View -> Properties Window.) Scroll down until you see the “Text” property and change the text from “button1” to “Click me!”.
5. Click on the lightning bolt in the properties window to see the events. We are going to handle the Click event of the button. Double-click on the Click event to edit it. (Alternatively, you can use this shortcut: double-click on the button in the designer to handle the Click event.)
6. This will open a new tab in Visual Studio next to the designer view, where you can edit the Window1.cs file. It will create a new function called button1_Click(), which is called when the button is clicked.
Inside of the button1_Click() function, add this code:
This will display a MessageBox containing the version of .NET with which our Wisej.NET application is running.
As with all applications developed in Visual Studio, you can launch the compilation and debug execution using the "F5" function key or the start icon present on the menu bar. For client-side execution, you can choose which browser to use: Microsoft Edge, Firefox, Chrome, Microsoft IE 11, Apple Safari, or Opera. Once your Web Page application is compiled and started, it will appear in your browser.
There are two ways to change the running .NET version- you can change the development version, and you can change the version that is used when deploying to IIS.
Change the development version of .NET Click on the down arrow inside of the “Play” button to bring up additional options. Under “Framework”, you can switch between versions of .NET. The options that you see (net48, net7.0, etc) are based on the .csproj file. You can see the .csproj file by double-clicking on the root node of the project (ie "WisejWebApplication1") in the Solution Explorer. This only affects the version of .NET used when running the project in Visual Studio- when the project is compiled, it will be built for all .NET versions listed in the .csproj file.
Change the .NET version used when deploying to IIS Edit the Web.Config file. Choose the version you want to deploy by editing the processPath parameter. This will change the version that is deployed to IIS. Note that this MUST be a .NET Core version; .NET framework 4.8 will not work.
