Domain Composition

This page covers how to declare and compose Cognibase Domains at the assembly level.

Declaring a Domain

Every domain assembly must carry the [RuntimeDomain] assembly attribute. At a minimum you must supply the DomainName:

// AssemblyInfo.cs  (or any file that accepts assembly-level attributes)
[assembly: RuntimeDomain(DomainName = "MyApp.Domain")]

The DomainName is used as the domain identifier throughout the Cognibase runtime — in transactions, subscriptions, and log output. Choose a name that is stable across releases.

Key [RuntimeDomain] Options

Option	Type	Default	Description
DomainName	string	—	Required. Logical name of this domain
DomainShortCode	string	""	Optional short abbreviation for the domain name
EntitiesNameSpace	string	""	Namespace prefix used when locating entity types
Description	string	""	Human-readable description shown in admin tooling
DefaultIdPersistenceMode	DataItemIdPersistenceMode	Key	How object identity is persisted by default across the domain
ClientCacheMode	DomainCacheMode	Class	Caching strategy applied on the client side
ServerCacheMode	DomainCacheMode	Class	Caching strategy applied on the server side
ClientPreLoadMode	DomainPreLoadMode	Class	Pre-load strategy applied on the client side
ServerPreLoadMode	DomainPreLoadMode	Class	Pre-load strategy applied on the server side
InitializationMode	DomainInitializationMode	InServer	Controls where domain initialization code runs
IsReportProvider	bool	true	Exposes the domain as a data source for reporting

Security Defaults

[RuntimeDomain] also carries a full set of security defaults that apply to every class and property in the domain unless overridden at a lower level:

Option	Default
SecurityOnFields	false
SecurityOnActions	true
SecurityDefaultLoadAllow	true
SecurityDefaultBrowseAllow	true
SecurityDefaultDisplayAllow	true
SecurityDefaultSaveNewAllow	true
SecurityDefaultSaveUpdatedAllow	true
SecurityDefaultSaveDeletedAllow	true
SecurityDefaultFieldDisplayAllow	true
SecurityDefaultFieldChangeAllow	true
SecurityDefaultExecuteActionAllow	true

Depending on Other Domains

A domain can reference classes from other domain assemblies. You declare those dependencies with [RequiredDomain] or [IncludedDomain], both placed at the assembly level. Both take the Type of the target domain's DataItemDomainFactory subclass as their argument.

[RequiredDomain]

Use [RequiredDomain] when your domain's data model cannot function without the referenced domain — for example, when one of your entity properties is typed to a class that lives in the other domain.

[assembly: RuntimeDomain(DomainName = "MyApp.Domain")]
[assembly: RequiredDomain(typeof(CommonDomainFactory))]

The Cognibase runtime will enforce that the required domain is loaded before your domain starts.

[IncludedDomain]

Use [IncludedDomain] for a looser reference where the dependency is optional or dynamically resolved:

[assembly: RuntimeDomain(DomainName = "MyApp.Domain")]
[assembly: IncludedDomain(typeof(TopologyDomainFactory))]

Example — Multi-Domain Assembly

The following example is modelled on the Is2Aware system, where separate domain assemblies cover generic/common data, topology, and application-specific data. Each domain assembly declares its own [RuntimeDomain] and then lists any assemblies it depends on:

// Missionware.Common.Generic.Domain — assembly-level declarations
[assembly: RuntimeDomain(DomainName = "Missionware.Common.Generic.Domain")]

// Missionware.Common.Topology.Domain — depends on the generic domain
[assembly: RuntimeDomain(DomainName = "Missionware.Common.Topology.Domain")]
[assembly: RequiredDomain(typeof(CommonGenericDomainFactory))]

// Missionware.Facility.Domain — depends on both common domains
[assembly: RuntimeDomain(DomainName = "Missionware.Facility.Domain")]
[assembly: RequiredDomain(typeof(CommonGenericDomainFactory))]
[assembly: RequiredDomain(typeof(TopologyDomainFactory))]

Domain Factory

Every domain must provide a DataItemDomainFactory subclass. The factory is the entry-point that the Cognibase Client Object Manager uses to register and initialise the domain at startup:

public class MyAppDomainFactory : DataItemDomainFactory
{
    // Framework calls this to create instances of your DataItem classes
    public override DataItem CreateDataItem(Type type) { ... }
}

The factory class is registered once during application bootstrapping:

// Client bootstrap
var client = ClientObjMgr.Initialize(cApp, ref clientSettings);
client.RegisterDomainFactory<MyAppDomainFactory>();

Serialization Alias

When serialized domain payloads must survive assembly renames or moves across deployment environments, attach a stable alias with [DataItemDomainSerializationAssemblyAlias]:

[assembly: DataItemDomainSerializationAssemblyAlias("MyApp.Domain.v1")]

This attribute maps the assembly to a stable string key used in serialized streams, so that an older client can still deserialize objects from a renamed assembly.