Configuration

You add AppText to an existing ASP.NET Core application in Startup.cs with the services.AddAppText() extension method. This method adds the core services with API and returns an AppTextBuilder object where all extensions are configured.

An example:

services.AddAppText() // Adds AppText core services with API
.AddNoDbStorage('my_storage_folder') // Adds the NoDb storage module
.AddAdmin() // Adds admin interface

The different AppText packages all come with their own extensions and options which are all configured in Startup.cs. This page contains a complete overview of all configuration methods and options.

AppText#

The main AppText NuGet package. Contains core services, REST and GraphQL API's and the NoDb storage implementation.

AddAppText()#

Namespace: AppText.Configuration

This is the main configuration method that adds the core services with API. You can optionally pass an AppTextApiConfigurationOptions action.

Example#

services.AddAppText(options =>
{
options.RoutePrefix = "cms";
options.RequireAuthenticatedUser = true;
});

AddAppText() returns the AppTextBuilder object that can be used to chain all other configuration options.

services.AddAppText(options =>
{
/// ... options
})
.AddOtherConfiguration()
.AddMoreConfiguration()

AppTextApiConfigurationOptions#

optiondescriptiondefault
RoutePrefixThe route prefix for the AppText API. This defines the base url of the API: https://your_host_url/{RoutePrefix}."apptext"
RequireAuthenticatedUserOnly authenticated users are allowed to access the API.false
RequiredAuthorizationPolicyThe name of a pre-defined authorization policy that is applied to the API.null
EnableGraphiqlEnable the interactive Graphql browser (located at /{RoutePrefix}/{appId}/graphql/graphiql).false
RegisterClaimsPrincipalShould HttpContext.User be registered as ClaimsPrincipal?true

InitializeApp()#

Namespace: AppText.Features.Application

Ensure that a specific AppText application always exists by configuring it from code.

Example#

services.AddAppText()
.InitializeApp("my-app", "My Application", new[] { "en", "nl" }, "en");

Parameters#

parameterdescriptionrequired
appIdThe App identifier (only lowercase characters, numbers and underscores allowed).yes
displayNameDisplay name of the App.yes
languagesArray with available languages.yes
defaultLanguageDefault language.yes
isSystemIndicates if an App is a system App (for example, the AppText Admin app).no, default false

AddNoDbStorage()#

Namespace: AppText.Storage.NoDb

Configure AppText to use NoDb as file-based storage implementation.

Example#

var dataPath = Path.Combine(Env.ContentRootPath, "App_Data");
services.AddAppText()
.AddNoDbStorage(dataPath);

Parameters#

parameterdescriptionrequired
baseFolderPhysical folder where AppText content files will be stored.yes

AppText.Storage.LiteDb#

The AppText.Storage.LiteDb NuGet package contains an AppText storage implementation that uses LiteDB as database.

AddLiteDbStorage()#

Configure AppText to use LiteDB for storage.

Example#

var connectionString = $"FileName={Path.Combine(Env.ContentRootPath, "App_Data", "AppText.db")};Mode=Exclusive";
services.AddAppText()
.AddLiteDbStorage(connectionString);

Parameters#

parameterdescriptionrequired
connectionStringThe LiteDB connection string.yes

AppText.Translations#

The AppText.Translations NuGet package contains a standard Content Type, Translation for translations and extensions for the AppText REST API that make it easy to use AppText with external translation libraries. The package comes with support for RESX, GNU gettext .po and JSON formats.

AddTranslations()#

Namespace: AppText.Translations.Configuration

Adds the Translation Content Type and the REST API endpoints for translations. You can optionally pass an AppTextTranslationConfigurationOptions action.

note

When no options are specified, AppText checks if options with the same name are set in AppTextApiConfigurationOptions and applies these.

Example#

services.AddAppText()
.AddTranslations(options =>
{
options.RequiredAuthorizationPolicy = "my-policy"
});

AppTextTranslationConfigurationOptions#

optiondescriptiondefault
RequireAuthenticatedUserOnly authenticated users are allowed to access the Translations API.false
RequiredAuthorizationPolicyThe name of a pre-defined authorization policy that is applied to the Translations API.null

AppText.AdminApp#

The AppText.AdminApp NuGet package contains the Admin interface for the AppText REST API.

note

AppText.AdminApp uses the AppText.Translations package so you don't have to add that package anymore when using the AppText.AdminApp package.

AddAdmin()#

Namespace: AppText.AdminApp.Configuration

Adds the Admin interface to AppText. You can optionally pass an AppTextAdminConfigurationOptions action.

note

When no options are specified, AppText checks if options with the same name are set in AppTextApiConfigurationOptions and applies these.

Example#

services.AddAppText()
.AddAdmin(options =>
{
options.RoutePrefix = "admin";
options.ApiBaseUrl = "/apptext";
options.RequiredAuthorizationPolicy = "apptext-administrator-only";
});

AppTextAdminConfigurationOptions#

optiondescriptiondefault
RoutePrefixThe Admin interface url prefix (Admin url becomes https://your_host_url/{RoutePrefix}).inherits RoutePrefix of the AppTextApiConfigurationOptions
ApiBaseUrlThe base URL of the AppText REST APISame base url as Admin interface
RequireAuthenticatedUserOnly authenticated users are allowed to access the Admin interface.false
RequiredAuthorizationPolicyThe name of a pre-defined authorization policy that allows users to access the Admin interface.null
AuthTypeThe type of authentication to use for the Admin interface and accessing the API. Options are AppTextAdminAuthType.DefaultCookie or AppTextAdminAuthType.Oidc.AppTextAdminAuthType.DefaultCookie
OidcSettingsOptional OpenID Connect settings (only applies when AuthType is set to AppTextAdminAuthType.Oidc).empty
EmbeddedViewsDisabledDon't use the embedded views (only for development).false

AppText.Localization#

The AppText.Localization NuGet package enables .NET Core apps to use AppText dynamic resources with the standard .NET Core localization API.

AddAppTextLocalization()#

Namespace: AppText.Localization

Enables AppText for localization of the .NET Core host application. You can optionally pass an AppTextLocalizationOptions action.

Example#

services.AddAppText()
.AddAppTextLocalization(options =>
{
options.AppId = "my_host_app";
options.CreateItemsWhenNotFound = true;
options.ConfigureRequestLocalizationOptions = true;
});

AppTextLocalizationOptions#

optiondescriptiondefault
CollectionNameThe collection name where the content items are stored."Resources"
AppIdAppText App id for which the content items should be stored.The Assembly name of the entry assembly (lowercased).
CreateItemsWhenNotFoundCreate new empty content item with a key when the key is not found.false
ConfigureRequestLocalizationOptionsBase the ASP.NET Core request localization options (supported languages, default language) on the AppText appfalse
PrefixContentKeysPrefix localization keys with type or paths. When set to false, localization keys will be shared.true
PrefixSeparatorSeparator between content key prefix and content key."."
DefaultLanguageThe default language of the AppText Appnull
RecycleHostAppAfterSavingAppWhen set to true, the host application is terminated after changing the AppText app. This is required to immediately see the effect of adding new languages or changing the default language. WARNING: this only works when running behind a server like IIS that automatically restarts the process when it is terminated. Do not set this option to true when running standalone. It will kill your host application.false