Configuration
VC Platform is an ASP.NET Core application, and it can be configured as described in Configuration in ASP.NET Core.
Configuration Settings
The configuration keys are hierarchical. This structure is most convenient to manage the appsettings.json file:
| Top Configuration Node | Child Node(s) | Default or Sample Value | Description |
|---|---|---|---|
| DatabaseProvider | Required. Database Provider Name. Supported Values: SqlServer (default), MySql, PostgreSql. | ||
| ConnectionStrings | Required. Connection strings for VC Platform and modules. | ||
| VirtoCommerce | E.g., Data Source=(local);Initial Catalog=VirtoCommerce3;Persist Security Info=True;User ID=virto;Password=virto; MultipleActiveResultSets=True;Connect Timeout=30 |
Required. VC Platform system connection string to SQL Server DB. VC modules would revert to this connection string, if specific connection string wasn't defined. | |
| E.g., VirtoCommerce.Catalog | E.g., 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., VirtoCommerce.Catalog module would use VirtoCommerce.Catalog connection string, if it's defined. |
|
| RedisConnectionString | E.g., "localhost" |
StackExchange.Redis Configuration string. Check Redis Configuration for details. | |
| Serilog | Serilog logging settings. | ||
| Using | [ "Serilog.Sinks.Console", "Serilog.Sinks.Debug" ] |
List of assemblies for logging providers in which configuration methods reside | |
| MinimumLevel | Information, Warning, Error, Debug or Trace |
Minimum severity level of log message | |
| ApplicationInsights | AplicationInsights service settings | ||
| ConnectionString | E.g. InstrumentationKey={guid};IngestionEndpoint={url}/;LiveEndpoint={url}/ |
Copy the connection string from the ApplicationInsights admin panel. | |
| SamplingOptions.Processor | E.g. Adaptive |
Chose Adaptive to reduce amount of data to be sent or Fixed to get more details. |
|
| SamplingOptions.Adaptive | E.g. { "MaxTelemetryItemsPerSecond": "5", "InitialSamplingPercentage": "100", "MinSamplingPercentage": "0.1", "MaxSamplingPercentage": "100", "EvaluationInterval": "00:00:15", "SamplingPercentageDecreaseTimeout": "00:02:00", "SamplingPercentageIncreaseTimeout": "00:15:00", "MovingAverageRatio": "0.25" } |
Adaptive processor settings | |
| SamplingOptions.Fixed | E.g. { "SamplingPercentage": 100 } |
Fixed processor settings | |
| VirtoCommerce | VC Platform system settings | ||
| CountriesFilePath | "localization/common/countries.json" |
Local path for countries list. By default, includes all the countries in the world. | |
| CountryRegionsFilePath | "localization/common/countriesRegions.json" |
Local path for countries' regions list. By default, includes the states of USA and regions of Canada. | |
| 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" |
Uploads folder location | |
| SampleDataUrl | E.g., "http://virtocommerce.azureedge.net/sample-data" |
URL to download sample data during initial Platform setup | |
| DiscoveryPath | "./Modules" |
Relative or absolute folder location where Platform will discover installed modules | |
| AllowInsecureHttp | false |
Controls how the OpenID Connect server (ASOS) handles the incoming requests to arriving on non-HTTPS endpoints should be rejected or not. By default, this property is set to false to help mitigate man-in-the-middle attacks. | |
| UseResponseCompression | false |
Enables the Response Compression Middleware for default MIME types and compression providers (Brotli and Gzip). | |
| Hangfire | E.g. "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 } } |
Background processing library (Hangfire) configuration.JobStorageType - current job storage. Supported values: Memory, SqlServer.UseHangfireServer - enable/disable HangFire for this app instance.AutomaticRetryCount - maximum number of automatic retry attempts. WorkerCount - Hangfire subsystem dedicated pool of worker threads size.Queues - Set of the queues Hangfire uses for prioritizing jobs.SqlServerStorageOptions - Hangfire.SqlServer.SqlServerStorageOptions. Check Hangfire's SQL Server Configuration for details. |
|
| Swagger | E.g. "Swagger": { "Enable": false } |
Allows to disable swagger initialization at platform startup to prevent access to the swagger UI and documents. | |
| GraphQLPlayground | E.g. "GraphQLPlayground": { "Enable": false } |
Allows to disable GraphQL Playground initialization at platform startup to prevent access to the GraphQL Playground UI and schemas. | |
| UseAllOfToExtendReferenceSchemas | true |
Extend Rest API reference schemas (using the allOf construct) so that contextual metadata can be applied to all parameter and property schemas. | |
| IncludeOutputNullValues | true |
Include null values when serializing Rest API objects. | |
| FileExtensionsBlackList | E.g. "FileExtensionsBlackList": [".pdf", ".json"] |
This used together with the 'VirtoCommerce.Platform.Security.FileExtensionsBlackList' setting (admin UI) to set extensions of the files prohibited to be uploaded to the server by the platform. 'FileExtensionsBlackList' not accessible from admin UI. Administrator gives additional list of extensions thru UI that mixing with 'FileExtensionsBlackList'. | |
| Assets | Required. Configuration defining how VC Platform works with assets (files). | ||
| Provider | "FileSystem" |
Current assets provider. Supported values: FileSystem, AzureBlobStorage. | |
| FileSystem | E.g., "FileSystem": { "RootPath": "~/assets", "PublicUrl": "http://localhost:10645/assets/" } |
File system based assets provider configuration. Used, if "Provider": "FileSystem" |
|
| AzureBlobStorage | E.g., "AzureBlobStorage": { "ConnectionString": "", "CdnUrl": "" } |
Azure Blob Storage based assets provider configuration. Used, if "Provider": "AzureBlobStorage" |
|
| IdentityOptions | Options to configure the ASP.NET Core Identity system. Check Configure ASP.NET Core Identity for details. | ||
| Password.PasswordHistory | E.g., "PasswordHistory": 4 |
The number of recent user's passwords to check during the password validation. Old password can't be reused for this number of cycles. Value of "0" or not defined - password history is disabled. |
|
| Password.RepeatedResetPasswordTimeLimit | "RepeatedResetPasswordTimeLimit": "0:01:0" | The time limit after which a user can request a password reset. | |
| Password.PasswordChangeByAdminEnabled | true |
Enable or disable for administrators to set passwords for users in the system. | |
| User.MaxPasswordAge | "MaxPasswordAge": "0" | TimeSpan defining max. user password age until the password expires. The user is forced to change the expired password on login to Platform Manager UI. Value of "0" or not defined - password expiration is disabled. |
|
| User.RemindPasswordExpiryInDays | "RemindPasswordExpiryInDays": 7 | Number of days to start showing password expiry warning in Platform Manager UI. Used, if password expiration is enabled. | |
| Lockout.AutoAccountsLockoutJobEnabled | false | Enable auto-lock for accounts whose last login date is older than configured. | |
| Lockout.LockoutMaximumDaysFromLastLogin | 365 | The maximum number of days since the last login to lockout an account. | |
| Lockout.AutoAccountsLockoutJobEnabled | "0 0 * * *" | Cron expression for accounts auto-lock job. | |
| ExternalModules | Configure external source to install modules. | ||
| IncludePrerelease | false |
Show module versions marked as Prerelease if value is true. |
|
| ModulesManifestUrl | E.g., "https://raw.githubusercontent.com/VirtoCommerce/vc-modules/master/modules_v3.json" |
Url to .json file containing modules' manifests. | |
| AuthorizationToken | Authorization token to access ModulesManifestUrl. Added to Authorization header, if specified. | ||
| AutoInstallModuleBundles | ["commerce"] |
Group(s) of modules to install automatically during initial Platform setup. Provide empty array to install none. | |
| Caching | Caching configuration | ||
| Redis | E.g., "Redis": { "ChannelName": "VirtoCommerceChannel", "BusRetryCount": 3 } |
Redis configuration, incl. the message channel to use and number of times to retry. | |
| CacheEnabled | true |
If set to true, cache entries are retained based on expiration settings. Otherwise, cache entries expire immediately.Used, if ConnectionStrings\:RedisConnectionString not specified. |
|
| CacheSlidingExpiration | E.g., "0:15:00" |
Cache entry will expire if it hasn't been accessed in a set amount of time. Used, if CacheAbsoluteExpiration was not defined. | |
| CacheAbsoluteExpiration | E.g., "0:5:00" |
Cache entry will expire after a set amount of time. Used, if RedisConnectionString not specified. | |
| Notifications | Notifications configuration for VirtoCommerce.Notifications module |
||
| Gateway | E.g., "SendGrid" |
Current notification sending gateway. Out of the box implemented and supported values: Smtp, SendGrid. | |
| DefaultSender | E.g., "[email protected]" |
Required. Sender identification used by current notification sending gateway. | |
| Smtp | E.g., "Smtp": { "SmtpServer": "smtp.mydomain.com", "Port": 587, "EnableSsl": true, "Login": "my-login", "Password": "my-password" } |
Smtp gateway configuration. Used, if "Gateway": "Smtp" |
|
| SendGrid | E.g., "SendGrid": { "ApiKey": "my-SendGrid-Api-Key" } |
SendGrid gateway configuration. Used, if "Gateway": "SendGrid" |
|
| Search | Full text search configuration for VirtoCommerce.Search module |
||
| Provider | E.g., "Lucene" |
Required. Current Search Provider. Implemented (in dedicated modules) and supported values: Lucene, AzureSearch, ElasticSearch. | |
| Scope | E.g., "default" |
Required. Scope to use | |
| Lucene | E.g., "Lucene": { "Path": "App_Data/Lucene" } |
Lucene Provider configuration for VirtoCommerce.LuceneSearch module. Used, if "Provider": "Lucene" |
|
| AzureSearch | E.g., "AzureSearch": { "SearchServiceName": "my-ServiceName", "Key": "my-AccessKey" } |
AzureSearch Provider configuration for VirtoCommerce.AzureSearch module. Used, if "Provider": "AzureSearch" |
|
| ElasticSearch | E.g., "ElasticSearch": { "Server": "localhost:9200", "User": "elastic", "Key": "", "EnableHttpCompression": "" } |
ElasticSearch Provider configuration for VirtoCommerce.ElasticSearch module. Used, if "Provider": "ElasticSearch" |
|
| Content | Required. Static content (incl. themes) configuration for VirtoCommerce.Content module |
||
| Provider | "FileSystem" |
Current Content (files) Provider. Supported values: FileSystem, AzureBlobStorage. | |
| FileSystem | E.g., "FileSystem": { "RootPath": "~/cms-content", "PublicUrl": "http://localhost:10645/cms-content/" } |
File system based content provider configuration. This is the default provider, used if AzureBlobStorage is not set as current provider. |
|
| AzureBlobStorage | E.g., "AzureBlobStorage": { "ConnectionString": "", "CdnUrl": "" } |
Azure Blob Storage based content provider configuration. Used, if "Provider": "AzureBlobStorage". |
|
| AzureAd | Used for authentication with Azure Active Directory. Check Enabling authentication with Azure Active Directory for details. | ||
| Enabled | false |
Enables of authentication with Azure Active Directory. Disabled by default. | |
| UsePreferredUsername | false |
If set to true will check the preffered_username in case if the upn claim returns empty. |
|
| UseEmail | false |
If set to true will check the email in case if the upn claim returns empty. |
|
| Priority | 0 | Configures the priortiy of the Azure Active Directory login popup on the Login page. Lower value has a higher prioriy. | |
| ValidateIssuer | Default | Configures the validation schema for issuer. Allowed values: Default - generic OpenID Connect provider, MultitenantAzureAD - for Multitenant Azure AD and Disabled. |
|
| DefaultUserType | Manager | Configures the default user type (role) for SSO. | |
| PasswordLogin | Enables authentication with username and passowrd. | ||
| Enabled | true |
Always enabled by default. Set to false to disable login with username/passowrd. |
|
| Priority | 0 | Configures the priortiy of the password login popup on the Login page. Lower value has a higher prioriy. | |
| LoginPageUI | Used for configuration of the background screen and background pattern of the login page. | ||
| BackgroundUrl | Login page background URI. If set takes priority over the preset. | ||
| PatternUrl | Login page background pattern URI. If set takes priority over the preset. | ||
| Preset | demo |
Login page background preset name. If set searches the preset from the Presets list and applies BackgroundUrl and PatternUrl from it. | |
| Presets | E.g., [{ "Name": "demo", "BackgroundUrl": "images/login_background.png", "PatternUrl": "/images/pattern-demo.svg" }, { "Name": "prod", "BackgroundUrl": "", "PatternUrl": "/images/pattern-live.svg" }] |
A list of background Presets. | |
| Auth | Platfom authencification parameters | ||
| ConnectionString | E.g. Data Source=(local);Initial Catalog=VirtoCommerce3;Persist Security Info=True;User ID=virto;Password=virto; MultipleActiveResultSets=True;Connect Timeout=30 |
This is an optional connection string to the authentification database. In case it is not provided, the security tables will be placed into the main VirtoCommerce database. |
|
| PlatformSettings | Used for platform settings overriding | ||
| Settings | E.g.: "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 } |
Array of settings to be overriden. These settings will be read only in the admin panel. |
Note: Each setting mentioned above is optional unless marked Required.
Hierarchical Keys
-
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, hierarchical keys use
--as a separator. The Azure Key Vault configuration provider automatically replaces--with a:when the secrets are loaded into the app's configuration.
Configuring ElasticSearch on localhost in the appsettings.json file
Configuring the VirtoCommerce connection string and other settings trough environment variables in the docker-compose.yml file
Configuring AzureSearch and other settings trough Application settings in Azure
Check ASP.NET Core Configuration keys and values for more details.
Last update:
October 5, 2023