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

dotnet new web -n CentiasQuickstart
cd CentiasQuickstart

Add Centias

1. Add private NuGet feed

You have to replace YOUR_EMAIL_ADDRESS with the email your account on centias.com is registered with. Replace YOUR_API_TOKEN with an API token from your Centias account. If you don't have an API token, you may create one in your account.

For global use, you can execute the following command.

dotnet nuget add source "https://nuget.centias.com/v3/index.json" \
 --name "centias.com" \
 --username YOUR_EMAIL_ADDRESS \
 --password YOUR_API_TOKEN \
 --store-password-in-clear-text

Alternatively, you can use the source by adding the following configuration to a NuGet.Config of your choice:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
        <add key="centias.com" value="https://nuget.centias.com/v3/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <centias.com>
            <add key="Username" value="YOUR_EMAIL_ADDRESS" />
            <add key="ClearTextPassword" value="YOUR_API_TOKEN" />
        </centias.com>
    </packageSourceCredentials>
</configuration>

2. Add Centias as dependency

Execute the following command from your project folder.

dotnet add package Linkerion.Centias

3. Configure Centias

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 the ./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 the 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 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 your Product 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.