Quickstart

In this section we will show you how to set up a demo web application with a database so you can get a feeling for how Centias works.

Prerequisites

• .NET 8.0 or higher
• Docker Desktop

Install prerequisites

1. Follow the official guide from Microsoft to install .NET
2. Download and install Docker for Desktop

Setup new solution

Open a terminal window and execute the following commands:

dotnet new web -n CentiasQuickstart
cd CentiasQuickstart

Now you have created a new .NET solution called CentiasQuickstart. You can open the solution in an IDE of your choice or continue the rest of the project setup directly in the terminal window.

Add Centias

1. Add Centias as dependency

Execute the following command from your project folder.

dotnet add package Linkerion.Centias

Or if you have a visual NuGet package manager, type in "Centias" in the search bar and choose the package Linkerion.Centias.

2. Configure Centias in your project

In your Program.cs call AddCentias() and UseCentias() in that order. You can leave the LicenseKey field free for now.

The BaseUrl should match the applicationUrl in your ./Properties/launchSettings.json for development.

using Linkerion.Centias;
using Microsoft.EntityFrameworkCore;
using CentiasQuickstart;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCentias(new CentiasOptions
{
    Title = "Centias Quickstart",
    BaseUrl = "http://localhost:8535",
    LicenseKey = null
});
var app = builder.Build();

app.UseCentias();
app.Run();

Create your first entity

Here we configure a simple database model to use as an example entity.

using System.ComponentModel.DataAnnotations;
using Microsoft.EntityFrameworkCore; 

namespace CentiasQuickstart;

public class Product
{
    [Key]
    public int Id { get; set; }
    
    [Required]
    public string Name { get; set; }
    
    public DateTimeOffset CreatedAt { get; set; } = DateTimeOffset.Now;
}

Configure and add DbContext

A DbContext must be configured and all relevant database sets added.

using Microsoft.EntityFrameworkCore;

namespace CentiasQuickstart;

public class QuickstartDbContext : DbContext
{
    public QuickstartDbContext(DbContextOptions<QuickstartDbContext> options): base(options) {}

    public DbSet<Product> Products { get; set; }
}

Add the provider of the database engine you wish to use to your project. You can find a list of all supported EF Core providers here. For this example, we use a MySql provider maintained by the Pomelo Foundation.

.Net 9

dotnet add package Pomelo.EntityFrameworkCore.MySql --prerelease

.Net 8

dotnet add package Pomelo.EntityFrameworkCore.MySql

WARNING

SQLite databases are currently not supported by Centias.

Configure the database connection in your appsettings.Development.json.

{
  "ConnectionStrings": {
    "DefaultConnection": "server=localhost;port=3306;database=CentiasQuickstart;userid=root;password=secret"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

TIP

Credentials for production databases should never be stored in clear text in your solution, instead use services such as key vaults to access credentials securely.

Then we add the DbContext to our Program.cs. This allows us to create and execute migrations and inject the DbContext in other parts of the application.

using Linkerion.Centias;
using Microsoft.EntityFrameworkCore;
using CentiasQuickstart;

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection") ??
                       throw new InvalidOperationException("Connection string 'DefaultConnection' not found.");
builder.Services.AddDbContext<QuickstartDbContext>(options => {
    options.UseMySql(connectionString, ServerVersion.AutoDetect(connectionString));
});

builder.Services.AddCentias(new CentiasOptions
{
    Title = "Centias Quickstart",
    BaseUrl = "http://localhost:8535",
    LicenseKey = null
});
var app = builder.Build();

app.UseCentias();
app.Run();

Create and apply migrations

To create migrations add the Microsoft.EntityFrameworkCore.Design package to your project.

.Net 9

dotnet add package Microsoft.EntityFrameworkCore.Design --version 9.0.4

.Net 8

dotnet add package Microsoft.EntityFrameworkCore.Design --version 8.0.15

Start your MySql database with the following docker script:

docker run -d \
  --name CentiasQuickstart \
   -p 3306:3306 \
   -e MYSQL_ROOT_PASSWORD=secret \
   -e MYSQL_DATABASE=CentiasQuickstart mysql

Now the first migration can be created and applied to the database.

dotnet ef migrations add InitMigration
dotnet ef database update

Your database should now contain the Products table with its associated columns.

Create your first resource

With the migration executed you can start building your first resource for the Product entity. Here is an example ProductResource.cs.

using Linkerion.Centias.Displayables.Fields.Builders;
using Linkerion.Centias.Displayables.Fields.DateTimeOffsetField;
using Linkerion.Centias.Displayables.Fields.TextField;
using Linkerion.Centias.Pages.Resources;

namespace CentiasQuickstart;

public class ProductResource : Resource<QuickstartDbContext, Product, int>
{
    public ProductResource(QuickstartDbContext context) : base(context) {}
    
    public override IList<IResourceFieldBuilder> Fields()
    {
        return
        [
            TextField.Make("Name", nameof(Product.Name)),
            DateTimeOffsetField.Make("Created At", nameof(Product.CreatedAt))
                .HideOnCreate()
                .HideOnEdit()
        ];
    }
}

Run it

You can run the application by either clicking on the Run button (if you're in an IDE) or by typing the following command into your terminal:

dotnet run

Open your web browser and navigate to the address shown in your console, you should see the Centias admin panel with a Products resource listed in the sidebar.

Next steps

Congratulations! You've successfully implemented your first Centias admin panel. Now that you have a feeling how the setup works you can continue building more complex admin panels adapted to your database entities.