Commerce Engine configuration file

Abstract

Lists and describes the Commerce Engine properties available in the configuration JSON file.

Each instance of a Commerce Engine (CE) role in a Commerce deployment has its own config.json file that defines the service application configuration at a high level.

The CE config.json file is located at the root of the Commerce Engine application, in the wwwroot folder, for example: C:\inetpub\wwwroot\CommerceShops_Sc/wwwroot.

This topic lists and describes Commerce Engine configuration settings available in each section of the config.json file, and provides examples based on the sample Commerce Engine solution included in the Sitecore.Commerce.Engine.SDK.zip file:

  • Applications Settings (AppSettings)

  • Azure Application Insights settings

  • Logging settings

  • Serilog settings

  • Caching settings

  • Compression settings

  • Commerce Connector settings

  • Health Check settings

Note

Parameters that use a placeholder as default value (for example, "PlaceholderForSiteTitle" ) can be set using an environment variable file.

The AppSettings section of the Commerce Engine config.json file contains application level settings, for example, parameters used at application startup time.

The following shows an example of the "AppSettings" section:

{
  "AppSettings": {
    "SiteTitle": "PlaceholderForSiteTitle",
    "BootStrapFile": "Global",
    "DeploymentId": "PlaceholderForDeploymentId",
    "EnvironmentName": "PlaceholderForEnvironmentName",
    "EncryptionProtectionType": "Redis",
    "EncryptionCertificateHash": "Enter a valid certificate thumbprint for a PXF file. X-509 not supported yet",
    "EncryptionSID": "Enter a valid SID for a domain registered user",
    "EncryptionKeyStorageLocation": "c:\\Encryption-Keys\\",
    "SitecoreIdentityServerUrl": "PlaceholderForSitecoreIdentityServerUrl",
    "AllowedOrigins": "PlaceholderForBizFxUrl|PlaceholderForSxaStorefrontUrl",
    "AntiForgeryEnabled": "PlaceholderForAntiForgeryEnabled",
    "CommerceServicesHostPostfix": "PlaceholderForCommerceServicesHostPostfix",
    "UseHttpsInKestrel": false,
  },

Application settings description

The following table describes the configuration parameters available in the AppSettings section.

Parameter

Description

"SiteTitle"

The name of the website as displayed in IIS Manager.

Default: "PlaceholderForSiteTitle"

"BootStrapFile"

The name of the JSON file that contains the global environment configuration that is loaded at application startup. By default, this is the Global.json file.

Default: Global

"DeploymentId"

The number (GUID) automatically assigned in Microsoft Azure deployment.

Default: "PlaceholderForDeploymentId"

"EnvironmentName"

The name of the Commerce environment to start at application startup.

Default: "PlaceholderForEnvironmentName"

"EncryptionProtectionType"

Type of of storage used for encryption keys.

Default: "Redis" Cache keys are stored in the Redis cache for distributed applications

Possible values are: "DPAPI-SID", "DPAPI-CERT", "LOCAL", "MACHINE".

"EncryptionCertificateHash"

A valid certificate thumbprint for a PXF file when using "EncryptionProtectionType": "DPAPI-CERT".

"EncryptionSID"

A valid SID for a domain registered user when using "DPAPI-CERT""EncryptionProtectionType": DPAPI-SID

"EncryptionKeyStorageLocation"

Path to the location where to store the encryption key when using "EncryptionProtectionType": "MACHINE".

Default: "c:\\Encryption-Keys\\" ?

"SitecoreIdentityServerUrl"

The URL of the Sitecore Identity server.

Default: "PlaceholderForSitecoreIdentityServerUrl"

"AllowedOrigins"

List of URLs that should be allowed to make cross-origin calls, such as the Business Tools URL, and the storefront URL.

Default: "PlaceholderForBizFxUrl|PlaceholderForSxaStorefrontUrl"

"AntiForgeryEnabled"

Whether to enable antiforgery (boolean).

Default: "PlaceholderForAntiForgeryEnabled"

"CommerceServicesHostPostfix"

Postfix used as the root domain name (two-levels) to append as the hostname for Commerce services.

Default: "PlaceholderForCommerceServicesHostPostfix"

"UseHttpsInKestrel"

Whether to use Https in the Kestrel Web server included by default in ASP.NET Core project templates (boolean).

Default: "false"

Note

This setting is used in a development environment.

The Application Insights section ("ApplicationInsights") in the Commerce Engine config.json file allows you to configure the instrumentation key for Commerce Engine performance monitoring and telemetry.

  "ApplicationInsights": {
    "InstrumentationKey": "",
  },

Azure Application Insights parameter description

The following table describes the parameter in the "ApplicationInsights" section.

Parameter

Description

"InstrumentationKey"

The Azure Application Insights instrumentation key generated for monitoring the Commerce Engine running in a Microsoft Azure resource.

Default: no default

The Logging section in the Commerce Engine config.json contains parameters that allow you to control application log levels, and pipeline trace logging on the Commerce Engine for diagnostic purposes.

{ 
  "Logging": {
    "IncludeScopes": false,
    "LogLevel": {
      "Default": "Warning",
      "System": "Warning",
      "Microsoft": "Warning"
      },
    "SerilogLoggingEnabled": true,
    "PipelineTraceLoggingEnabled": false
  }

Logging parameters description

The following table describes the parameters in the Logging section:

Parameter

Description

"IncludeScopes"

Whether it is required to use scopes.

Default: false

Severity of "LogLevel" to capture for each of the following category:

"Default"

Log level to capture for Default log category:

Default: "Warning"

"System"

Log level to capture for System log category.

Default: "Warning"

"Microsoft"

Log level to capture for Microsoft log category

Default: "Warning"

"PipelineTraceLoggingEnabled"

Whether pipeline tracing is enabled.

Default: false

"SerilogLoggingEnabled"

Whether Serilog logging is enabled.

Default: true

The Serilog section contains configuration settings from the Serilog logging framework that you can use to configure logging levels.

  "Serilog": {
    "Using": [
       "Serilog.Sinks.Literate",
       "Serilog.Sinks.File"],
       "Serilog.Sinks.ApplicationInsights"
       ]
    "MinimumLevel":  {
       "Default": "Warning",
       "Override": {
          "Microsoft": "Warning",
          "System": "Warning"
          }
    "WriteTo": [
       {
        "Name":  "ApplicationInsights",
        "Args":  {
            "restrictedToMinimumLevel":  "Warning",
            "telemetryConverter": "Serilog.Sinks.ApplicationInsights.Sinks.ApplicationInsights.TelemetryConverters.TraceTelemetryConverter, Serilog.Sinks.ApplicationInsights"
            }
         },
    "FileSizeLimitBytes": 100000000
  },

Serilog parameters description

The Serilog Wiki describes Serilog configuration settings used in the preceding code sample.

The "Caching" section in the Commerce Engine config.json file contains settings that specifies the cache provider used by the Commerce Engine.

"Caching":  {
   "Memory":  {
      "Enabled":  false,
      "CacheStoreName":  "Commerce-Memory-Store"
      },
   "Redis":  {
      "Enabled":  true,
      "CacheStoreName":  "Commerce-Redis-Store",
      "Options":  {
          "Configuration":  "PlaceholderForRedisConfiguration",
          "InstanceName":  "PlaceholderForRedisInstanceName"
          }
      }
 },

Caching parameters description

The following table describes caching parameters:

Parameter

Description

"Memory" cache provider parameters:

Note

The memory cache provider is suitable for development environment only, and must not be used for production. The Redis cache provider is recommended for a production deployment.

"Enabled"

Specifies whether to use in memory caching.

Default: "false".

"CacheStoreName"

The name of the cache store used by the memory cache provider.

Default: "Commerce-Memory-Store"

"Redis" cache provider parameters:

"Enabled"

Specifies whether to use in memory caching.

Default: "true"

"CacheStoreName"

The name of Redis cache store.

Default: "Commerce-Redis-Store"

"Configuration"

The configuration used to connect to Redis.

Default: "PlaceholderForRedisConfiguration"

"InstanceName"

The Redis instance name.

Default: "PlaceholderForRedisInstanceName"

The "Compression" section contains configuration parameters that control response compression. The following shows an example of the "Compression" section:

 "Compression": {
   "Enabled": true,
   "ResponseCompressionOptions": {
      "EnableForHttps": true,
      "MimeTypes": [
        "text/plain",
        "text/css",
        "application/javascript",
        "text/html",
        "application/xml",
        "text/xml",
        "application/json",
        "text/json",
        "application/wasm"
      ]
   },
   "GzipCompressionProviderOptions": {
      "Level": "Fastest"
      }
   },

Compression parameters description

The following table describes compression parameters:

Parameter

Description

"Enabled"

Controls whether compression is enabled or disabled.

Default: true

"ResponseCompressionOptions":

"EnableForHttps"

Compresses responses over secure connections.

Default: true

"MimeTypes"

Lists the set of MIME types for compression: "text/plain", "text/css", "application/javascript", "text/html", "application/xml", "text/xml", "application/json", "text/json", "application/wasm"

GzipCompressionProviderOptions:

"Level"

Sets the compression level.

Default: "Fastest"

The CommerceConnector section contains the "ClientId" parameter that specifies the ID of the Commerce Engine Connect client. The default is: "PlaceHolderForCommerceEngineConnectClientId".

"CommerceConnector": {
  "ClientId": "PlaceHolderForCommerceEngineConnectClientId"
}

The HealthCheck service, based on the ASP.NET Core, allows the retrieval of health status of a deployed role.

"HealthCheck":  {
    "Enabled":  true,
    "URL":  "/health"
   }

Health check parameters description

Parameter

Description

"Enabled"

Specifies whether the HealthCheck service is enabled.

"URL"

The URL of the application endpoint.