.NET Core

Deploying a Wisej .NET Core application to IIS is exactly the same as deploying any ASP.NET Core application. However, it's a bit more complex than an ASP.NET application.

IIS Configuration

Basic Steps

2. Create an application in IIS.

3. Uncomment and update the IIS entries in web.config.

4. Publish the application to a folder using the Visual Studio publishing tool.

5. Create a virtual application in IIS pointing to the published folder.

6. Create a new App Domain set to Unmanaged Code and assign it to the application.

Our templates have already added the commented out IIS configuration to the web.config file:

<handlers>
	<!--
	Uncomment the aspNetCore handler below to deploy to IIS when using .NET Core.
	-->
	<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
	<add name="json" verb="*" path="*.json" type="System.Web.HttpForbiddenHandler" />
	<add name="wisej" verb="*" path="*.wx" type="Wisej.Core.HttpHandler, Wisej.Framework"/>
</handlers>

<!--
Uncomment the aspNetCore section below to deploy to IIS when using .NET Core.
-->
<aspNetCore stdoutLogEnabled="false" hostingModel="InProcess" processPath="bin\Debug\net6.0\WisejWebPageApplication1.exe" arguments="" />

However, the web.config in the project has the processPath set to the debug output. When using the publishing tool, it changes the process path to ".\WisejWebPageApplication1.dll" or ".\WisejWebPageApplication1.exe" depending on the hosting model.

InProcess

When running InProcess, IIS uses the AspNetCoreModuleV2 handler to load your ASP.NET Core app in the app domain's process and directly invokes the OWIN middleware.

OutOfProcess

Configuration File

Security

When deploying on .NET Core, you are unable to use the web.config file to configure the System.Web.HttpForbiddenHandler, which is typically used to block the downloading of potentially sensitive .json files. As a result, these .json files could become accessible for downloading, which might pose a security vulnerability.

Since ASP.NET Core relies on middleware modules instead of using traditional HttpHandlers and HttpModules, to secure specific files or directories, you need to modify the configuration in the Startup.cs file. Adjusting the middleware settings within Startup.cs allows you to implement security measures to protect sensitive files or directories effectively.

Below is an example of how to block access to specific files or directories in ASP.NET Core, based on your security requirements. You can customize the middleware configuration in the Startup.cs file to meet your particular security needs.

// app.UseFileServer();
app.UseWhen(
 cx => !cx.Request.Path.Value.EndsWith(".json", StringComparison.OrdinalIgnoreCase), 
 app => app.UseFileServer()
);

.NET Framework

Basic Steps

2. Create the /bin directory in the application's directory

3. Copy all the assemblies from your local /bin to the server's /bin (no need to copy xml and pdb files)

4. Copy the /Themes folder if you have custom themes or mixins

5. Copy the /Images folder if you have images that need to be served as URLs

6. Copy the /App_Data folder if your application uses it

7. Copy Web.config

8. Copy Default.html (and other html files you use sub-applications)

9. Copy Default.json (and other json configuration files if you use sub-applications)

10. Copy favicon.ico.

References:

Configuration file

There are two solutions:

1. Remove the duplicated setting in the child web.config

2. Add XML statements to remove the duplicated settings in the child web.config.

<modules>
      <remove name="Wisej"/>
      <add name="Wisej" type="Wisej.Core.HttpModule, Wisej.Framework"/>
</modules>

...

<handlers>
  <remove name="json"/>
  <remove name="wisejn"/>
  <add name="json" verb="*" path="*.json" type="System.Web.HttpForbiddenHandler" />
  <add name="wisej" verb="*" path="*.wx" type="Wisej.Core.HttpHandler, Wisej.Framework"/>
</handlers>

Debug Mode

When deploying in production, we recommend to turn off the debug flag in web.config.

<configuration>
  <appSettings>
    <add key="Wisej.LicenseKey" value=""/>
    <add key="Wisej.DefaultTheme" value="Blue-1"/>
  </appSettings> 
  <system.web>
    <compilation debug="true|false" />

When debug mode is false all the .js and .css resources are minified and the debug console in the browser receives much less logging data then debug mode.

License Key

Copy your deployment Wisej Server key to web.config in the Wisej.LicenseKey setting. Make sure the server has internet connection in order to activate the license.

App Pool & Permissions

When you create a new application in IIS, it will be assigned to the DefaultAppPool which uses the ApplicationPoolIdentify as the user. This is fine in most deployments.

If you want to create a new Application Pool it's also fine. The only aspect of the application pool that affects Wisej is the user and the user's permissions: it must have Full Control on the system's Temp directory (which is usually located at C:\Windows\Temp).

Application Request Routing (AAR)

You can also try using the AWS toolkit to deploy to AWS directly from Visual Studio:

.NET Core

Wisej 3 .NET Core applications are self-hosted by default being standard ASP.NET Core applications. ASP.NET Core apps are built to an executable that you can simply start and will start hosting your application. You don't need to use Wisej.HostService.exe.

Basic Steps

Service

2. Add builder.Host.UseWindowsServices() to Startup.cs or Startup.vb (see code snippet below).

4. Now you can start the service like any other Windows service. For any additional configuration option refer to the Microsoft documentation.

Security

When deploying on .NET Core, you are unable to use the web.config file to configure the System.Web.HttpForbiddenHandler, which is typically used to block the downloading of potentially sensitive .json files. As a result, these .json files could become accessible for downloading, which might pose a security vulnerability.

Since ASP.NET Core relies on middleware modules instead of using traditional HttpHandlers and HttpModules, to secure specific files or directories, you need to modify the configuration in the Startup.cs file. Adjusting the middleware settings within Startup.cs allows you to implement security measures to protect sensitive files or directories effectively.

Below is an example of how to block access to specific files or directories in ASP.NET Core, based on your security requirements. You can customize the middleware configuration in the Startup.cs file to meet your particular security needs.

.NET Framework

Basic Steps

1. Create the application directory

2. Copy Wisej.HostService.exe to the application directory

3. Create the /bin directory in the application's directory

4. Copy all the assemblies from your local /bin to the server's /bin (no need to copy xml and pdb files)

5. Copy the /Themes folder if you have custom themes or mixins

6. Copy the /Images folder if you have images that need to be served as URLs

7. Copy the /App_Data folder if your application uses it

9. Copy Default.html (and other html files you use sub-applications)

10. Copy Default.json (and other json configuration files if you use sub-applications)

11. Copy favicon.ico.

Once the deployment directory is ready, you can either register Wisej.HostService.exe as a Windows service, or run it directly as a normal process.

These are the supported startup arguments:

Service

Register the executable to run as a service:

You can start the same service multiple times listening on different ports.

Used in conjunction with a load balancer like NGINX, you can have multiple processes of the same application handle their share of the sessions.

Process

Run Wisej.HostService.exe as any other process. You can configure Windows to start the process at startup or use Windows Task Scheduler or any other means to start the process.

Starts the process listening for connections to localhost on port 8080 (the default).

Web.Config Classic

If your web.config file doesn't include the <system.web> section (classic pipeline), add it as shown in the example below. All it needs is the definition of the Wisej httpModule. under <system.web> and to turn the validation of the integrated mode in <system.webServer>, otherwise IIS will throw in an error.

Once the web.config file includes these settings it can be used with IIS, self hosting, standalone, and Ultidev/Cassini deployments.

Microsoft Azure supports different deployment types for Wisej (ASP.NET) applications. You can deploy to a Web Site (renamed to Web Service), to an IIS instance or a to a Virtual Machine with IIS.

Project Formats

Old Project Format

Supported Frameworks for Publishing

• .NET Framework v4.x

SDK-Project Format

Supported Frameworks for Publishing

• .NET Core

Troubleshooting

.NET Core

The application was published successfully but shows an error 'Couldn't find Wisej.Framework' on startup.

Remove <add name="Wisej" type="Wisej.Core.HttpModule, Wisej.Framework" /> from <modules> in web.config.

The application was published successfully but shows a blank white screen on startup.

Make sure <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" /> is uncommented under <handlers> in web.config.

Security

When deploying on .NET Core, you are unable to use the web.config file to configure the System.Web.HttpForbiddenHandler, which is typically used to block the downloading of potentially sensitive .json files. As a result, these .json files could become accessible for downloading, which might pose a security vulnerability.

Since ASP.NET Core relies on middleware modules instead of using traditional HttpHandlers and HttpModules, to secure specific files or directories, you need to modify the configuration in the Startup.cs file. Adjusting the middleware settings within Startup.cs allows you to implement security measures to protect sensitive files or directories effectively.

Below is an example of how to block access to specific files or directories in ASP.NET Core, based on your security requirements. You can customize the middleware configuration in the Startup.cs file to meet your particular security needs.

.NET Core

Basic Steps

1. After generating a build using the Visual Studio Publishing link above, copy the executable, resource files, and referenced DLLs to the folder they will run in.

2. Test that the deployment works using the dotnet start AppName command.

This is all you need for Apache to dispatch the requests to the Wisej.NET application.

Security

When deploying on .NET Core, you are unable to use the web.config file to configure the System.Web.HttpForbiddenHandler, which is typically used to block the downloading of potentially sensitive .json files. As a result, these .json files could become accessible for downloading, which might pose a security vulnerability.

Since ASP.NET Core relies on middleware modules instead of using traditional HttpHandlers and HttpModules, to secure specific files or directories, you need to modify the configuration in the Startup.cs file. Adjusting the middleware settings within Startup.cs allows you to implement security measures to protect sensitive files or directories effectively.

Below is an example of how to block access to specific files or directories in ASP.NET Core, based on your security requirements. You can customize the middleware configuration in the Startup.cs file to meet your particular security needs.

.NET Framework

Basic Steps

1. Create the application directory on the deployment server

2. Create the /bin directory in the application's directory on the deployment server

3. Copy all the assemblies from your local /bin to the server's /bin (no need to copy xml and pdb files)

4. Copy the /Themes folder if you have custom themes or mixins

5. Copy the /Images folder if you have images that need to be served as URLs

6. Copy the /App_Data folder if your application uses it

7. Copy Web.config

8. Copy Default.html (and other html files you use sub-applications)

9. Copy Default.json (and other json configuration files if you use sub-applications)

10. Copy favicon.ico.

This is all you need for Apache to dispatch the requests to the Wisej.NET application.

Load Balancer

Apache can also serve as a load balancer out of the box. Instead of setting the ProxyPass property to the actual Wisej server, assign it to a balancer group that defines the load balancing rotation.

In some scenarios, the license can't be validated.

Potential Issues During License Activation

1. Network Connectivity: Ensure a stable internet connection.

2. License Limit: Verify the license hasn't exceeded its activation limit.

3. Incorrect License Key: Double-check the entered key for any typos.

4. Firewalls/Antivirus: These might block the activation process; consider temporary disablement.

5. Black-listed domain: Contact us for more information on what IPs and Domains to whitelist.

The "wisej-server.lic" file might become corrupted or be replaced by an outdated version on your server, causing the Invalid License popup to appear.

To mitigate this issue, we advise that you start by:

1. Deleting any old wisej-license.lic file.

2. Restarting the server.

3. Set the wisej-server.lic file to read-only.

.NET Core

Wisej.NET applications targeting .NET Core can follow Microsoft's instructions for deploying an ASP.NET Core application to Linux with NGINX.

Below you will find some useful information related to Wisej.NET-specific deployments.

Basic Steps

1. After generating a build using the Visual Studio Publishing Tool, copy the executable, resource files, and referenced DLLs to the folder they will run in.

2. Test that the deployment works using the dotnet start AppName command.

http {
    
    server {
        listen 80;
        
        location /myapp/ {
            # Location of the Wisej server. 
            proxy_pass http://10.1.10.112:43662; 
        }
    }
}

This is all you need for NGINX to dispatch the requests to the Wisej.NET application on .NET Core.

Security

When deploying on .NET Core, you are unable to use the web.config file to configure the System.Web.HttpForbiddenHandler, which is typically used to block the downloading of potentially sensitive .json files. As a result, these .json files could become accessible for downloading, which might pose a security vulnerability.

Since ASP.NET Core relies on middleware modules instead of using traditional HttpHandlers and HttpModules, to secure specific files or directories, you need to modify the configuration in the Startup.cs file. Adjusting the middleware settings within Startup.cs allows you to implement security measures to protect sensitive files or directories effectively.

Below is an example of how to block access to specific files or directories in ASP.NET Core, based on your security requirements. You can customize the middleware configuration in the Startup.cs file to meet your particular security needs.

// app.UseFileServer();
app.UseWhen(
 cx => !cx.Request.Path.Value.EndsWith(".json", StringComparison.OrdinalIgnoreCase), 
 app => app.UseFileServer()
);

.NET Framework

Basic Steps

1. Create the application directory on the deployment server

2. Create the /bin directory in the application's directory on the deployment server

3. Copy all the assemblies from your local /bin to the server's /bin (no need to copy xml and pdb files)

4. Copy the /Themes folder if you have custom themes or mixins

5. Copy the /Images folder if you have images that need to be served as URLs

6. Copy the /App_Data folder if your application uses it

7. Copy Web.config

8. Copy Default.html (and other html files you use sub-applications)

9. Copy Default.json (and other json configuration files if you use sub-applications)

10. Copy favicon.ico.

http {
    
    server {
        listen 80;
        
        location /myapp/ {
            # Location of the Wisej server. 
            proxy_pass http://10.1.10.112:43662; 
        }
    }
}

This is all you need for NGINX to dispatch the requests to the Wisej.NET application on .NET Framework.

Load Balancer

NGINX can also serve as a load balancer out of the box. Instead of setting the proxy_pass property to the actual Wisej server, assign it to an upstream configuration group that defines the load balancing rotation.

http {
    
    upstream myapp1 {
        ip_hash;
        server 10.1.10.1:52433;
        server 10.1.10.1:52434;
        server 10.1.10.2:52000;
        server 10.1.10.2:52001;
    }
    
    server {
        listen 80;
        
        location /myapp/ {
            # Location of the Wisej server. 
            proxy_pass http://myapp1; 
        }
    }
}

Beginning with Wisej.NET 3.5, we introduced the new Wisej.NET Hybrid system, which is built upon our hybrid MAUI client. This system leverages the capabilities of the .NET Multi-platform App UI (MAUI) to provide a seamless and integrated application development experience, allowing developers to build more versatile applications that can run across various platforms efficiently.

With Wisej.NET Hybrid, you can deploy a Wisej.NET application locally on iOS, Android, macOS, Linux, and Windows. This platform allows you to write your code exclusively in C# or VB.NET and maintain a single code base for all these platforms.

Wisej.NET Hybrid, when on .NET Core, also supports running applications entirely on the local device, enabling a fully offline mode.

For more information, visit the Wisej.NET Hybrid documentation.

Locate the httpdocs or equivalent directory using the control panel, the follow the basic steps below:

• Create the application directory

• Create the /bin directory in the application's directory

• Copy all the assemblies from your local /bin to the server's /bin (no need to copy xml and pdb files)

• Copy the /Themes folder if you have custom themes or mixins

• Copy the /Images folder if you have images that need to be served as URLs

• Copy the /App_Data folder if your application uses it

• Copy Web.config

• Copy Default.html (and other html files you use sub-applications)

• Copy Default.json (and other json configuration files if you use sub-applications)

• Copy favicon.ico.

Prerequisites

Wisej, like most ASP.NET applications, needs to run in Full Trust mode and needs write permissions to the system's /temp directory. When using the web hosting control panel, locate the ASP.NET Settings section and set the CAS trust level to Full.

We tried over a dozen commercial ASP.NET providers with Wisej applications without any major issue.

Deploying a Wisej application can be simplified using Visual Studio Publishing. Using this approach you can deploy directly to Azure, IIS, or a directory on the file system.

.NET Core

Azure Publishing

Publishing to Azure streamlines the deployment of a Wisej application to an Azure App Service Instance with minimal effort. Publishing to Azure copies all the files required for deployment to the app service.

Basic Steps

1. In Solution Explorer, right-click the project node and choose Publish (or use the Build > Publish menu item).

2. If you have previously configured any publishing profiles, the Publish window appears. Select New.

3. In the Publish window, select Azure.

4. Select Azure App Service (Windows) and Next.

5. Sign in with your Azure account, if necessary. Select Create a new Azure App Service...

6. In the Create Azure App Service (Windows) dialog, the App Name, Resource Group, and App Service Plan entry fields are populated. You can keep these names or change them. When ready, select Create.

7. In the Publish dialog, the newly created instance has been automatically selected. When ready, select Finish.

8. Select Publish. Visual Studio deploys the app to your Azure App Service, and the web app loads in your browser. The project properties Publish pane shows the site URL and other details.

Find more information and screenshots on MSDN.

Information about the deployment can be found in the Web Publish Activity window in Visual Studio.

Web Server (IIS) Publishing

Web Server Publishing allows a Wisej application to be rapidly distributed to a local or external IIS server.

Basic Steps

1. In Solution Explorer, right-click the project and choose Publish (or use the Build > Publish menu item).

2. If you have previously configured any publishing profiles, the Publish pane appears. Select New.

3. In the Publish window, choose Web Server (IIS).

5. Configure the required settings for the publish method and select Finish.

6. To publish, select Publish in the summary page. The Output window shows deployment progress and results.

Find more information and screenshots on MSDN.

Folder Publishing

Publishing to a Folder using Visual Studio exports the files needed to deploy the Wisej application to a folder on the file system. This can be used when preparing the distribution for another platform.

Basic Steps

1. In Solution Explorer, right-click the project and choose Publish (or use the Build > Publish menu item).

2. If you have previously configured any publishing profiles, the Publish window appears. Select New.

3. In the Publish window, select Folder.

4. Enter a path or select Browse to specify a folder.

5. Click Finish.

6. Select Publish. Visual Studio builds the project and publishes it to the specified folder.

7. To configure deployment settings, select Edit in the publish profile summary and select the Settings tab.

   • The settings you see depend on your application type.

8. Configure options such as whether to deploy a Debug or Release configuration, and then select Save.

9. To republish, select Publish.

Find more information and screenshots on MSDN.

.NET Framework

Wisej applications are standard web applications and work very well with load balancers. However, Wisej goes a step further and gives you additional features to manage the load across several servers.

You can configure each server running a Wisej application to accept a maximum number of sessions, or to be available for the load balancer only if the CPU load is below a certain percentage and/or the memory usage is below a certain level.

Sticky Sessions

Wisej needs the requests from clients to always be routed to the same server instance. This is usually achieved by configuring your load balancer to either use Sticky Sessions, or another type of routing that guarantees that a specific server instance is assigned to a user.

There are several ways to configure the session affinity feature (sticky sessions):

1. Cookie generated by the load balancer

2. Cookie generate by the application and configure the load balancer to use that cookie

3. Client IP hash

Refer to your load balancer documentation to learn how to enable Session Affinity.

WebSocket

Most load balancers don't enable WebSocket support by default. You have to locate in the documentation how to turn on WebSocket support.

Wisej works perfectly well in HTTP-only mode, it just loses the ability to push updated to the client without a request initiated by the browser.

Failover/Rotation

To implement this feature, Wisej processes the first HTTP request and, before dispatching the request to the application, checks in order:

1. • The default in the built-in healthcheck.json file is false.

HealthCheck.json

Add a custom HealthCheck.json to your application using Add -> New Item -> Wisej 2 -> HealthCheck.

You can also create the file manually. The default file is created and initialized like this:

/**
 * HealthCheck
 *
 * Place the HealthCheck.json file in the /bin directory of the
 * application to enable the enhanced load balancing features.
 *
 * Properties:
 *
 *  enabled:      Enables the enhanced load balancing healthcheck.
 *  maxMemory:    Maximum percentage of allocated memory. Default: 70; 0 = unlimited.
 *  maxSessions:  Maximum number of active sessions: Default: 0; 0 = unlimited.
 *  maxCPU:       Maximum CPU load in percentage: Default: 100; 0 = unlimited.
 *  returnCode:   Http return code to signal that this server is not available. Default: 503.
 *  retryAfter:   Value for the Retry-After header in minutes. Default: 10.
 *  returnUrl:    Url to redirect the client when the server is not available. Default: null.
 */
{
  "enabled": false,
  "maxSessions": 0,
  "maxMemory": 70,
  "maxCPU": 100,
  "returnCode": 503,
  "retryAfter": 10,
  "returUrl": null
}

Values set in HealthCheck.json are also available, to read and to write, in the static class Wisej.Core.HealthCheck.

HealthCheck.IsServerAvailable

This is a placeholder for a custom function that you can install simply by assigning the property to a function. Usually the best place is Program.Main, but you can assign it or change it at any time.

// Assign custom IsServerAvailable
Wisej.Core.HealthCheck.IsServerAvaiable = () => 
{
    // Add custom logic and return true (available) or false.
    return true;
}

Wisej will call this method before loading the application allowing your app to decide whether a particular server can take the incoming session.

Healthcheck

When configuring your load balancer's healthcheck URL simply use your application's URL + "/healthcheck.wx".

There are several ways to install libgdiplus depending on the distribution. If using apt-get, this is the preferred installation script:

sudo apt-get update && apt-get install -y apt-utils
sudo apt-get install -y libfontconfig1
sudo apt-get install -y libgdiplus

We also recommend the installation of Microsoft's fonts:

sudo apt-get update; apt-get install -y ttf-mscorefonts-installer fontconfig

In case the scripts fail, please search online on how to install libgdiplus and microsoft fonts on Linux or MacOS, and contact our support if you have a different solution.

Note: The Linux distribution used in this tutorial video is Ubuntu 22.04.2 LTS. You can get information about which Linux distribution you are using by running the command lsb_release -a

Wisej.NET can be deployed in several ways, with or without a web server:

Usually, the deployment is just a matter of copying the correct files to the target machine and configure the web server to recognize the deployed folder as an application.

We cover each scenario in this document, the most common are:

Sometimes you may need to debug an application in production. Which means you have to debug the server, somehow.

Remote Debugging

Visual Studio supports remote debugging, allowing you to connect to the production machine with Visual Studio running on your development machine.

.NET Framework

All you need to do to deploy your Wisej app as a local app, is to copy the version of Wisej.Application.exe that you want to use along with the deployment files. The executable must be placed in the root folder, at the same level as /bin (not inside /bin).

When your Wisej application is deployed as a Standalone executable running as a desktop application, your "server side" code in .NET is running together with with the "client side" browser. This configuration gives your .NET code full access to the user's machine.

You can:

• Read/write the user's registry

• Read/write the entire file system

• Connect to a local or remote database

• Show native windows and controls

• Launch and control Word or any other local application

It is basically a local application running in the browser.

License

Personalization

You can customize the final executable in several ways:

1. Each of the standalone applications is a simple WinForms project with a form and a web browser control. You can personalize it freely: i.e. add a toolbar, status bar, icon, etc.

2. Change the initial splash loader simply by placing either a splash.png, splash.gif or splash.jpg file in the root project folder.

3. Change the application's icon.

IE

Uses the Internet Explorer component that is already preinstalled with Windows. This is the smallest executable of all at roughly 500KB.

Chromium

Firefox

Edge/Chromium