Skip to content

Configuration Parameters ​

MARS configuration is a name/value store (TMARSParameters) available at the engine and application levels. Values are typically loaded from an .ini file next to the executable with FEngine.Parameters.LoadFromIniFile, and can be read in code or injected with [EngineParam] / [ApplicationParam].

ini
[Engine]
Port=8080
ThreadPoolSize=75
BasePath=/rest

[DefaultApp]
JWT.Secret=please-change-me
JWT.Duration=1

When AddApplication runs, the engine copies the matching .ini section (by application name) into the application's parameters.

Which .ini file is used ​

LoadFromIniFile (and SaveToIniFile / IniFileExists) accept an explicit file name. Called without one, they resolve it in this order:

  1. the -configFileName <path> command-line switch, if present — handy to run the same binary against different configurations (dev, staging, service instances);
  2. otherwise the module name with the extension changed to .ini — MyServer.exe → MyServer.ini, an ISAPI DLL → <dllname>.ini.

Parameters.GetFileName returns the path that would be used, with the same rules, which is what to log or display when a server starts up with unexpected settings:

pascal
if not FEngine.Parameters.IniFileExists then
  Writeln('No configuration file at ' + FEngine.Parameters.GetFileName);

Shared configuration: [Include] ​

Several servers often share most of their configuration (JWT settings, logging, database connections) and differ in a few values (port, secret, application specific settings). Put the common values in a base file and include it in the .ini of each server with an [Include] section: the call to LoadFromIniFile in Server.Ignition stays the same.

text
C:\Servers\
├─ BaseConfiguration.ini
├─ Orders\
│  ├─ OrdersServer.exe
│  └─ OrdersServer.ini
└─ Invoices\
   ├─ InvoicesServer.exe
   └─ InvoicesServer.ini

C:\Servers\BaseConfiguration.ini, shared:

ini
[DefaultEngine]
Port=8080
ThreadPoolSize=50
JSONLogging.Enabled=true

[DefaultApp]
JWT.Issuer=MyCompany
JWT.Duration=8
JWT.Secret=base-secret-replaced-by-each-server

C:\Servers\Orders\OrdersServer.ini:

ini
[Include]
Base=..\BaseConfiguration.ini

[DefaultEngine]
Port=8081

[DefaultApp]
JWT.Secret=a-long-random-value-for-orders
Orders.MaxItems=100

The parameters of OrdersServer are the sum of the two files, the including file winning:

ParameterValueFrom
Port8081OrdersServer.ini
ThreadPoolSize50BaseConfiguration.ini
JSONLogging.EnabledtrueBaseConfiguration.ini
DefaultApp.JWT.IssuerMyCompanyBaseConfiguration.ini
DefaultApp.JWT.Duration8BaseConfiguration.ini
DefaultApp.JWT.Secreta-long-random-value-for-ordersOrdersServer.ini
DefaultApp.Orders.MaxItems100OrdersServer.ini

The MARSTemplate, MARSTemplateDCS and MARSTemplateRoutes templates, and so the projects created with MARSCmd, use this layout: bin\Server.ini holds the settings, and each server flavor has a small .ini named after its executable that includes it.

The rules:

  • each value of [Include] is a file to load; the names (Base above) are free and only identify the line. Relative paths are relative to the folder of the file containing the [Include] section, not to the current folder;
  • included files are loaded first, in the order they are listed, then the values of the including file: the including file wins, and a later include wins over an earlier one;
  • an included file can have its own [Include] section, e.g. BaseConfiguration.ini could include a CompanyDefaults.ini. A file including itself, directly or through other files, raises EMARSParametersIniFileException;
  • an included file that does not exist raises EMARSParametersIniFileException (a missing main file, instead, still gives empty parameters, as before);
  • [Include] is not a parameters section; an included file cannot remove a value, only replace it (Key= sets an empty value);
  • SaveToIniFile writes all the parameters to a single file, without [Include].

Names are case insensitive in .ini files ​

Like the .ini files themselves, the parameters read from them ignore case: jwt.secret in the file is found as JWT.Secret in code, and Feature.X in a base file and feature.x in the including file are the same parameter (the first spelling is kept). Parameters read from JSON (LoadFromJSON) keep matching the exact case.

Values from .ini files are typed ​

A value read from an .ini file becomes an integer, a float, a boolean or a date when it looks like one (Port=8080 is read with .AsInteger), else a string. Their text is kept too: ByNameAsText returns it as written, whatever the type (Version=1.10 gives '1.10', not the Double 1.1), and converts the values set in code or read from JSON. Use it for values that are text even when they look like numbers (versions, codes, names): .AsString on such a value raises EInvalidCast. The OpenAPI.info.* parameters are read this way.

pascal
var LVersion := FEngine.Parameters.ByNameAsText('OpenAPI.info.version', '0.1.0');

Engine parameters ​

ParameterTypeDefaultPurpose
PortInteger8080HTTP listening port.
PortSSLInteger0HTTPS port (0 = disabled), for the Indy and DCS servers. See HTTPS.
DCS.SSL.CertFilestringlocalhost.crtDCS server: certificate (PEM, may hold the chain); relative to the executable folder.
DCS.SSL.KeyFilestringlocalhost.keyDCS server: private key (PEM); relative to the executable folder.
Indy.SSL.CertFile, Indy.SSL.KeyFile, Indy.SSL.RootCertFilestringlocalhost.crt, localhost.key, localhost.pemIndy server: certificate, key and root certificate.
Indy.SSL.Version, Indy.SSL.ModestringsslvTLSv1_2, sslmServerIndy server: TLS version and mode.
Indy.KeepAliveBooleanfalseIndy server: HTTP keep-alive (without it every request opens a new connection, and a TLS handshake with HTTPS). Each open connection holds a thread of the pool: ThreadPoolSize is also the maximum number of connections. true in the MARSTemplate projects. The DCS server always supports keep-alive.
ThreadPoolSizeInteger75Worker threads (size for concurrent requests, incl. open SSE streams).
BasePathstring/restRoot path stripped from every URL before application matching.
RateLimit.RequestsInteger0Requests allowed to each client per RateLimit.Window (0: no limit); over the limit, 429 with Retry-After. See Engine ▸ Rate limiting.
RateLimit.WindowInteger60The window of RateLimit.Requests, in seconds.
RateLimit.ClientIPHeaderstring(empty)Behind a trusted reverse proxy: the header with the address of the client (i.e. X-Forwarded-For, its first address); empty: the remote IP of the connection.
COM.InitializeBooleanfalseWindows: COM initialized (multithreaded apartment) for each request, in the thread that serves it, and uninitialized after it: for COM based components such as ADO, OLE DB providers (i.e. UniDAC or SDAC with SQL Server through OLE DB), MSXML, without CoInitialize in every method.

OpenAPI.Header.<name> (string, [required|optional;]description): a request header of every operation in the OpenAPI document, for the documentation only, i.e. an API key checked by a middleware; also per application (DefaultApp.OpenAPI.Header.<name>, which wins). See OpenAPI ▸ Request headers.

CORS-related parameters (when CORS is enabled) include CORS.Origin, CORS.Methods, CORS.Headers. See Engine ▸ CORS.

JWT / authentication parameters (per application) ​

Read by the token resource and JWT backends:

ParameterDefaultPurpose
JWT.Secret—HMAC signing secret. Missing or equal to the public default: see JWT.AllowDefaultSecret.
JWT.AllowDefaultSecretfalseKnowingly use the public default secret. Otherwise a DEBUG build generates a random per-process secret and a RELEASE build raises (TMARSToken.DefaultSecretPolicy).
JWT.KeyId—Id of JWT.Secret, written as kid in the header of new tokens. See Key rotation.
JWT.PreviousSecret.<kid>—A retired key, accepted only to verify tokens whose kid is <kid>.
JWT.PreviousSecret—A retired key for tokens without kid (issued before JWT.KeyId was set).
JWT.AlgorithmHS256Signature algorithm: HS256 (a shared secret), or RS256, PS256, ES256 (a key pair). See Asymmetric algorithms.
JWT.PrivateKey—With an asymmetric algorithm, the key that signs new tokens: a PEM file (relative to the folder of the executable) or a PEM text in one line (\n for the line breaks).
JWT.PublicKey—With an asymmetric algorithm, the key that verifies tokens (same forms).
JWT.PreviousPublicKey.<kid>, JWT.PreviousPublicKey—Retired public keys, as JWT.PreviousSecret.
JWT.IssuerMARS-Curiosityiss claim.
JWT.Duration1Token lifetime in days.
JWT.Duration.InMinutes—Lifetime in minutes (alternative).
JWT.Duration.InSeconds—Lifetime in seconds (alternative).
JWT.CookieEnabledtrueAlso deliver/accept the token as a cookie.
JWT.CookieNameaccess_tokenCookie name.
JWT.CookieDomain—Cookie domain.
JWT.CookiePath—Cookie path.
JWT.CookieSecurefalseMark the cookie Secure (HTTPS only).
JWT.CookieSameSiteLaxSameSite attribute of the cookie: Lax, Strict, None (makes the cookie Secure too) or Unspecified (not written). See The token cookie.
JWT.AuthenticationFailedStatus403HTTP status of a request whose token is missing, not valid or expired. Set it to 401 to tell it apart from the 403 of a token without the required role. See How clients see denials.

Set JWT.Secret

The default secret ships in the public source and is never used unless you opt in with JWT.AllowDefaultSecret. Set a strong, unique secret per deployment; MARSCmd writes a random one into the .ini files of every project it creates.

JSON parameters (per application) ​

ParameterTypeDefaultPurpose
JSON.EscapeNonASCIIBooleanTrueEscape the characters above 127 as \uXXXX in JSON responses. False writes them as they are (Unicode response encodings only). See Non-ASCII characters.
JSON.SkipEmptyValuesBoolean—Shortcut: sets all the JSON.Skip* options below.
JSON.SkipEmptyStringsBooleanTrueOmit "" values.
JSON.SkipEmptyNumbersBooleanFalseOmit zero numbers.
JSON.SkipEmptyBooleansBooleanTrueOmit false values.
JSON.SkipEmptyObjectsBooleanTrueOmit empty {}.
JSON.SkipEmptyArraysBooleanTrueOmit empty [].
JSON.SkipNullValuesBooleanTrueOmit null.
JSON.DateIsUTCBooleanTrue only on a UTC+0 machineWrite and read TDateTime values as UTC.
JSON.ZeroDateAsEmptyBooleanTrueWrite a zero date (0, 1899-12-30) as "", "no date". False writes it as a date.
JSON.TDateAsDateBooleanTrueWrite TDate values as calendar dates ("2026-10-19", OpenAPI format: date). False writes them with the time and the offset, as MARS 2.0.2 and earlier.
JSON.UseDisplayFormatForNumericFieldsBooleanFalseUse the display format of dataset numeric fields.

Defaults are those of DefaultMARSJSONSerializationOptions; resource and method attributes win over these parameters. See Serialization options.

Content negotiation parameters (per application) ​

ParameterTypeDefaultPurpose
Produces.Defaultstring (media types, comma separated)—What the endpoints without [Produces] produce, as an implicit [Produces] on each of them (negotiation, /metadata, OpenAPI). application/json makes strings and numbers JSON too. See A default for the application.

Routes parameters (per application) ​

NameTypeDefaultDescription
Middlewares.ResourcesBooleanTMARSRouteTable.DefaultMiddlewaresOnResources (False)The middlewares of the application (MARSRoutesOf(App).Use) also wrap the methods of the resources. See Middlewares around resource methods.

Logging parameters ​

Read by the request/response loggers (engine section). Each logger is inert until both its unit is in the server's uses clause and its Enabled flag is set.

ParameterTypeDefaultPurpose
JSONLogging.EnabledBooleanFalseEnable the NDJSON file logger (MARS.Utils.ReqRespLogger.JSON).
MemoryLogging.EnabledBooleanFalseEnable the in-memory logger (MARS.Utils.ReqRespLogger.Memory); it retains whole requests and responses in clear text.
JSONLogging.BuiltInEntriesBooleanTrueWrite the built-in in/out/error lines of the JSON logger; False leaves the file to the entries your code writes with Log<T>.
JSONLogging.Folderstring<exe folder>\logsTarget directory (created if missing).
JSONLogging.FileNamestringmars-reqresp.logBase log file name.
JSONLogging.DailyRotationBooleanTrueInsert the date before the extension for daily rotation.
JSONLogging.RetentionDaysInteger0With daily rotation, delete the log files dated more than this many days ago when a new file is opened; 0 keeps every file.
CodeSiteLogging.EnabledBooleanFalseEnable CodeSite output (MARS.Utils.ReqRespLogger.CodeSite).

See Request/Response Logging for the log line format and a Grafana Alloy ingestion example.

Data access parameters ​

Connection definitions live in a section of the engine parameters, loaded by the ignition with LoadConnectionDefs:

KeysLoaded byContent
FireDAC.<name>.<parameter>TMARSFireDAC.LoadConnectionDefs(FEngine.Parameters, 'FireDAC')a FireDAC connection definition (DriverID, Database, Server, User_Name, Password, Pooled, …)
UniDAC.<name>.<item> or UniDAC.<name>.ConnectStringTMARSUniDAC.LoadConnectionDefs(FEngine.Parameters, 'UniDAC')a UniDAC connect string (Provider Name, Server, Database, User ID, Password, …)
MyDAC.<name>.<item> or MyDAC.<name>.ConnectStringTMARSMyDAC.LoadConnectionDefs(FEngine.Parameters, 'MyDAC')a MyDAC connect string (Server, Port, Database, User ID, Password, …)
IBDAC.<name>.<item> or IBDAC.<name>.ConnectStringTMARSIBDAC.LoadConnectionDefs(FEngine.Parameters, 'IBDAC')an IBDAC connect string (Server, Database, User ID, Password, Client Library, Charset, …)

Application parameters (i.e. DefaultApp.FireDAC.ConnectionDefName) choose the definition injected without a [Connection] attribute:

ParameterTypeDefaultDescription
FireDAC.ConnectionDefName, UniDAC.ConnectionDefName, MyDAC.ConnectionDefName, IBDAC.ConnectionDefNamestringMAIN_DBThe definition of [Context] connections and helpers.
FireDAC.ConnectionExpandMacros, UniDAC.ConnectionExpandMacros, MyDAC.ConnectionExpandMacros, IBDAC.ConnectionExpandMacrosBooleanFalseResolve the definition name as a context value (i.e. Token_Claim_tenant).

See Data Access and the page of each library: FireDAC, UniDAC, MyDAC, IBDAC.

Reading and injecting parameters ​

pascal
// In code
var LPort := FEngine.Parameters.ByName('Port').AsInteger;
var LSecret := LApp.Parameters.ByName('JWT.Secret').AsString;

// Injected into a resource
[Path('cfg')]
TCfgResource = class
  [EngineParam('Port', 8080)]       Port: Integer;
  [ApplicationParam('JWT.Secret')]  Secret: string;
end;

Provide a default as the second argument to ByName/[EngineParam]/[ApplicationParam] so missing keys degrade gracefully.

Custom parameters ​

You can add your own keys to the .ini and read/inject them the same way — a convenient place for feature flags, external service URLs, file paths, etc.

ini
[DefaultApp]
Feature.NewSearch=true
Storage.Path=C:\data\uploads
pascal
[ApplicationParam('Storage.Path')] StoragePath: string;

Released under the Mozilla Public License 2.0.