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

# 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

# State store Redis indexes
RedisQueryIndexes:
  - Name: europeanUnionIdx
    Indexes:
      - Key: europeanUnion
        type: NUMERIC

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).

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.

RedisQueryIndexes

This is the list of custom Redis indexes you want to create in the state store.

Please see this article for more information.

TaskRunnerExecutionMode

This options 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

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.

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).

Example:

ApplicationInsights:
  Client:
    DisableAjaxTracking: false
    DisableExceptionTracking: false
    DisableFetchTracking: false
    EnableAjaxErrorStatusText: false
    EnableAjaxPerfTracking: false
    EnableAutoRouteTracking: true
    EnableCorsCorrelation: true
    EnableRequestHeaderTracking: false
    EnableResponseHeaderTracking: false
    EnableUnhandledPromiseRejectionTracking: true
    InstrumentationKey: <InstrumentationKeyOfClientApplicationInsightsResource>
  Generator:
    DeveloperMode: false
    InstrumentationKey: <InstrumentationKeyOfGeneratorApplicationInsightsResource>
  Server:
    AddAutoCollectedMetricExtractor: true
    DeveloperMode: false
    EnableAdaptiveSampling: true
    EnableAzureInstanceMetadataTelemetryModule: true
    EnableDependencyTrackingTelemetryModule: true
    EnableEventCounterCollectionModule: true
    EnableHeartbeat: true
    EnablePerformanceCounterCollectionModule: true
    EnableQuickPulseMetricStream: true
    EnableRequestTrackingTelemetryModule: true
    InstrumentationKey: <InstrumentationKeyOfServerApplicationInsightsResource>
    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.NET: 2.7.3
  System.IO.Abstractions: 21.0.2

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.

Tenants

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

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 you to define other clusters which could be accessed through the main cluster url (using url prefix).

For example, you have a cluster TechnicalDemos and a cluster TrackingDemo. You want to display a TrackingDemo page directly in a UI of TechnicalDemos.

In this case, you can add the following configuration to TechnicalDemos yml configuration file :

NestedClusters:
  - Name: TrackingDemo
    Prefix: tracking

Please see this article for an example of how to display a UI view of a nested cluster inside a main cluster UI view.

With this configuration, TrackingDemo can be accessed using the base url of TechnicalDemos (eg: https://localhost/neos/TechnicalDemos) and the tracking prefix. Which lead to the url https://localhost/neos/TechnicalDemos/tracking.

Warning

This feature only works in development with HTTPSys web server on Windows machine. It doesn't work if you run Neos with Kestrel web server (eg: neos run -ws Kestrel)

Note

Several configurations can be referenced by NestedClusters. It can be other clusters, but also multiple prefixes for a same cluster.

Example :

NestedClusters:
  - Name: TrackingDemo
    Prefix: tracking
  - Name: TrackingDemo
    Prefix: my-order/status
  - Name: Documents
    Prefix: docs

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.sln.

But with this configuration:

ClusterName: TechnicalDemos
SolutionName: AllProjects

The solution name will be AllProjects.sln.

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.

GenerationLogLevels

Since version 1.20, it is possible to define the log level of some generation logs :

GenerationLogLevels:
  AutomaticLookup: Warning
  UnassociatedResource: Warning

The configurable logs are :

Code	Default level	Message
AutomaticLookup	Warning	An automatic lookup was generated for property "{0}" of UIView "{1}", you should define a lookup for this property.
UnassociatedResource	Warning	The "{0}" is not associated with any function.

The possible log levels are : Error, Warning, Information, Debug, Verbose, None.

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

Optional properties

ClusterTitle

Authentication

Languages

RedisQueryIndexes

TaskRunnerExecutionMode

Csprojs

AutomationTest

Persistence

BusinessCode

Warning

Application

Warning

PersistenceConverters

DatabaseContextConfigurators

ApplicationInsights

MainUIViewName

MainFramesContainerId

NugetPackages

ReferencedModules

RestoreOptions

Tenants

Usings

Application

UI

DataModelingStrategy

GlobalResiliencySpec

Note

ClusterResiliencyPolicies

NestedClusters

Warning

Note

SolutionName

EFCoreWarnings

Note

Note

GenerationLogLevels