Contribute to Docs Contribute to Docs

Getting Started

The fastest way to get started is to use one of the Project Templates available. If you want to read more about this, please go to Project Templates.

Installing From NuGet

All libraries and components are available on NuGet. You can read more about the available packages here.

Installing From GitHub

If you want the latest source code and maybe be a part of the community and contribute to Piranha you should head over to GitHub. You can read more about this in Contribute.

Project Setup

Configure the services

In ConfigureServices you should register the component services you want use in your application. As an example, let's look at the service configuration for a project that uses FileStorage, SQLite, TinyMCE and AspNetCore Identity.

public void ConfigureServices(IServiceCollection services)
{
    services.AddPiranha(options =>
    {
        options.UseFileStorage();
        options.UseImageSharp();
        options.UseManager();
        options.UseTinyMCE();
        options.UseMemoryCache();
        options.UseEF(db =>
            db.UseSqlite("Filename=./piranha.razorweb.db"));
        options.UseIdentityWithSeed<IdentitySQLiteDb>(db =>
            db.UseSqlite("Filename=./piranha.razorweb.db"));
    });
}

Service options

AddRazorRuntimeCompilation
services.AddPiranha(options =>
{
    options.AddRazorRuntimeCompilation = true;
});

Enables runtime compilation for Razor .cshtml files. This is useful for development environments so that you don't have to restart the application every time you update a view or page. The default value of this property is false as you shouldn't have runtime compilation enabled in production.

UseAliasRouting
services.AddPiranha(options =>
{
    options.UseAliasRouting = false;
});

If alias routing should be enabled when using the Integrated Middleware. The default value is true.

UsePageRouting
services.AddPiranha(options =>
{
    options.UsePageRouting = false;
});

If page routing should be enabled when using the Integrated Middleware. The default value is true.

UsePostRouting
services.AddPiranha(options =>
{
    options.UsePostRouting = false;
});

If post routing should be enabled when using the Integrated Middleware. The default value is true.

UseSiteRouting
services.AddPiranha(options =>
{
    options.UseSiteRouting = false;
});

If site routing should be enabled when using the Integrated Middleware. This can be disabled if you only have one site in your application. The default value is true.

UseStartpageRouting
services.AddPiranha(options =>
{
    options.UseStartpageRouting = false;
});

If start page routing should be enabled when using the Integrated Middleware. The default value is true.

Advanced Service Configuration

If you need to choose specific Piranha components or maybe configure ASP.NET in a specific way for your application you can add the desired components directly onto the IServiceCollection and take care of the application initialization yourself.

public void ConfigureServices(IServiceCollection services)
{
    services.AddLocalization(options =>
        options.ResourcesPath = "Resources"
    );
    services.AddControllersWithViews();
    services.AddRazorPages()
        .AddPiranhaManagerOptions();

    services.AddPiranha();
    services.AddPiranhaApplication();
    services.AddPiranhaFileStorage();
    services.AddPiranhaImageSharp();
    services.AddPiranhaManager();
    services.AddPiranhaTinyMCE();
    services.AddPiranhaMemoryCache();

    services.AddPiranhaEF(options =>
        db.UseSqlite("Filename=./piranha.razorweb.db")));
    services.AddPiranhaIdentityWithSeed<IdentitySQLiteDb>(options =>
        db.UseSqlite("Filename=./piranha.razorweb.db")));
}

Configure the application

Once the services has been configured you need to initialize Piranha. Let's again look at how it's done in the example project.

public void Configure(IApplicationBuilder app, IApi api)
{
    // Initialize Piranha
    App.Init(api);

    // Configure cache level
    App.CacheLevel = Piranha.Cache.CacheLevel.Full;

    // Build content types
    new ContentTypeBuilder(api)
        .AddAssembly(typeof(Startup).Assembly)
        .Build()
        .DeleteOrphans();

    // Configure editor
    Piranha.Manager.Editor.EditorConfig.FromFile("editorconfig.json");

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

Advanced Configuration

If you need full control of the application configuration you can add the desired components directly on the IApplicationBuilder instead.

public void Configure(IApplicationBuilder app, IHostingEnvironment env, IApi api)
{
    // Initialize Piranha
    App.Init(api);

    // Configure cache level
    App.CacheLevel = Piranha.Cache.CacheLevel.Basic;

    // Build content types
    new ContentTypeBuilder(api)
        .AddAssembly(typeof(Startup).Assembly)
        .Build()
        .DeleteOrphans();

    // Configure Tiny MCE
    EditorConfig.FromFile("editorconfig.json");

    // Register middleware
    app.UseStaticFiles();
    app.UsePiranha();
    app.UseRouting();
    app.UseAuthentication();
    app.UseAuthorization();
    app.UsePiranhaIdentity();
    app.UsePiranhaManager();
    app.UsePiranhaTinyMCE();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");

        endpoints.MapPiranhaManager();
    });
}

The important part here is the order in which the middleware is registered. The current security component should always be registered before the rest of the Piranha middleware, and the rest of the Piranha middleware should be registered before MVC. This is needed as the Piranha middleware re-writes the request and passes it on to to the underlying web framework.