Last update: April 11, 2024

Appsettings.json

As Virto Commerce Platform is an ASP.NET Core based application, it can be configured as described in this Microsoft article.

Configuration Settings

The configuration keys are hierarchical, and the most convenient way to manage them is to work with the appsettings.json file. The following sections, organized by configuration node and alphabetically, show the general structure of the file, provide defaults, and explain what each key is.

Note

All settings listed below are optional unless marked Required.

ConnectionStrings

These required settings represent connection strings for VC Platform and modules.

Node	Sample value	Description
VirtoCommerce	Data Source=(local);Initial Catalog=VirtoCommerce3;Persist Security Info=True;User ID=virto;Password=virto; MultipleActiveResultSets=True;Connect Timeout=30;TrustServerCertificate=True;	This required setting is used to provide the VC Platform system connection string to the SQL Server database. VC modules would revert to this connection string if no specific connection string is defined.
E.g., VirtoCommerce.Catalog	Data Source=(local);Initial Catalog=VirtoCommerceCatalog;Persist Security Info=True;User ID=virto;Password=virto; MultipleActiveResultSets=True;Connect Timeout=30	Other module-specific connection string(s). E.g., Virto Commerce Catalog module will use the VirtoCommerce.Catalog connection string if it is defined.
RedisConnectionString	"localhost"	StackExchange.Redis Configuration string. Redis Configuration

VirtoCommerce

This configuration node defines the system settings of the VC Platform.

Node	Default or sample value	Description
CountriesFilePath	"localization/common/countries.json"	Local path for the country list, which, by default, includes all countries of the world.
CountryRegionsFilePath	"localization/common/countriesRegions.json"	Local path for state/province list. By default, includes the US states and Canada's provinces.
LicenseActivationUrl	"https://virtocommerce.com/admin/api/licenses/activate/"	VC Platform license activation service URL.
LicenseFilePath	"App_Data/VirtoCommerce.lic"	VC Platform license file location.
LocalUploadFolderPath	"App_Data/Uploads"	The Uploads folder location.
SampleDataUrl	"http://virtocommerce.azureedge.net/sample-data"	URL to download sample data upon the initial Platform setup.
AllowInsecureHttp	true false	Manages how the OpenID Connect server (ASOS) handles the incoming requests: whether those arriving to non-HTTPS endpoints should be rejected or not. By default, this property is set to false to help mitigate the man-in-the-middle attacks.
Hangfire		Background processing library (Hangfire) configuration. JobStorageType: Current job storage. Supported values: Memory, SqlServer. UseHangfireServer: Enables or disables Hangfire for this app instance. AutomaticRetryCount: Maximum number of automatic retry attempts. SqlServerStorageOptions: Hangfire.SqlServer.SqlServerStorageOptions. Hangfire's SQL Server Configuration
Swagger		Allows you to disable Swagger initialization upon platform startup to prevent access to Swagger UI and documents.
GraphQL Playground		Allows you to disable the initialization of the GraphQL Playground at platform startup to prevent access to the GraphQL Playground UI and schemas. By default, the playground is disabled.
FileExtensionsBlackList		This setting is used in conjunction with the VirtoCommerce.Platform.Security.FileExtensionsBlackList setting in the admin UI to define the file extensions that the platform does not permit to be uploaded to the server. The FileExtensionsBlackList is not accessible from the admin UI. An administrator may provide an additional list of extensions through the UI that may be used with FileExtensionsBlackList.

Examples

HangfireSwaggerPlaygroundFileExtensionsBlackList

appsettings.json

"Hangfire": {
"JobStorageType": "Database",
"UseHangfireServer": true,
"AutomaticRetryCount": 1,
"WorkerCount": 11,
"Queues": [
"alpha",
"default"
],
  "SqlServerStorageOptions": {
    "CommandBatchMaxTimeout": "00:05:00",
    "SlidingInvisibilityTimeout": "00:05:00",
    "QueuePollInterval": "00:00:00",
    "UseRecommendedIsolationLevel": true,
    "UsePageLocksOnDequeue": true,
    "DisableGlobalLocks": true,
    "EnableHeavyMigrations": true
  },
  "MySqlStorageOptions": {
    "InvisibilityTimeout": "00:05:00",
    "QueuePollInterval": "00:00:05"
  },
  "PostgreSqlStorageOptions": {
    "InvisibilityTimeout": "00:05:00",
    "QueuePollInterval": "00:00:05",
    "UseRecommendedIsolationLevel": true,
    "UsePageLocksOnDequeue": true,
    "DisableGlobalLocks": true
  }
}

appsettings.json

"Swagger":
{
"Enable": true
}

appsettings.json

"GraphQLPlayground": {
  "Enable": false
}

appsettings.json

"FileExtensionsBlackList": [".pdf", ".json"]

Application Insights

This node adds and customizes the Application Insight section.

Node	Default or sample value	Description
SamplingOptions.Processor	Adaptive Fixed	Lets you choose between two sampling methods: Adaptive sampling: automatically adjusts the volume of telemetry sent from the SDK in your ASP.NET/ASP.NET Core app, and from Azure Functions. Sampling in Application Insights Fixed-rate sampling: reduces the volume of telemetry sent from both applications. Unlike adaptive sampling, it reduces telemetry at a fixed rate controlled by SamplingPercentage setting.
IncludedTypes	Dependency Event Exception PageView Request Trace	A semi-colon delimited list of types to be sampled. The specified types will be sampled. All telemetry of other types will always be transmitted. All types are included by default.
ExcludedTypes	Dependency Event Exception PageView Request Trace	A semi-colon delimited list of types not to be sampled. All telemetry of the specified types is transmitted. The types that aren't specified will be sampled. Empty by default.
EnableSqlCommandTextInstrumentation	true false	For SQL calls, the name of the server and database is always collected and stored as the name of the collected Dependency Telemetry. Another field, called data, can contain the full SQL query text. To opt in to SQL Text collection, set this setting to true.
IgnoreSqlTelemetryOptions		Controls the Application Insights telemetry processor that excludes SQL queries related to dependencies. Any SQL command name or statement that contains a string from the QueryIgnoreSubstrings options will be ignored.

Example

To configure ApplicationInsights:

1. Use current active telemetry configuration which is already initialized in most application types like ASP.NET Core:

   appsettings.json

   {
     "ApplicationInsights": {
       "ConnectionString": "<Copy connection string from Application Insights Resource Overview>"
     }
   }
   

2. Configure Platform AP telemetry behavior inside the VirtoCommerce:ApplicationInsights section:

   appsettings.json

   {
     "VirtoCommerce": {
       "ApplicationInsights": {
         "SamplingOptions": {
           "Processor": "Adaptive",
           "Adaptive": {
             "MaxTelemetryItemsPerSecond": "5",
             "InitialSamplingPercentage": "100",
             "MinSamplingPercentage": "0.1",
             "MaxSamplingPercentage": "100",
             "EvaluationInterval": "00:00:15",
             "SamplingPercentageDecreaseTimeout": "00:02:00",
             "SamplingPercentageIncreaseTimeout": "00:15:00",
             "MovingAverageRatio": "0.25"
           },
           "Fixed": {
             "SamplingPercentage": 90
           },
           "IncludedTypes": "Dependency;Event;Exception;PageView;Request;Trace",
           "ExcludedTypes": ""
         },
         "EnableSqlCommandTextInstrumentation": true,
         "IgnoreSqlTelemetryOptions": {
           "QueryIgnoreSubstrings": [
             "[HangFire].",
             "sp_getapplock",
             "sp_releaseapplock"
           ]
         }
       }
     }
   }
   

Assets

This required node determines how VC Platform will be working with assets, i.e. files.

Node	Default or Sample Value	Description
Provider	"FileSystem"	Current asset provider. Supported values: FileSystem, AzureBlobStorage.
FileSystem		File system-based asset provider configuration. Used when the Provider setting has the value "FileSystem".
FileSystem:RootPath	"~/assets"	The root path where assets are stored in the file system.
FileSystem:PublicUrl	"https://localhost:5001/assets/"	The public Url used to access assets stored in the file system.
AzureBlobStorage		Azure Blob Storage-based asset provider configuration. Used when the Provider setting has the value "AzureBlobStorage".
AzureBlobStorage:ConnectionString		The connection string for Azure Blob Storage.
AzureBlobStorage:CdnUrl		The optional CDN Url for serving assets from Azure Blob Storage.

Examples

FileSystemAzureBlobStorage

appsettings.json

 "Assets": {
    "Provider": "FileSystem",
    "FileSystem": {
      "RootPath": "~/assets",
      "PublicUrl": "http://localhost:5001/assets/"
    }
 }

appsettings.json

 "Assets": {
    "Provider": "AzureBlobStorage",
    "AzureBlobStorage": {
        "ConnectionString": "",
        "CdnUrl": ""
    }
 }  

Auth

This setting determines platfom authencification parameters.

Node	Default or Sample Value	Description
Authority	https://localhost:5051/ <br> https://auth.example.com/	The Url of the authentication server. Leave empty for the mode when authorization and resource server are the same application.
Audience	"resource_server"	The audience for which the token is intended.
PublicCertPath	"./certificates/virtocommerce.crt"	The file path to the public certificate used for token validation.
PrivateKeyPath	"./certificates/virtocommerce.pfx"	The file path to the private key used for token signing.
PrivateKeyPassword	"virto"	The password for accessing the private key (if protected by a password).

Example

appsettings.json

"Auth": {
    "Authority": "",
    "Audience": "resource_server",
    "PublicCertPath": "./certificates/virtocommerce.crt",
    "PrivateKeyPath": "./certificates/virtocommerce.pfx",
    "PrivateKeyPassword": "virto"
}

Authorization

This configuration node defines authorization settings for the system.

Node	Default or Sample Value	Description
ReturnPasswordHash	true false	A boolean setting that determines whether to return the password hash during user authentication. If set to true, the password hash is returned; if set to false, it's not returned.
RefreshTokenLifeTime	"30.00:00:00"	The time span specifying the lifetime of a refresh token. A refresh token is used to obtain a new access token without re-entering the user's credentials. The default is 30 days.
AccessTokenLifeTime	"00:30:00"	The time span specifying the lifetime of an access token. An access token is used to access protected resources. The default is 30 minutes.
LimitedCookiePermissions	"platform:asset:read;platform:export;<br>content:read;platform:asset:create;<br>licensing:issue;export:download"	A semicolon-separated list of permissions that define the limited cookie permissions for the user. These permissions determine what actions the user can perform when using cookies for authentication.
AllowApiAccessForCustomers	true false	A boolean setting that controls whether API access is allowed for customers. If set to false, customers are not allowed to access the API; if set to true, they are granted API access.

Example

appsettings.json

"Authorization": {
  "ReturnPasswordHash": true,
  "RefreshTokenLifeTime": "30.00:00:00",
  "AccessTokenLifeTime": "00:30:00",
  "LimitedCookiePermissions": "platform:asset:read;platform:export;content:read;platform:asset:create;licensing:issue;export:download",
  "AllowApiAccessForCustomers": false
}

AzureAd

This node is used for authentication with Azure Active Directory.

How to enable authentication with Azure Active Directory

Node	Default or Sample Value	Description
Enabled	false	Enables authentication with Azure Active Directory. By default, this value is false, i.e. authentication is disabled.
UsePreferredUsername	false	If set to true, the system will check the preferred_username in case the upn claim returns empty.
Priority	0	Configures the priority of the Azure Active Directory login popup on the Login page. The lowest value means the highest priority.
AuthenticationType	"AzureAD"	Provides the authentication scheme. Must always have the AzureAD value set.
AuthenticationCaption	"Azure Active Directory"	Sets a human-readable caption for the Azure AD authentication provider. Visible on the Sign In page.
ApplicationId	01234567-89ab-cdef-0123-456789abcdef	The ID of the Virto Commerce platform application registered in Azure Active Directory. You can find it in the Azure control panel through Azure Active Directory → App registrations → (platform app) → Application ID.
TenantId	abcdef01-2345-6789-abcd-ef0123456789	The ID of the Azure AD domain that will be used for authentication. You can find it in the Azure control panel through Azure Active Directory → Properties → Directory ID.
AzureAdInstance	https://login.microsoftonline.com/	Url of the Azure AD endpoint used for authentication.
DefaultUserType	"Manager" "Customer"	Default user type for new users created upon first sign-in by Azure AD accounts.
DefaultUserRoles	"Order manager" "Store manager"	Default user roles assigned to new users created upon first sign-in by Azure AD accounts.
MetadataAddress		An optional setting that enables the discovery endpoint for obtaining metadata. Must be set only when your app has custom signing keys.
UsePreferredUsername	true false	Indicates whether to use the preferred_username claim as a fallback scenario in case the UPN claim is not set for getting the username.

Note to the MetadataAddress node

If your app has custom signing keys as a result of using the claim mapping feature, you should append the appid query parameter containing the app ID in order to get a jwks_uri pointing to your app's signing key information. For example, https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contains a jwks_uri of https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Example

Example settings for the AzureAD section:

"AzureAd": {
        "Enabled": true,
        "AuthenticationType": "AzureAD",
        "AuthenticationCaption": "Azure Active Directory",
        "ApplicationId": "b6d8dc6a-6ddd-4497-ad55-d65f91ca7f50",
        "TenantId": "fe353e8f-5f08-43b4-89d1-f4acec93df33",
        "AzureAdInstance": "https://login.microsoftonline.com/",
        "DefaultUserType": "Manager",
        "UsePreferredUsername": false,
        "Priority": 0
    },

Caching

This node manages caching configuration.

Node	Default or sample value	Description
Redis		Redis configuration. Includes the message channel to use and the number of retries.
CacheEnabled	true false	Cache entries are retained based on the expiration settings. Disables caching of application data for the entire application. Used when ConnectionStrings:RedisConnectionString is not specified.
CacheSlidingExpiration	"0:15:00"	The cache entry will expire if it is not accessed for a specified amount of time. Used when CacheAbsoluteExpiration is not defined.
CacheAbsoluteExpiration	"0:5:00"	The cache entry will expire after a specified amount of time. Used when RedisConnectionString is not specified.

Examples

appsettings.json

 "Caching": {
       "CacheEnabled": true, 
       "CacheSlidingExpiration": "0:15:00", 
       //"CacheAbsoluteExpiration": "0:15:00"
    }

appsettings.json

"Redis": {
"ChannelName": "VirtoCommerceChannel",
"BusRetryCount": 3
} 

Content

This required setting is used for static content configuration (including themes) for the VirtoCommerce.Content module.

Node	Default or Sample Value	Description
Provider	"FileSystem"	Current content (file) provider. The supported values are FileSystem and AzureBlobStorage.
FileSystem		File system-based content provider configuration. This is the default provider used unless AzureBlobStorage is set as the current provider.
FileSystem:RootPath	"~/cms-content"	The root path where content files are stored in the file system.
FileSystem:PublicUrl	"https://localhost:5001/cms-content/"	The public URL used to access content files stored in the file system.
AzureBlobStorage		Azure Blob Storage-based content provider configuration. Used when the Provider setting has AzureBlobStorage as the value.
AzureBlobStorage:ConnectionString		The connection string for Azure Blob Storage.
AzureBlobStorage:CdnUrl		The optional CDN (Content Delivery Network) URL for serving content from Azure Blob Storage.
AzureBlobStorage:RootPath	"cms"	The root path within the Azure Blob Storage container where content files are stored.

Examples

FileSystemAzureBlobStorage

appsettings.json

"FileSystem": {
"RootPath": "~/cms-content",
"PublicUrl": "http://localhost:10645/cms-content/"
}  

appsettings.json

"AzureBlobStorage": {
"ConnectionString": "",
"CdnUrl": ""
}

Crud

This configuration node defines settings for the CRUD operations within the system.

Node	Default or sample value	Description
MaxResultWindow	2147483647	The maximum value for the combination of skip and take parameters in search requests. By setting this value to 2147483647, there are no specific limits on the number of records that can be retrieved in a single search request. This effectively allows retrieving a large number of records in a single query.

Example

appsettings.json

"Crud": {
    "MaxResultWindow": 2147483647
}

DataProtection

This configuration node configures lifetimes for security tokens that are issued by platform like password reset.

Node	Default value	Description
DataProtection.TokenLifespan	"1.00:00:00" - Defaults to 1 day	The amount of time a generated token remains valid.

Example

Example settings for the DataProtection section:

appsettings.json

"DataProtection": {
        "TokenLifespan": "24:00:00",        
    },

File Upload

This node configures file upload settings for your application:

Node	Default or sample value	Description
RootPath		The root directory where uploaded files will be stored.
Scopes.Scope		The scope or category of the uploaded files.
Scopes.MaxFileSize	123	The maximum size in bytes allowed for each uploaded file.
Scopes.AllowedExtensions	[".jpg", ".pdf", ".png", ".txt"]	The list of allowed extensions for uploads.

Example

appsettings.json

{
  "FileUpload": {
    "RootPath": "attachments",
    "Scopes": [
      {
        "Scope": "quote-attachments",
        "MaxFileSize": 123,
        "AllowedExtensions": [ ".jpg", ".pdf", ".png", ".txt" ]
      }
    ]
  }
}

FrontendSecurity

This node configures frontend security settings.

Node	Default or sample value	Description
OrganizationMaintainerRole	Organization maintainer	The role that defines permissions for organization maintainers.

Example

appsettings.json

"FrontendSecurity": {
    "OrganizationMaintainerRole": "Organization maintainer"
}

IdentityOptions

This configuration node configures the ASP.NET Core Identity system.

Identity Configuration

Node	Default or Sample Value	Description
Password		Configuration settings related to user password requirements.
Password:RequiredLength	8	The minimum required length for user passwords.
Password:RequireDigit	false	Indicates whether a digit is required in user passwords.
Password:RequireNonAlphanumeric	false	Indicates whether a non-alphanumeric character is required in user passwords.
Password:RepeatedResetPasswordTimeLimit	"0:01:0"	The time span within which a user cannot repeatedly reset their password.
User		Configuration settings related to user accounts.
User:MaxPasswordAge	90	The maximum age (in days) a user can keep the same password before being required to change it.
User:RequireUniqueEmail	true	Indicates whether each user must have a unique email address.
User:RemindPasswordExpiryInDay	7	The number of days before the password expiration date when the system will start reminding users to change their password.
Lockout		Configuration settings related to account lockout.
Lockout:DefaultLockoutTimeSpan	"0:15:0"	The default duration for which an account is locked out after the specified number of unsuccessful login attempts.

Example

appsettings.json

"IdentityOptions": {
    "Password": {
      "RequiredLength": 8,
      "RequireDigit": false,
      "RequireNonAlphanumeric": false,
      "RepeatedResetPasswordTimeLimit": "0:01:0"
    },
    "User": {
      "MaxPasswordAge": 90,
      "RequireUniqueEmail": true,
      "RemindPasswordExpiryInDay": 7
    },
    "Lockout": {
      "DefaultLockoutTimeSpan": "0:15:0"
    }

LoginPageUI

This node configures background screen and background pattern of the Login page.

Node	Default or Sample Value	Description
BackgroundUrl		Url for the background image of the login page. If empty, no background image is displayed.
PatternUrl		Url for the pattern image of the login page. If empty, no pattern image is displayed.
Preset		The currently selected preset for the login page. If empty, no preset is applied.
Presets		An array of preset configurations for the login page, allowing different visual settings for different scenarios.
Presets:Name	"demo", "prod", etc.	The name of the preset. Used for identification and selection of the preset.
Presets:BackgroundUrl		Url for the background image specific to the preset. If empty, the default background is used.
Presets:PatternUrl	"/images/pattern-demo.svg", "/images/pattern-live.svg", etc.	Url for the pattern image specific to the preset. If empty, the default pattern is used.

Example

appsettings.json

    "LoginPageUI": {
        "BackgroundUrl": "",
        "PatternUrl": "",
        "Preset": "",
        "Presets": [
          {
            "Name": "demo",
            "BackgroundUrl": "",
            "PatternUrl": "/images/pattern-demo.svg"
          },
          {
            "Name": "prod",
            "BackgroundUrl": "",
            "PatternUrl": "/images/pattern-live.svg"
          }
        ]
      }

Modularity

This node configures external sources, from which modules are being installed and discovered.

Node	Default or sample value	Description
IncludePrerelease	true false	Shows module versions marked as Prerelease if value is true.
DiscoveryPath	"./Modules"	Relative or absolute folder location where the platform will discover the installed modules from.
ModulesManifestUrl	"https://raw.githubusercontent.com/VirtoCommerce/vc-modules/master/modules_v3.json"	Url to the .json file that contains module manifests.
AuthorizationToken		The authorization token to access ModulesManifestUrl, added to the Authorization header, if specified.
AutoInstallModuleBundles	"commerce"	Group(s) of modules to install automatically during the initial Platform setup. If you do not need to install anything here, provide an empty array.

Example

appsettings.json

  "ExternalModules": {
    "IncludePrerelease": false,
    "ModulesManifestUrl": "https://raw.githubusercontent.com/VirtoCommerce/vc-modules/master/modules_v3.json",
    "AuthorizationToken": "",
    "AutoInstallModuleBundles": [
      "commerce"
    ]
  }

Notifications

This node enables notification configuration for the VirtoCommerce.Notifications module.

Node	Default or Sample Value	Description
Gateway	"Smtp" "SendGrid"	The current notification sending gateway. The out-of-the-box implemented and supported values are Smtp, SendGrid.
DefaultSender	"[email protected]"	This required setting provides sender identification used by the current notification sending gateway.
Smtp		SMTP gateway configuration. Used if the Gateway setting has the Smtp value.
Smtp:SmtpServer	"smtp.gmail.com"	The SMTP server address for sending emails.
Smtp:Port	587	The port number to use when connecting to the SMTP server.
Smtp:Login		The login (username) for authenticating to the SMTP server.
Smtp:Password		The password for authenticating to the SMTP server.
Smtp:ForceSslTls	false	If set to true, forces the usage of SSL/TLS when connecting to the SMTP server.
SendGrid		SendGrid gateway configuration. Used when the Gateway setting has the SendGrid value.
SendGrid:ApiKey		The API key for authenticating to the SendGrid service.
Notifications:DiscoveryPath	Templates	Relative folder path in the local file system that will be used to discover notification template files during notification rendering.
Notifications:FallbackDiscoveryPath		Alternative relative folder path in the local file system that will be used to discover alternative template files during notification rendering. Templates found through this path will be used as a backup, in case the templates defined in the Notifications:DiscoveryPath setting are not found.

Example

appsettings.json

"Notifications": {
    "Gateway": "Smtp",
    "DefaultSender": "[email protected]",
    "Smtp": {
      "SmtpServer": "smtp.gmail.com",
      "Port": 587,
      "Login": "",
      "Password": "",
      "ForceSslTls": false
    },
    "SendGrid": {
      "ApiKey": ""
    },
    "Notifications:DiscoveryPath": "Templates",
    "Notifications:FallbackDiscoveryPath": ""
}

PasswordLogin

This node enables authentication with username and password.

Node	Default or sample value	Description
Enabled	true falsee	Always enabled by default. Setting to false will disable logging in with username and password.
Priority	0	Configures the priority of the password login popup on the Login page. The lowest value means the highest priority.

PlatformSettings

This node is used for Used for platform settings overriding.

Node	Default or sample value	Description
Settings		Array of settings to be overriden. These settings will be read only in the admin panel.

Example

appsettings.json

"Settings":{
  "ItHasValues": true,
  "Value": 20000,
  "RestartRequired": false,
  "ModuleId": "VirtoCommerce.Sitemaps",
  "GroupName": "Sitemap|General",
  "Name": "Sitemap.RecordsLimitPerFile",
  "IsRequired": false,
  "IsHidden": false,
  "ValueType": 8,
  "DefaultValue": 10000,
  "IsDictionary": false
}

Search

This node configures full text search for the VirtoCommerce.Search module.

Node	Default or sample value	Description
Provider	"Lucene"	This required setting specifies the current search provider. The supported values are: ElasticSearch ElasticAppSearch ElasticSearch8 Lucene AzureSearch AlgoliaSearch
Scope	"default"	This setting determines the scope to use and is required.

Examples

Configure the search provider modules and activate them in the Search.Provider section, providing connection parameters as specified in the module documentation:

appsettings.json

"Search": {
        "Provider": "ElasticAppSearch",
        "Scope": "default",
        "ElasticAppSearch": {
      "Endpoint": "https://localhost:3002",
            "PrivateApiKey": "private-key",
          "KibanaBaseUrl": "https://localhost:5601"
        }
    }

Tailor the search provider per document type to optimize search performance and functionality:

appsettings.json

{
  "Search": {
    "Provider": "ElasticAppSearch",
    "DocumentScopes": [
      {
        "DocumentType": "Category",
        "Provider": "ElasticSearch8"
      }
    ]
  }
}

ElasticSearch

This node configures the Elastic Search provider:

Node	Default or Sample Value	Description
Search.Provider	"ElasticSearch"	Specifies the search provider name, which must be set to "ElasticSearch".
Search.Scope	"default"	Specifies the common name (prefix) for all indexes. Each document type is stored in a separate index, and the full index name is scope-{documenttype}. This allows one search service to serve multiple indexes. The key is optional. Its default value is default.
Search.ElasticSearch.Server		Specifies the network address and port of the Elasticsearch server.
Search.ElasticSearch.User	"elastic"	Specifies the username for either the Elastic Cloud cluster or private Elasticsearch server.
Search.ElasticSearch.Key		(Optional) Specifies the password for either the Elastic Cloud cluster or private Elasticsearch server.
Search.ElasticSearch.EnableCompatibilityMode	false	(Optional) Set this to "true" to use Elasticsearch v8.x or "false" (default) for earlier versions.
Search.ElasticSearch.EnableHttpCompression	false	(Optional) Set this to "true" to enable gzip compressed requests and responses or "false" (default) to disable compression.
Search.ElasticSearch.CertificateFingerprint		During development, you can provide the server certificate fingerprint. When present, it is used to validate the certificate sent by the server. The fingerprint is expected to be the hex string representing the SHA256 public key fingerprint.

Examples

Elastic Cloud v8.xElasticsearch v8.xElastic Cloud v7.xElasticsearch v7.xAmazon OpenSearch Service

Note

Virto Commerce has its native Elasticsearch 8.x module. The current module works with Elasticsearch 8.x in compatibility mode.

Enable the compatibility mode for Elastic Cloud v8.x:

appsettings.json

"Search": {
    "Provider": "ElasticSearch",
    "Scope": "default",
    "ElasticSearch": {
        "EnableCompatibilityMode": "true",
        "Server": "https://4fe3ad462de203c52b358ff2cc6fe9cc.europe-west1.gcp.cloud.es.io:9243",
        "User": "elastic",
        "Key": "{SECRET_KEY}"
    }
}

Configure Elasticsearch v8.x without security features enabled:

appsettings.json

"Search": {
    "Provider": "ElasticSearch",
    "Scope": "default",
    "ElasticSearch": {
        "EnableCompatibilityMode": "true",
        "Server": "https://localhost:9200"
    }
}

Configure Elasticsearch v8.x with ApiKey authorization:

appsettings.json

"Search": {
    "Provider": "ElasticSearch",
    "Scope": "default",
    "ElasticSearch": {
        "EnableCompatibilityMode": "true",
        "Server": "https://localhost:9200",
        "User": "{USER_NAME}",
        "Key": "{SECRET_KEY}"
    }
}

Configure Elastic Cloud v7.x as follows:

appsettings.json

"Search": {
    "Provider": "ElasticSearch",
    "Scope": "default",
    "ElasticSearch": {
        "Server": "https://4fe3ad462de203c52b358ff2cc6fe9cc.europe-west1.gcp.cloud.es.io:9243",
        "User": "elastic",
        "Key": "{SECRET_KEY}"
    }
}

Configure Elasticsearch v7.x without security features enabled:

appsettings.json

"Search": {
    "Provider": "ElasticSearch",
    "Scope": "default",
    "ElasticSearch": {
        "Server": "https://localhost:9200"
    }
}

Configure Elasticsearch v7.x with ApiKey authorization:

appsettings.json

"Search": {
    "Provider": "ElasticSearch",
    "Scope": "default",
    "ElasticSearch": {
        "Server": "https://localhost:9200",
        "User": "{USER_NAME}",
        "Key": "{SECRET_KEY}"
    }
}

Configure Amazon OpenSearch Service:

appsettings.json

"Search": {
    "Provider": "ElasticSearch",
    "Scope": "default",
    "ElasticSearch": {
        "Server": "https://{master-user}:{master-user-password}@search-test-vc-c74km3tiav64fiimnisw3ghpd4.us-west-1.es.amazonaws.com"
    }
}

Elastic App Search

This node configures the Elastic App Search provider:

Node	Default or Sample Value	Description
Search.Provider	"ElasticAppSearch"	Name of the search provider, which must be set to ElasticAppSearch
Search.Scope	"default"	(Optional) Specifies the common name (prefix) for all indexes. Each document type is stored in a separate index, and the full index name is scope-{documenttype}. This allows one search service to serve multiple indexes. Its default value is set to default.
Search.ElasticAppSearch.Endpoint		Network address and port of the ElasticAppSearch server.
Search.ElasticAppSearch.PrivateApiKey		API access key that can read and write against all available API endpoints. Prefixed with private-.
Search.ElasticAppSearch.KibanaBaseUrl		Kibana base URL for accessing the Kibana Dashboard from the application menu.
Search.ElasticAppSearch.KibanaPath		Path to the App Search engine in the Kibana Dashboard. Default value is /app/enterprise_search/app_search/engines/.

Note

Endpoint and API key can be managed in the Credential menu within the App Search Dashboard panel.

Examples

appsettings.json

    "Search": {
        "Provider": "ElasticAppSearch",
        "Scope": "default",
        "ElasticAppSearch": {
                "Endpoint": "https://localhost:3002",
            "PrivateApiKey": "private-key",
          "KibanaBaseUrl": "https://localhost:5601"
        }
    }

Dynamic Boosting

The Elastic App Search provider combines static boosting from the Search Relevance Tuning panel with dynamic boosting that can be passed at runtime.

Dynamic Boosting supports both Value Boost and Functional Boosting.

Define Boost Presets as follows:

appsettings.json

    "Search": {
        "Provider": "ElasticAppSearch",
        "Scope": "default",
        "ElasticAppSearch": {
          "Endpoint": "https://localhost:3002",
          "PrivateApiKey": "private-key",
          "KibanaBaseUrl": "https://localhost:5601",

          "BoostPresets": [
            {
              "Name": "High",
              "Type": "value",
              "Operation": "add",
              "Factor": 5,
              "IsDefault": true
            },
            {
              "Name": "Medium",
              "Type": "value",
              "Operation": "add",
              "Factor": 3
            },
            {
              "Name": "LOw",
              "Type": "value",
              "Operation": "add",
              "Factor": 3
            }
          ]
        }
      }

Pass SearchBoost with Search Request:

appsettings.json

searchRequest.Boosts = [new SearchBoost
      {
                FieldName = "brand",
                Value = "Apple",
                Preset = "Medium",
        }];

Elastic Search 8

This node configures the Elastic Search 8 provider:

Node	Default or Sample Value	Description
Search.Provider	"ElasticSearch8"	Specifies the search provider name, which must be set to "ElasticSearch8".
Search.Scope	"default"	(Optional) Specifies the common name (prefix) for all indexes. Each document type is stored in a separate index, and the full index name is scope-{documenttype}. This allows one search service to serve multiple indexes. Its default value is default.
Search.ElasticSearch8.Server		Specifies the network address and the port of the Elasticsearch8 server.
Search.ElasticSearch8.User	"elastic"	Specifies the username for the Elasticsearch8 server.
Search.ElasticSearch8.Key		(Optional) Specifies the password for the Elasticsearch8 server.
Search.ElasticSearch8.CertificateFingerprint		(Optional) During development, you can provide the server certificate fingerprint. When present, it is used to validate the certificate sent by the server. The fingerprint is expected to be the hex string representing the SHA256 public key fingerprint.

Examples

Configure local v8.x server:

appsettings.json

"Search": {
    "Provider": "ElasticSearch8",
    "Scope": "default",
    "ElasticSearch8": {
        "Server": "https://localhost:9200",
        "User": "elastic",
        "Key": "{PASSWORD}"
    }
}

Configure Elastic Cloud v8.x:

appsettings.json

"Search": {
    "Provider": "ElasticSearch8",
    "Scope": "default",
    "ElasticSearch8": {
        "Server": "https://vcdemo.es.eastus2.azure.elastic-cloud.com",
        "User": "elastic",
        "Key": "{SECRET_KEY}"
    }
}

Lucene

This node configures the Lucene search provider:

Node	Default or Sample Value	Description
Search.Provider	"Lucene"	Name of the search provider, which must be set to Lucene.
Search.Lucene.Path		A virtual or physical path to the root directory where indexed documents are stored.
Search.Scope	"default"	(Optional) Specifies the common name (prefix) for all indexes. Each document type is stored in a separate index, and the full index name is scope-{documenttype}. This allows one search service to serve multiple indexes.

Example

appsettings.json

"Search": {
    "Provider": "Lucene",
    "Scope": "default",
    "Lucene": {
        "Path": "/path/to/lucene/indexes"
    }
}

Azure Search

This node configures the Azure Search provider:

Node	Default or Sample Value	Description
Search.Provider	"AzureSearch"	Name of the search provider, which must be set to AzureSearch.
Search.AzureSearch.SearchServiceName		The name of the search service instance in your Azure account. Example: SERVICENAME.search.windows.net.
Search.AzureSearch.AccessKey		The primary or secondary admin key for this search service.
Search.AzureSearch.QueryParserType	Simple Full	Type of Query Languages. Simple (default) or Full.
Search.Scope	"default"	(Optional) Specifies the common name (prefix) for all indexes. Each document type is stored in a separate index, and the full index name is scope-{documenttype}. This allows one search service to serve multiple indexes.

Example

appsettings.json

"Search": {
    "Provider": "AzureSearch",
    "Scope": "default",
    "AzureSearch": {
        "SearchServiceName": "YOUR_SEARCH_SERVICE_NAME.search.windows.net",
        "AccessKey": "YOUR_SEARCH_SERVICE_ACCESS_KEY",
        "QueryParserType": "Simple"
    }
}

Algolia

This node configures the Algolia search provider:

Node	Default or Sample Value	Description
Search.Provider	"AlgoliaSearch"	Name of the search provider, which must be set to AlgoliaSearch.
Search.AlgoliaSearch.ApiId		The API id for Algolia server.
Search.AlgoliaSearch.ApiKey		The API key for either Algolia server.

Example

appsettings.json

"AlgoliaSearch": {
    "AppId": "API_ID",
    "ApiKey": "API_KEY"
}

Serilog

This node configures the Serilog logging library, allowing customization of logging providers, minimum severity levels, and other logging-related settings.

Node	Default or sample value	Description
Using	"Serilog.Sinks.Console" "Serilog.Sinks.Debug"	List of assemblies for logging providers in which configuration methods reside.
MinimumLevel	Information Warning Error Debug Trace	Minimum severity level of log messages.
WriteTo	"Console" "Debug"	Specifies the sinks to which log events will be written.
Enrich	"FromLogContext"	List of enrichers that will add additional properties to log events.

Example

appsettings.json

"Serilog": {
    "Using": [
      "Serilog.Sinks.Console",
      "Serilog.Sinks.Debug"
    ],
    "MinimumLevel": {
      "Default": "Information"
    },
    "WriteTo": [
      "Console",
      "Debug"
    ],
    "Enrich": [
      "FromLogContext"
    ]
}

Skyflow

This node configures the Skyflow payment processing module, facilitating secure handling of payment data and integration with various payment service providers.

Node	Default or Sample Value	Description
tokenURI	"https://manage.skyflowapis.com/v1/auth/sa/oauth/token"	The URI for obtaining authentication tokens from the Skyflow API.
clientSDK:clientID	"b7eeb4df0007492cbef5bd1000000000"	The client ID for authentication with the Skyflow client SDK.
clientSDK:keyID	"i24bb5b53c114f1c9531db69000000000"	The key ID for authentication with the Skyflow client SDK.
clientSDK:privateKey		The private key for authentication with the Skyflow client SDK.
Connections	"Default"	Configuration details for establishing connections with payment service providers.
DefaultConnection:clientID	"ca2836c68afa4546b6e09b000000000"	The client ID for the default connection to Skyflow APIs.
DefaultConnection:keyID	"hd75811c6f4b4ed4835eda00000000"	The key ID for the default connection to Skyflow APIs.
DefaultConnection:privateKey		The private key for the default connection to Skyflow APIs.
DefaultConnection:connectionUrl		The connection URL for the default connection to Skyflow APIs.
DefaultConnection:name		The name of the default connection.
DefaultConnection:transactionKey		The transaction key for the default connection to Skyflow APIs.

Example

appsettings.json

{
  "Payments": {
    "Skyflow": {
      "tokenURI": "https://manage.skyflowapis.com/v1/auth/sa/oauth/token",
      "clientSDK": {
        "clientID": "b7eeb4df0007492cbef5bd1000000000",
        "keyID": "i24bb5b53c114f1c9531db69000000000",
        "privateKey": "-----BEGIN PRIVATE KEY---TODO---END PRIVATE KEY-----"
      },
      "Connections": {
        "Default": {
          "clientID": "ca2836c68afa4546b6e09b000000000",
          "keyID": "hd75811c6f4b4ed4835eda00000000",
          "privateKey": "-----BEGIN PRIVATE KEY---TODO---END PRIVATE KEY-----"
        }
      },
      "DefaultConnection": {
        "connectionUrl": "https://ebfc00000000.gateway.skyflowapis.com/v1/gateway/outboundRoutes/gfb5ce07e91340efac348a2df00000000/xml/v1/request.api",
        "name": "TODO:YOURID",
        "transactionKey": "TODO:YOUR_TRANSACTION_KEY"
      }
    }
  }
}

Tax

This setting is used to configure tax providers.

Node	Default value	Description
FixedRateTaxProvider	true false	Determines whether the FixedRateTaxProvider is enabled or disabled. When set to false, the FixedRateTaxProvider is not active, and tax calculations will not be performed using this provider. When set to true the FixedRateTaxProvider will be enabled, allowing the platform to use fixed-rate tax calculations.

Example

appsettings.json

{
"FixedRateTaxProvider": {"Enabled": false}
}

Hierarchic keys and separators

When working with keys, one should follow these rules:

• Within the Configuration API, a colon separator (:) works on all platforms.
• In environment variables, a colon separator may not work on all platforms. A double underscore, __, is supported by all platforms and is automatically converted into a colon :.
• In Azure Key Vault, hierarchic keys use double hyphen -- as a separator. The Azure Key Vault configuration provider automatically replaces -- with a : when the secrets are loaded into the app configuration.

Configuring ElasticSearch on localhost in the appsettings.json file

Configuring VirtoCommerce ConnectionString and other settings through environment variables in the docker-compose.yml file

Configuring AzureSearch and other settings trough the Application settings in Azure

ASP.NET configuration guide