4/13/2020 Admin

Oqtane Module Creator

Oqtane is an application that is built using Microsoft’s Blazor technology. It allows you to deploy and run modules written in Blazor. When Oqtane is deployed and running, it provides a dynamic web experience that can be run as client side Blazor or as server side Blazor.

What makes Oqtane different from other Blazor applications, is that it produces the entire website, not just a single application. Oqtane was created by Shaun Walker and is inspired by the DotNetNuke web application framework. Initially created as a proof of concept, Oqtane is a native Blazor application written from the ground up using modern .NET Core technology. It is a modular framework offering a fully dynamic page compositing model, multi-site support, designer friendly templates ( skins ), and extensibility via third party modules.

Creating A Custom Module For Oqtane

To extend and expand Oqtane, you can create custom modules.

There are two methods to create custom modules in Oqtane, inline, and external (as a separate Visual Studio project).

Create an Inline Module

Run Oqtane, log in as the Host account and open the Menu.

Select Add under Page Management.

Create a new page called Hello World Inline.

The page will be added to the navigation menu.

Select the link to navigate to the page

Click the Menu button to open the Menu, and add the Module Creator module to the page.

Close the menu.

Fill in the form and click Create Module.

Oqtane will need to restart to create the module.

If you are running the site in Visual Studio debugging mode, Visual Studio will stop.

Restart Visual Studio.

Oqtane will detect that a new module has been added and it will install the module.

We can confirm this by opening the menu…

Going to the Admin Dashboard…

Selecting Module Management…

… and we can view the Module definition.

Explore The Module

If we navigate to the page we created we will see the module.

Clicking the PageEdit button will allow us to see the Add HelloWorld button.

This will bring up a popup that allows us to add items.

We can edit and delete the items.

We can also go to the Manage Settings dialog.

This will allow us to navigate to the custom Settings page.

We can enter a custom settings value.

Looking At The Code

In Visual Studio, we can see that the wizard created a lot of code that gives us a good starting point for our custom module.

When we look in the database, we see that the table has been created to hold the data for the module code that was created.

We can also look at the data in the Settings table.

We see the value we entered in the Settings screen.

We can update the code.

For example, open the Oqtane.Client/Modules/HelloWorld/Index.razor page and remove the information text.

When we run the application, the module no longer displays the informational text.

Create an External Module

Creating an external Oqtane module allows us to create a module that is more easily packaged to be distributed to other Oqtane instances.

An External Oqtane module is created outside of the Oqtane solution in a folder at the same level as Oqtane. It contains all of the project and solution files already configured so that it can build and deploy the artifacts to the Oqtane instance. It also has the ability to package a module into a Nuget package.

Repeat the previous steps to create a module, however, this time select External for the Template.

This time we have to look at the file system to see that a new folder was created.

This folder contains all the code created by the wizard, including a Visual Studio solution file.

Open that file in another instance of Visual Studio.

Build The Project

We want to build the project, create the NuGet package for the Module, and put that Nuget package in the Module folder of the Oqtane solution.

Switch to Release mode (By default, the Nuget package is only set to be created when building in Release mode).

Build the Solution.

It should Build without errors.

When we view the Oqtane.Server/wwwroot/Modules directory of the Oqtane solution, we see the NuGet package for the Blog module has been copied to that location.

When we run the Oqtane application, we see that the module will be installed and will be usable.

Distribute Your Custom Module

You can install the .nupkg module in other Oqtane installations using Module Management, either by uploading it, or downloading it from Nuget in the Available Modules section (if you first upload the module to Nuget with the tag: Oqtane

Note: the module creator creates a *.nuspec for your module which contains the required Nuget tags automatically.

Debugging External Oqtane Modules

Debugging inline Oqtane modules is easy, simply set a breakpoint and hit F5 in Visual Studio, and when you run the Oqtane application it will hit your breakpoints.

For external Oqtane modules, you will want to open the Oqtane solution in one instance of Visual Studio, and the external Oqtane module in a separate instance of Visual Studio.

In the Visual Studio instance that contains the external module, select Debug mode.

Then Rebuild Solution.

You will see that the .pdb files, required for debugging, have been copied to the Oqtane solution.

In the Visual Studio instance that contains the Oqtane solution, rebuild the solution, then select Debug, then Start Without Debugging.