Getting Started with Oqtane 6.2.x

I’m returning to work with Oqtane, and to be honest, we’re exploring new frameworks at the office that will help us expand our market reach. We specialize in a specific type of development and don’t want to move too far away from .NET in general. We’ve used Oqtane in the past—I’ve even installed it on Linux—but I want to conduct fresh research: try it again, get a feel for it, and potentially move some production-sized projects to it.

There’s a lot to understand about Oqtane, especially because it’s a truly layered development framework where you need to work across different layers. This will be the first article in a series that serves both as a guide and as personal mental notes of things I don’t want to forget the next time I develop prototypes or production sites with Oqtane.

The first topic we’ll review is how to install Oqtane and start it up. Here are the steps I usually follow.

Choosing Your Development Approach

The first question you should ask yourself is: How do you want to develop? There are a few ways to do it, and I’ve watched every video about Oqtane over the last two weeks. Here are your three main options:

Option 1: Clone or Download from GitHub (Main Branch)

The old way was to simply go to GitHub and clone or download the source from the main branch, which is actually the development branch. This approach allows you to see all the ins and outs of the framework—how each module is created and registered, how they use repositories, and so on.

However, this may be overwhelming at the beginning. To be honest, since Oqtane has several layers, I got confused many times and wrote code in the wrong layer more than once.

Option 2: Download a Specific Version from Releases

You can also download just the version you want from the releases section on GitHub. This gives you a stable, versioned codebase to work with.

Option 3: Use .NET Templates (Recommended for Beginners)

Now they have .NET new templates available. If you’re a beginner, I strongly suggest installing the .NET templates and using dotnet new because the structure is much more simplified.

However, if you want to understand the ins and outs of the application framework and how it works, I strongly recommend taking a look at the source code.

Installation Resources

Source Code Repository

You can get the source code at this GitHub repository:

https://github.com/oqtane/oqtane.framework

In the README of that repository, you’ll find instructions for installing the templates.

Using the Templates

Here’s an example of how to install and use the templates:

dotnet new install Oqtane.Application.Template
dotnet new oqtane-app -o MyCompany.MyProject 
cd MyCompany.MyProject
dotnet build
cd Server
dotnet run

Release Versions

In the releases section, you can find the source code for each specific version:

https://github.com/oqtane/oqtane.framework/releases

Solution Structure

The solution structure differs depending on which installation method you choose:

Solution structure when created with the templates:

MyTests/
├── Client/                    # Blazor WebAssembly Client Project
├── Server/                    # ASP.NET Core Server Project
├── Shared/                    # Shared Models and Contracts
├── MyTests.sln               # Solution File
└── README.md                 # Solution Documentation

Solution structure when using the downloaded source:

OqtaneFramework/
├── .github/                      # GitHub configuration and issue templates
├── Oqtane.Application/           # .NET Template for creating new Oqtane apps
├── Oqtane.Client/                # Core Blazor WebAssembly client framework
├── Oqtane.Server/                # Core ASP.NET server framework
├── Oqtane.Shared/                # Shared contracts, models, and interfaces
├── Oqtane.Maui/                  # MAUI mobile application support
├── Oqtane.Package/               # NuGet packaging and distribution tools
├── Oqtane.Updater/               # Framework update/upgrade utilities
├── screenshots/                  # Marketing and documentation images
├── Oqtane.sln                    # Main solution file
├── Oqtane.Maui.sln              # MAUI solution file
├── Oqtane.Updater.sln           # Updater solution file
└── Configuration Files           # Build, deployment, and Git configs

In the source you will also find the source of around 27+ admin modules, which is a great way to learn how to create your own modules.

• Dashboard
• Files (file management)
• Jobs (background job scheduler)
• Languages (localization)
• Login/Register/Reset (authentication)
• Logs (system logging viewer)
• ModuleDefinitions (module registry)
• Modules (module instance management)
• Pages (page/route management)
• Profiles (user profiles)
• RecycleBin (soft delete management)
• Roles (role-based access)
• Search/SearchResults
• Settings (system configuration)
• Site/Sites (multi-tenancy)
• SQL (database query tool)
• SystemInfo (diagnostics)
• Themes (theme management)
• Upgrade (version upgrades)
• UrlMappings (URL rewriting)
• Users (user management)
• Visitors (analytics)

Wrapping Up

That’s it for this first article! We’ve covered the basics of getting Oqtane installed and understanding the different approaches you can take depending on your experience level and project needs.

In the next article, we’ll dive into starting up the application and picking a database provider. This is where things get interesting, as Oqtane supports multiple database options, and understanding how to configure them properly is crucial for getting your project off the ground.

Stay tuned, and happy coding!

---

This is part 1 of a series documenting my journey with Oqtane. Check back soon for the next installment.