Contribute to Docs Contribute to Docs

Application Setup

This section shows how to setup and configure Piranha in your Application Startup and is intended for users who wants to create their application from scratch and not have this code generated by any of the available project templates.

About Application Startup

In ASP.NET application startup is handled in two methods, ConfigureServices and Configure. In the first method you register the different services that should be available in the DI Container, and in the second you perform additional setup on the registered services and configure the middleware pipeline for the application.

Template Startup

After creating an empty ASP.NET web application your startup methods will look like this. As you can see there are no services added to the application and in Configure basic routing and a Hello world endpoint has been added for testing the application.

Classic Startup

public void ConfigureServices(IServiceCollection services)
{
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapGet("/", async context =>
        {
            await context.Response.WriteAsync("Hello World!");
        });
    });
}

.NET6 Startup

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Adding Piranha

Now that we've taken a look at the startup code that the empty template gives us, let's see what we need to add and modify to add Piranha to the application.

Adding Using Directives

Before adding code into our setup methods we will start by adding some using directives in Startup.cs so we won't need to write out the entire namespace everytime we call the components we want from Piranha.

using Microsoft.EntityFrameworkCore;
using Piranha;
using Piranha.AspNetCore.Identity.SQLite;
using Piranha.AttributeBuilder;
using Piranha.Data.EF.SQLite;

Classic Startup

ConfigureServices

In ConfigureServices we add a call to AddPiranha() which adds the basic services needed. It's also inside this method that we register the different components we choose to use in our application in the project setup.

public void ConfigureServices(IServiceCollection services)
{
    services.AddPiranha(options =>
    {
        options.UseCms();
        options.UseManager();
        options.UseFileStorage(naming: Piranha.Local.FileStorageNaming.UniqueFolderNames);
        options.UseImageSharp();
        options.UseMemoryCache();
        options.UseTinyMCE();
        options.UseEF<SQLiteDb>(db =>
            db.UseSqlite("Filename=./PiranhaWeb.db"));
        options.UseIdentityWithSeed<IdentitySQLiteDb>(db =>
            db.UseSqlite("Filename=./PiranhaWeb.db"));
    });
}

Configure

Before configuring any other parts of Piranha we need to make a call to App.Init() which initializes the main Piranha application object. As a parameter this needs an IApi, which has been registered in ConfigureServices, this is also why we've added a third parameter to Configure.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, IApi api)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    App.Init(api);

    app.UsePiranha(options => {
        options.UseManager();
        options.UseTinyMCE();
        options.UseIdentity();
    });
}

As you can also see we have also removed the following code from the template:

app.UseRouting();

app.UseEndpoints(endpoints =>
{
    endpoints.MapGet("/", async context =>
    {
        await context.Response.WriteAsync("Hello World!");
    });
});

The reason for this is that UseCms() sets up these things for you as a convinence. Inside this method we have also added the middleware components for the manager interface, Tiny editor and Identity user management.

.NET6 Startup

The new startup syntax pretty much follows the same principals. First you create a WebApplicationBuilder to which you add all of your services. Then you build a WebApplication and add all of your neccessary middleware and other components.

var builder = WebApplication.CreateBuilder(args);

builder.AddPiranha(options =>
{
    options.UseCms();
    options.UseManager();
    options.UseFileStorage(naming: Piranha.Local.FileStorageNaming.UniqueFolderNames);
    options.UseImageSharp();
    options.UseTinyMCE();
    options.UseMemoryCache();
    options.UseEF<SQLiteDb>(db =>
        db.UseSqlite("Filename=./PiranhaWeb.db"));
    options.UseIdentityWithSeed<IdentitySQLiteDb>(db =>
        db.UseSqlite("Filename=./PiranhaWeb.db"));
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

app.UsePiranha(options =>
{
    App.Init(options.Api);

    options.UseManager();
    options.UseTinyMCE();
    options.UseIdentity();
});

app.Run();

As you can see the options within UsePiranha() exposes an Api property that you can use. If you want to resolve the IApi outside of this method you have to remember to create a scope first as scoped services can't be resolved from the root provider.

Advanced Configuration

There are many options you can set for your application startup that are useful if for example you are integrating Piranha into an existing application. You can read more about them here.

DocsDocumentation