Backend application configuration

The backend application can typically be configured in development using the cluster YML configuration file.
This configuration is used by Neos to create an ASP.NET Core appsettings.json configuration file when generating the application.

Sometimes, you might need to add additional configuration for libraries used in the application (authentication, logger, email sender, ...).
This can be done by creating a appsettings.Development.json file a the root folder of the cluster.

Example :

{
  "PersistenceSettings": {
    "DefaultConcurrencyAccessMode": "Disabled",
    "SendGrid": {
      "Key": "MyKey",
      "From": {
        "Name": "MyApp",
        "Address": "[email protected]"
      }
    }
  }
}

This configuration file adds or overrides values in the appsettings.json file created by Neos when generating the application.

See this article to learn more about ASP.NET Core configuration.

Some of these options control database-level behavior specifically, such as generating CHECK constraints for text properties — see Configure database check constraints for multiline properties below.

Configure text validation

Neos validates text values on the backend before saving them:

• For single-line properties (Multiline = false), values containing line breaks (\r, \n) are rejected.
• For text properties with a maximum length, values longer than this length are rejected.

Each control runs at two levels:

• On entity views, when the data received by the API is saved. Every save made from the UI goes through this level.
• On entities, when they are saved. This level also covers backend code that writes entities directly, without an entity view, such as an import or a migration.

Neos 3.0 added some of these controls, and the TextValidation settings make it possible to disable them temporarily after the upgrade. Each setting only disables the controls added in Neos 3.0:

Setting	Disables	Does not disable
EnforceMultiLineConstraint	The line break control on entity views and entities	-
EnforceMaxLengthConstraint	The maximum length control on entities	The maximum length control on entity views and on the client

The maximum length control on entity views existed before Neos 3.0, so it stays enforced whatever the value of EnforceMaxLengthConstraint: a value that is too long is always rejected when it is entered in the UI or sent to the API. The client also reports it on the field before saving. EnforceMaxLengthConstraint is therefore only useful for backend code that writes entities directly. Before Neos 3.0, a value that was too long reached the database unchecked: depending on the database and the column type, it was either rejected with an error that does not name the property, or saved as is.

When a setting is disabled, the entity level logs a warning for each value it lets through, with the entity, the property and, for the maximum length, the configured length. Use these warnings to find the data or the code to fix before enabling the control again.

To disable one or both controls, add the following settings in your appsettings.Development.json:

{
  "TextValidation": {
    "EnforceMultiLineConstraint": false,
    "EnforceMaxLengthConstraint": false
  }
}

Apply with environment variable

In .NET configuration binding, use __ as a section separator:

$env:TextValidation__EnforceMultiLineConstraint = "false"
$env:TextValidation__EnforceMaxLengthConstraint = "false"

Caution

Disabling these settings allows invalid text values to be persisted: line breaks in single-line properties, and values longer than the maximum length when backend code writes entities directly. These options are intended as temporary production mitigation after an FMK upgrade when full regression testing is not yet possible and the new controls are considered too risky to enforce immediately. Keep them disabled only for transitional scenarios and re-enable them as soon as possible.

Configure database check constraints for multiline properties

In addition to the backend validation described above, Neos can generate database CHECK constraints for multiline properties, enforcing the same two rules directly at the schema level: no line breaks on single-line properties, and a maximum length on properties that declare one.

This setting is independent from TextValidation above: it does not control the backend validation, only whether the database constraints themselves are generated. It defaults to false, so existing environments are not affected until you opt in.

To enable it, add the following setting in your appsettings.<Environment>.json:

{
  "DatabaseCheckConstraints": {
    "EnforceMultiLineCheckConstraints": true
  }
}

Apply with environment variable

$env:DatabaseCheckConstraints__EnforceMultiLineCheckConstraints = "true"

Caution

Enabling this setting does not validate existing data: the migration succeeds even if some rows still violate the rule, but new inserts and updates are rejected immediately once the constraint is created. Check and correct existing data afterward — see Preparing data for text constraints.