Cluster configuration

Cluster configuration is parsed from YML files placed in the root directory of the cluster

Example: Cluster technicaldemos

technicaldemos
└─── client
└─── modules
└─── projects
└─── server
└─── [pattern]technicaldemos.connectionstring.yml
└─── technicaldemos.application-insights.yml
└─── technicaldemos.authentication.yml
└─── technicaldemos.connectionstring.yml
└─── technicaldemos.yml

Neos generator will look at the *.yml files in the root directory and use their values as cluster configuration.

Note

Files beginning with [ or _ are ignored by the generator.

Note

If a property is set in several files, the one in the file with the longer file name will be used.

Example:

# The root namespace for the generated application
RootNamespace: TechnicalDemos
# The cluster name
ClusterName: TechnicalDemos
# The cluster version
ClusterVersion: 0.0.1
# The company name
Company: Groupe Isagri Services

# Persistence type
# YamlFile | SqlServer | PostgreSQL | Oracle
PersistenceType: PostgreSQL

# Optional YAML persistence formatting settings
YamlPersistence:
  TemplateValueAutoFormatting: false
  CSharpValueAutoFormatting: false

# The cluster description
ClusterTitle: Technical demos
# PostgreSQL connection string
ConnectionString: Server=host;Port=1234;Database=databasename;User Id=user;Password=password
# The cluster supported languages
Languages:
  - en
  - fr

Clusters configurations in user profile

To develop an application, you usually need several clones of the application's git repository. This makes it easy to move from one version to another, or from one fix/development to another. In this case, it is often necessary to copy/paste yml configuration files from one directory to another. There may be omissions, and these file copies are very tedious.

To centralize cluster configurations, go to the user profile directory %USERPROFILE%/.neos/clusters/config (create directory if it doesn't exist). To create a configuration for a specfic cluster, create a directory with the ClusterName. If the yml file is at %USERPROFILE%/.neos/clusters/config directory, then all clusters will read this configuration file.

Example:

%USERPROFILE%/.neos/clusters/config
└─── NeosTransversalsBusiness
     └─── connectionstring.yml (read only by cluster with name `NeosTransversalsBusiness`)
└─── Tiers360
     └─── connectionstring.yml
└─── TMSCore
     └─── connectionstring.yml
└─── IPX
     └─── connectionstring.yml
└─── KEYBusiness
     └─── connectionstring.yml
└─── Siga.Invoicing
     └─── connectionstring.yml
└─── TechnicalDemos
     └─── connectionstring.yml
global.yml (read by all clusters)

The order in which the configuration files are read is as follows:

First, read the global files located in the directory %USERPROFILE%/.neos/clusters/config.
Second, read global files located in the %USERPROFILE%/.neos/clusters/config/{ClusterName} directory. Replaces and completes read configuration
Lastly, read the files in the cluster root directory. Replaces and completes read configuration

To see the loaded configuration, open Neos Studio > Go to Home Page > Configuration > Cluster. To check the origin of a configuration value, you can see the source file.

Mandatory properties

Following properties are mandatory in order to generate a working cluster.

ClusterName

This is the unique identifier of the cluster.

ClusterVersion

This is the version of the cluster.

RootNamespace

This is the root namespace that will be used for server-side generated code. It can be overridden at the module level.

Company

This is the name of the company that publishes the cluster.

PersistenceType

This is the type of persistence that the cluster will use. Supported values are:

YamlFile
SqlServer
PostgreSQL
Oracle

Warning

YamlFile persistence is not suited for use in production.

ConnectionString (if database persistence)

If PersistenceType is set to SqlServer, PostgreSQL or Oracle, you need to specify the connection string to connect to the database.

YamlDataPath (if YamlFile persistence)

If PersistenceType is set to YamlFile, you need to specify the directory in which all the files will be saved.

Note

You can use relative path (ex: ../yamlfiles).

YamlPersistence (optional)

This section contains settings specific to YAML-file persistence behavior.

Example:

YamlPersistence:
  TemplateValueAutoFormatting: true
  CSharpValueAutoFormatting: true

Both settings are boolean.

By default, both values are false, which means metadata is written without additional template or embedded C# reformatting.

TemplateValueAutoFormatting controls formatting of YAML properties containing UI templates such as Template.

CSharpValueAutoFormatting controls formatting of YAML properties containing embedded C# code such as Code, Getter, and Setter.

EncryptionKey (if database encryption)

If you want to encrypt database, you need to specify the encryption key.

Add the key to the cluster configuration file (*.yml):

```yaml
EncryptionKey: "<Your_Base64_Encoded_Key>"
```

Important

Ensure the key is Base64-encoded and exactly 32 bytes.

Optional properties

Following properties are not mandatory to generate a working cluster but they allow to customize the cluster behaviors.

ClusterTitle

This is the title which will be shown on the cluster main page.

Authentication

This is the property in which you can specify your authentication provider configuration.

Please see this article for more information.

Languages

This is the list of languages supported by your cluster.

The default language is the first of the list.

Example:

Languages:
  - en
  - fr

In this example, both en and fr are supported, and en is the default language.

TaskRunnerExecutionMode

This option allows you to configure the generation of the task runner project. By default, the task runner is not generated. The line below must be added so that it is generated and allows execution of background server methods.

TaskRunnerExecutionMode: IsolatedProcess

MultiTenant

The default value for this option is true.

By default, the Generate metadata action on an entity with a Guid or Auto-incremented integer key sets the Multi-tenant attribute to true when it creates a data table (the action never modifies the attribute on an existing data table). If you are working on a cluster which is going to be run in single-tenant mode all the time, you can indicate this in the cluster configuration like this:

MultiTenant: false

When MultiTenant is false, all tables created by the Generate metadata action have the Multi-tenant attribute set to false.

Csprojs

In this object, you can reference external projects (.csprojs files) containing business code for the following usages.

AutomationTest

This will add the referenced projects to the automation test generated projects. Please see this article for more information.

Persistence

This will allow the referenced projects to be used to configure persistence converters and database context configurators.

BusinessCode

This will add the referenced projects to generated solution. By default, no generated project references these projects. You can manually reference them in your business code projects (Domain or Application layer).

Csprojs:
  BusinessCode:
    - ./ProjectPath/ProjectName.csproj

Warning

It is not advisable to use this feature for modules that are to be published, as this dependency will make them difficult to distribute.

Application

This will add the referenced projects to generated solution. The projects will be added as dependency of the generated Application.Abstractions project.

Csprojs:
  Application:
    - ./ProjectPath/ProjectName.csproj

Warning

It is not advisable to use this feature for modules that are to be published, as this dependency will make them difficult to distribute.

PersistenceConverters

This section allows you to define the different converters. Please see this article for more information.

Database

This section allows you to define the database configuration.

Example:

Database:
  QuotedIdentifiers: false

There is only one QuotedIdentifiers option. Please see this article for more information.

DatabaseContextConfigurators

This section allows you to define the different database context configurators. Please see this article for more information.

ApplicationInsights

In this section you can define the Application Insights configuration you want to add to your cluster (backend and frontend).

Warning

Backend .NET SDK configuration in this section is deprecated and will be removed in a future version. For backend telemetry routing, use OpenTelemetry Collector configuration. See OpenTelemetry collector migration.

Example:

ApplicationInsights:
  Client:
    DisableAjaxTracking: false
    DisableExceptionTracking: false
    DisableFetchTracking: false
    EnableAjaxErrorStatusText: false
    EnableAjaxPerfTracking: false
    EnableAutoRouteTracking: true
    EnableCorsCorrelation: true
    EnableRequestHeaderTracking: false
    EnableResponseHeaderTracking: false
    EnableUnhandledPromiseRejectionTracking: true
    ConnectionString: <ConnectionStringOfClientApplicationInsightsResource>
  Generator:
    DeveloperMode: false
    ConnectionString: <ConnectionStringOfGeneratorApplicationInsightsResource>
  Server:
    AddAutoCollectedMetricExtractor: true
    DeveloperMode: false
    EnableAdaptiveSampling: true
    EnableAzureInstanceMetadataTelemetryModule: true
    EnableDependencyTrackingTelemetryModule: true
    EnableEventCounterCollectionModule: true
    EnableHeartbeat: true
    EnablePerformanceCounterCollectionModule: true
    EnableQuickPulseMetricStream: true
    EnableRequestTrackingTelemetryModule: true
    ConnectionString: <ConnectionStringOfServerApplicationInsightsResource>
    ResourceGroup: <ResourceGroupOfServerApplicationInsightsResource>
    ResourceName: <ResourceNameOfServerApplicationInsightsResource>
    TrackExceptions: true

MainUIViewName

This property is used if you want to use a custom homepage for your cluster. Please see this article for more information.

MainFramesContainerId

This property is used if you want to use a custom homepage for your cluster. Please see this article for more information.

NugetPackages

This section allows you to add nuget packages to the generated Application.Abstractions project.

Example:

NugetPackages:
  SmartFormat: 3.6.1
  System.IO.Abstractions: 22.2.0

ReferencedModules

This section is used if you want to reference external modules from a NuGet source. Please see this article for more information.

RestoreOptions

This section is used if you want to specify restore options when external modules are restored from a NuGet source. Please see this article for more information.

Multitenancy

Multi-tenant behavior can be set with the following sections / properties.

TenantManagement

This section is used to configure Tenant Management cluster. Please see this article.

Tenants

This property is used to customize multi-tenant behavior. Please see this article for more information.

TenantSelectionDirectory

This property is used to serve a custom tenant selection web page. Please see this article.

Tenant selection endpoint configuration

The tenant selection endpoint behavior can be customized in development using the following properties:

IncludeDisabledTenants
IncludeTenantStatus

These properties are read from the TenantSelection:Endpoint section.

Default values:

IncludeDisabledTenants: false (disabled tenants are filtered out)
IncludeTenantStatus: true (isDisabled and isAvailable are included in the endpoint response)

Example:

TenantSelection:
  Endpoint:
    IncludeDisabledTenants: false
    IncludeTenantStatus: true

Please see this article for details.

StatusCodePagesDirectory

This property is used to serve custom HTTP status code pages in development.

When a request having Accept: text/html header leads to a specific status code (ex: 404 when page is not found, 503 when a tenant is unavailable or migrating), then the response will contains the response of associated status code page.

Default pages are provided with the framework, but you can override them with your own pages. To do so, in development, you'll need to specify on which directory are located the files.This is done in the configuration of your current cluster using the StatusCodePagesDirectory property :

StatusCodePagesDirectory: c:/projects/my-custom-status-code-pages-directory

Note

The directory path can be relative (eg: ../some/directory), in this case, the base directory is the root directory of the cluster.

Warning

The status code pages can only be of html type and should be named XXX.html where XXX is the status code (ex: 404, 503).

Warning

In development, the custom directory replace the whole default directory. Status code pages will only be rendered if created in the custom directory.

For production, please see this article.

DisabledTenantPagePath and UnavailableTenantPagePath

These optional properties override pages for tenant-related 503 responses:

DisabledTenantPagePath is the HTML file served when the requested tenant is disabled by an administrator.
UnavailableTenantPagePath is the HTML file served when the tenant is unavailable because its data persistence state is not Running.

The disabled tenant page has priority when both the tenant status and persistence state indicate that the tenant cannot be accessed. If a property is not configured, the environment default is used. The development Server Proxy uses tenant-pages/disabled.html and tenant-pages/unavailable.html from the Neos installation directory; the deployed Gateway uses /app/tenant-pages/disabled.html and /app/tenant-pages/unavailable.html. The 503.html page is served when the request is not associated with a known tenant cause.

In the Gateway, NEOS_TENANT_PAGES_ENABLED controls whether these specialized pages are used and defaults to true at application level. The standard Gateway Docker image temporarily sets it to false for backward compatibility, causing tenant-related responses to use 503.html. Override it with true to enable the specialized pages.

Paths can be absolute or relative. Relative paths use the current process directory as their base. The properties are optional, but a configured path that does not point to an existing HTML file is reported as an error at startup. In the development Server Proxy, this error is non-blocking; in the deployed Gateway, it prevents startup.

Example:

DisabledTenantPagePath: ../demos/custom-gateway/custom-tenant-pages/disabled.html
UnavailableTenantPagePath: ../demos/custom-gateway/custom-tenant-pages/unavailable.html

Usings

This section allows you to add usings in generated class file for business code compilation.

Application

usings added in this section are added in the generated class files for Required as expressions on entity view properties.

Example:

Usings:
  Application:
    - FluentResults

UI

usings added in this section are added in the generated class files for UI code transpilation.

Example:

Usings:
  UI:
    - FluentResults

DataModelingStrategy

This option allows you to define what is the strategy used to model data. Two options are available :

Entity first [default value] : the entities will be the starting point for defining the architecture of the cluster
Database first : the data tables will be the starting point for defining the architecture of the cluster

Example:

DataModelingStrategy: DatabaseFirst

GlobalResiliencySpec

This property is used to configure the global resiliency policies of Dapr. The content will be used to generate a resiliency configuration file.

Example:

In the cluster yaml configuration file :

GlobalResiliencySpec:
  policies:
    retries:
      DaprBuiltInServiceRetries: # Overrides default retry behavior for service-to-service calls
        policy: constant
        duration: 5s
        maxRetries: 10

This corresponds to this example in the Dapr documentation.

Note

This configuration is applied for all clusters launched with neos run. It is perfect for overriding default configurations. If you want to create a configuration for specific clusters, you should use the ClusterResiliencyPolicies which will automatically target the cluster.

ClusterResiliencyPolicies

This property is used to configure Dapr resiliency policies for the cluster (using specific apps target). The supported policies are retries, circuitBreakers and timeouts

Example:

In the cluster yaml configuration file of technicaldemos cluster :

ClusterResiliencyPolicies:
  circuitBreakers:
    pubsubCB:
      maxRequests: 1
      interval: 8s
      timeout: 45s
      trip: consecutiveFailures > 8
  retries:
    retryForever:
      policy: exponential
      maxInterval: 15s
      maxRetries: -1 # Retry indefinitely
  timeouts:
    general: 5s

In this case, it will generate a circuit breaker and retry policy configuration for the edited cluster :

specs:
  targets:
    apps:
      technicaldemos: # app-id of the target cluster
        retry: retryForever
        circuitBreaker: pubsubCB
        timeout: general

NestedClusters

This option allows the current cluster to access other clusters under its own base URL using a path prefix (proxying).

This is typically used to keep everything under the same origin (avoid CORS) and/or embed a nested cluster UI in the main cluster.

For more information, see this article.

MicroFrontend

This section allows a cluster to expose UI views so another cluster can consume them as micro-frontend remote views.

Example:

MicroFrontend:
  ExposedUIViews:
    - OrderTrackingUI

For more information, see this section.

RedisHost

When you run neos setup command, it installs and starts a redis-server instance on your computer (in wsl for windows). By default, the cluster will try to connect to this redis instance running on localhost:6379.

In development you can use any other instance by setting the RedisHost property of your cluster configuration in the format <hostname>:<port>.

Examples :

RedisHost: localhost:1234 # Custom port

RedisHost: external-redis.local:6379 # Custom host name

RedisHost: 12.34.56.78:1234 # Custom host IP and port

Note

You can modify the %userProfile%/.neos/X.X/dapr/run-prescript.ps1 to customize how Redis instance is started. Example: change the port on which the server is started in wsl from 6379 (default) to 1234

wsl -u root sudo sed -i 's/^port [0-9]\+/port 1234/' /etc/redis/redis.conf
wsl -u root sudo service redis-server start

Warning

This feature only works with standalone instances (eg: not cluster nor sentinel) of Redis.

For production, please see this article.

SolutionName

This option allows you to define the name of the generated .NET solution in the server directory. The default solution name is the cluster name.

With this configuration:

ClusterName: TechnicalDemos

The solution name will be TechnicalDemos.slnx.

But with this configuration:

ClusterName: TechnicalDemos
SolutionName: AllProjects

The solution name will be AllProjects.slnx.

EFCoreWarnings

EF core warnings can be configured with ConfigureWarnings methods. This options allows you to configure the generation of the call to this method.

For each EF core event identifier, you can choose the action to do:

Ignore causes nothing to happen when the specified event occurs, regardless of default configuration.
Critical causes a LogLevel.Critical event to be logged, regardless of default configuration.
Error causes a LogLevel.Error event to be logged, regardless of default configuration.
Warning causes a LogLevel.Warning event to be logged, regardless of default configuration.
Information causes a LogLevel.Information event to be logged, regardless of default configuration.
Throw causes an exception to be thrown when the specified event occurs, regardless of default configuration.

You can find the list of available events with this links:

Note

The LogLevel enumeration contains other values (Debug and Trace) but these should not be used as only information, warning and error logs sent by EF Core are forwarded to Serilog.

Example to throw an exception when a navigation property is being lazy-loaded:

EFCoreWarnings:
  CoreEventId.NavigationLazyLoading: Throw

Example to log an information indicating that sensitive data logging is enabled and may be logged:

EFCoreWarnings:
  CoreEventId.SensitiveDataLoggingEnabledWarning: Information

Example to ignore the log when a database command has been executed:

EFCoreWarnings:
  RelationalEventId.CommandExecuted: Ignore

Note

The two previous examples only make sense if Serilog has been configured to display the logs sent by EF Core.

Default white space handling

The white space handling of the property applies to strings and localizable strings. See article about white space handling You can define a default white space handling. This option will be applied on all string properties of the cluster with White space handling set to Default.

For example, if you want that your application:

on back end: check automatically white space according to the case.
on front end: clean automatically white space according to the case.

You can define the default white space handling:

DefaultWhiteSpaceHandling: NoLeadingAndTrailingWhiteSpace

GenerationLogLevels

It is possible to set the log level of some messages emitted by the Neos generation processing.
The possible log levels are: Error, Warning, Information, Debug, Verbose, None.
The list of configurable messages is available here. The configuration can be done using the numeric code of the message having the format X0000 or the full code.

Warning

It is not recommended to use this setting to globally disable a warning. You can refer to this article for possible alternatives.

The table below gives configurable generation messages — some disabled by default for backward compatibility, others emitted at a low level by default — for which a stronger level is recommended:

Numerical code	Full code	Recommended level	Message
M0004	UnconfiguredRoute	Warning	The route is not configured on the entity view or server method. The default route will be used.
M0030	UICSharpWarning	Warning	C# code for a UI element issued a warning. You have to run `neos generate -f` to be sure to have all the warnings.
M0077	UIViewPropertySortableRequiresFilterableEntityViewProperty	Warning	A sortable UI view column is bound to an entity view property that is not `Filterable` or originates from a collection (directly or through a parent element). The column is generated as non-sortable in the UI view. In C# code, you can change the columns `SortProperty` to use another property for sorting it and re-enable sorting with `Sortable`.

Example configuration to activate them with the numeric code:

GenerationLogLevels:
  M0004: Warning # UnconfiguredRoute
  M0063: Warning # UICSharpWarning

Example configuration to enable them with the full code:

GenerationLogLevels:
  UnconfiguredRoute: Warning # M0004
  UICSharpWarning: Warning # M0063

DependenciesWarnings

By default, warnings issued by dependencies are not displayed in the result of the neos generate command. Only an information message at the end of the generation tells you if there are warnings in dependencies. If you want to display the details of these warnings and have them taken into account in the total number of warnings of the cluster, you can add the following line to your cluster configuration:

Example:

DependenciesWarnings: true

UIDefaultBehavior

This section enables you to globally change the default behavior of the UI.

Example:

UIDefaultBehavior:
  DatagridInfiniteScrolling: true

Please see this article for more information.

Table of Contents

Cluster configuration

Note

Note

Clusters configurations in user profile

Mandatory properties

ClusterName

ClusterVersion

RootNamespace

Company

PersistenceType

Warning

ConnectionString (if database persistence)

YamlDataPath (if YamlFile persistence)

Note

YamlPersistence (optional)

EncryptionKey (if database encryption)

Important

Optional properties

ClusterTitle

Authentication

Languages

TaskRunnerExecutionMode

MultiTenant

Csprojs

AutomationTest

Persistence

BusinessCode

Warning

Application

Warning

PersistenceConverters

Database

DatabaseContextConfigurators

ApplicationInsights

Warning

MainUIViewName

MainFramesContainerId

NugetPackages

ReferencedModules

RestoreOptions

Multitenancy

TenantManagement

Tenants

TenantSelectionDirectory

Tenant selection endpoint configuration

StatusCodePagesDirectory

Note

Warning

Warning

DisabledTenantPagePath and UnavailableTenantPagePath

Usings

Application

UI

DataModelingStrategy

GlobalResiliencySpec

Note

ClusterResiliencyPolicies

NestedClusters

MicroFrontend

RedisHost

Note

Warning

SolutionName

EFCoreWarnings

Note

Note

Default white space handling

GenerationLogLevels

Warning

DependenciesWarnings

UIDefaultBehavior