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

• Internet Information Server (IIS) is the most common deployment target.

• Cloud deployments, such as Amazon AWS, Microsoft Azure, …

• Most modern ASP.NET Provider.

• and as reverse proxies.

• Desktop Application through the deployment.

• Local service or process through the deployment.

• Containerized deployment using or any other Windows container technology.

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.

The best way is to install Visual Studio on the server and attach to the web server process (for IIS) or to the application's process when deployed as a standalone app.

Remote Debugging

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

Commercial ASP.NET hosting providers are virtually all using IIS and a web administration tool like or . The deployment process is identical to a standard IIS deployment.

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

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.

Amazon AWS doesn't provide an IIS service. The only way to deploy an ASP.NET or a Wisej application is to create an instance of a Windows Server machine, enable IIS and follow the guide or the guide.

AWS also provides its own . Wisej is fully compatible with Amazon's Elastic Load Balancing (including WebSocket support).

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

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.

When deploying using .NET Core on a Linux distribution, or on MacOS, you have to make sure that libgdiplus is installed.

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:

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

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.

In all cases you can publish directly from Visual Studio. Please refer to the guide and to Microsoft's Azure Deployment documentation for ASP.NET.

Project Formats

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.

See and to learn how to emulate push updated in HTTP-only mode.

Failover/Rotation

This is a unique feature only available in Wisej. Through the healthcheck.json file and the callback you can control when to take a specific server offline or return it to service.

Failover works by returning the status at the very first HTTP request for the application's HTML page (usually Default.html): the server has to "fail" at the very first request for the failover feature in the load balancer to kick in and resubmit the request to the next server in the rotation.

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

1. to verify that the healthcheck system is enabled.

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

2. The return value from as returned by the custom function that you may have installed.

If the final result is false, the server will return the error code configured in (the default is 503 Server Unavailable).

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:

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.

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

Healthcheck

Most load balancers use a "healthcheck" URL to probe whether a server is available in order to update their rotation list. Wisej provides a blank URL named healthcheck.wx that simply returns the .

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

.NET Framework

Wisej.NET also supports a local desktop deployment (we call it Standalone deployment) as a local executable. It's very similar to the Electron system, except that we provide the shell for Internet Explorer, Chromium, Firefox and Edge.

You can find the project source on . After downloading the extensions source code, you can compile the HostService projects. In the /bin directory you will find 4 directories (one for each browser) containing a single executable Wisej.Application.exe.

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

It is basically a local application running in the browser.

License

Desktop applications can be redistributed without using a server license. Technology partners can request a free by contacting [email protected].

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

Uses integrated in a WinForms application frame. The final executable is roughly 130MB since we embed the full Chromium system in the executable.

You can update the version simply by copying the newer files over the same files included in our GitHub repository.

Firefox

Uses integrated in a WinForms application frame. The final executable is roughly 102MB since we embed the full Firefox system in the executable.

You can update the version simply by copying the newer files over the same files included in our GitHub repository.

Edge/Chromium

Uses the latest control from Microsoft integrated integrated in a WinForms frame. The final executable is approximately 850KB but it doesn't include the deployment.

You can update the controls simply by copying the newer files over the same files included in our GitHub repository. However, the WebView2 SDK needs to be downloaded and updated independently.

.NET Core

There are a few steps required to deploy to deploy a Wisej.NET app to on .NET Core. use the following Visual Studio Publishing link to generate a build. Then proceed with Basic Steps.

👉 If you are deploying on a distribution or on , make sure is installed.

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

👉 If you are deploying on a distribution or on , make sure is installed.

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.

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

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.

Find more information and screenshots on MSDN.

.NET Framework

.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

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

👉 If you are deploying on a Linux distribution or on MacOS, make sure libgdiplus is installed.

Basic Steps

1. Run the to deploy to a folder.

That's it. When you run YourApplication.exe you can use the --urls command line argument to .

Service

Wisej 3 ASP.NET Core apps can be deployed as a quite easily:

1. Add the nuget to your project.

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

3. Register the service using ""

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

You can run a Wisej application (including Wisej 3 on .NET 4.8) as a self hosting process or service. All you need to do is deploy the executable in the root folder of the deployment directory.

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

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.