SaaS configuration

Kentico’s SaaS offering provides infrastructure and supporting services that allow you to deploy, host and manage Xperience by Kentico projects in the cloud. With the features and benefits of hosting your projects in the cloud also comes some necessary configuration you need to do for your projects to work optimally. To configure your application:

1. Configure identification of your working environment.
2. Enable Microsoft Application Insights.
3. Enable managed SendGrid integration.
4. (Optional) Configure Cloudflare CDN.
5. (Optional) Configure Azure Blob storage folder mapping for media library files and any unmanaged binary files referenced by your application or you can consider other File system providers. Consider this configuration, especially if your application works with binary files stored outside of the dedicated ~/assets directory that is mapped to the blob by default. Persisting binary data outside of the blob storage can be unreliable and lead to data loss in case the hosting service recycles the application (e.g., due to infrastructure changes).
6. (Optional) Define a custom static page to display when your application is unavailable.

To see more information about the configuration of custom domains visit website domains or email sending domains.

Environment identification extension methods

Use IsQa() and IsUat() extension methods (available in the Kentico.Xperience.Cloud namespace) alongside native .NET HostingEnvironmentExtensions methods IsDevelopment() and IsProduction() to identify the currently active environment.

For example, use the environment identification extension methods to integrate Twilio SendGrid in QA, UAT, and production environments but not in your local development environment.

using Kentico.Xperience.Cloud;

...

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

...

if (builder.Environment.IsQa() || builder.Environment.IsUat() || builder.Environment.IsProduction())
{
    // Code executed in QA, UAT, and Production environments
}

Microsoft Application Insights integration

Xperience integrates Application Insights for ASP.NET Core applications to enable monitoring and aggregation of metrics for your website:

• Event log – errors and warnings from the Xperience event log.
• .NET exceptions and errors – in addition to errors that are included in the Xperience event log, also covers exceptions that can occur before the Xperience application is fully running.
• (Optional) Client-side telemetry

You can view the Application Insights logs for your deployments in Xperience Portal using the corresponding applications under the Monitoring section:

• Event log – displays entries from the Xperience event log and any custom messages sent via the Application Insights SDK.
• Exceptions – displays all .NET exceptions (errors) from Application Insights.

Enabling the Application Insights integration is also helpful if you ever need to debug or monitor your application with the Kentico support team.

Enable Microsoft Application Insights integration

1. Open your Xperience project in Visual Studio and edit the Program.cs file.

2. Call WebApplicationBuilder.Services.AddXperienceCloudApplicationInsights when building the web application.

   C#

   Enabling AppInsights integration

   Copy

   
   
    using Kentico.Xperience.Cloud;
   
    ... 
   
    WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
   
    ...
   
    builder.Services.AddXperienceCloudApplicationInsights(builder.Configuration);
   
    

   Refer to Microsoft’s documentation on how to use Application Insights in Visual Studio in a development environment.

3. (Optional) Enable client-side telemetry.

4. Rebuild the solution.

Cloudflare CDN

The SaaS environment integrates Cloudflare CDN to ensure better application performance and availability by distributing the network load across the CDN data centers and by caching website resources.

Cloudflare CDN performs caching as described in Default Cache Behavior.

• Files with the Default cached extensions (images, videos, CSS, JS, PDF, etc.) are cached. By default, the cache time-to-live (TTL) is based on the response’s HTTP status code – see Edge TTL.
• The HTML output of pages is not cached.

You can control the CDN caching for supported file extensions by setting the Cache-Control HTTP header directives for each response. For example:

• no-cache, private, no-store, max-age=0 – disables caching
• max-age=<seconds> – enables caching with the specified time-to-live (TTL). For more information, see Retention versus Freshness (TTL).

There are several ways to set HTTP headers, for example, by using the ResponseCache attribute to set Cache-Control directives. See Response caching in ASP.NET Core to learn how to set HTTP headers in ASP.NET Core.

For example, the following code shows how to set the Cache-Control header for static files in your application’s Program.cs file:

...

builder.Services.Configure<StaticFileOptions>(o =>
{
    o.OnPrepareResponse = context =>
    {
        // Caches static files for 7 days
        context.Context.Response.Headers.Append("Cache-Control", "public,max-age=604800");
    };
});

...

app.UseStaticFiles();

...

Define a custom App Offline file

When the application is offline, for example, when scheduled Xperience Portal project maintenance is in progress, a generic .NET static page is displayed when accessing the application.

Create an app_offline.htm_ file in the project’s root to replace the default generic page. The app_offline.htm page is displayed only if the database is updated during the run of the deployment pipeline. The file will be packaged with the deployment package. See Deploy.