Skip to content

Database Entities Annotations

github-actions[bot] edited this page Nov 17, 2026 · 1 revision

Data Annotations

Annotations on an entity interface describe its SQL mapping, constraints, relationships, and optional behavior. Apply them to the contract before registering it. Registration reads the annotations and synchronizes supported schema changes.

Annotation reference

Annotation Namespace Purpose
Entity Blueprint.Database.Entities.Annotations Marks a contract; optionally sets table name and Schema (default dbo).
EntityIndex Blueprint.Database.Entities.Annotations Defines a named index over mapped properties; IsUnique defaults to false.
Multilingual Blueprint.Database.Entities.Annotations Stores a separate value for each configured language.
FallbackToDefaultLanguage Blueprint.Database.Entities.Annotations Requires Multilingual; reads the default value when the selected translation is null or empty, without changing stored translations.
RAMCached Blueprint.Database.Entities.Annotations Enables full-table RAM caching for this contract and automatically for all its transitive AutoInclude entities, even without their own RAMCached annotation. See automatic caching of AutoInclude entities.
AutoInclude Blueprint.Database.Entities.Annotations Automatically loads the annotated navigation when reading entities. When reached from a RAM-cached entity, the related entity is automatically RAM cached too.
Required System.ComponentModel.DataAnnotations Requires a stored value. For multilingual fields, applies to every language.
MaxLength, StringLength System.ComponentModel.DataAnnotations Sets the maximum stored length. StringLength.MinimumLength is not a database validation rule.
Timestamp System.ComponentModel.DataAnnotations Maps a SQL Server rowversion concurrency token.
ConcurrencyCheck System.ComponentModel.DataAnnotations Includes a property in optimistic concurrency checks.
Column System.ComponentModel.DataAnnotations.Schema Sets the physical column name and optionally SQL TypeName.
NotMapped System.ComponentModel.DataAnnotations.Schema Excludes a property from storage.
ForeignKey, InverseProperty System.ComponentModel.DataAnnotations.Schema Identifies reference keys and inverse navigation properties.
Precision Microsoft.EntityFrameworkCore Sets decimal precision and scale.
DefaultValue System.ComponentModel Configures a SQL default for the column.
ReadOnly(true) System.ComponentModel Allows an initial value but rejects later changes when saving.

Blueprint does not run a general form-validation pipeline for every .NET validation attribute. Validate user input in your application; use transaction validation for checks that must succeed before database commit.

Example contract

This separate contract demonstrates common annotations. Register it with database.RegisterEntity<Category>() before using Category.Create() or querying it.

using Blueprint.Database.Entities.Annotations;
using Blueprint.Database.Entities;
using System.ComponentModel;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace BlueprintManual
{
    /// <summary>Describes a catalog category with an immutable code and concurrency token.</summary>
    [Entity("Categories", Schema = "catalog")]
    [EntityIndex("UX_Categories_Code", nameof(Code), IsUnique = true)]
    public interface Category : BlueprintEntity
    {
        [Required, MaxLength(40), ReadOnly(true)]
        string Code { get; set; }

        [Column("DisplayName"), MaxLength(200)]
        string Name { get; set; }

        [DefaultValue(0)]
        int SortOrder { get; set; }

        [Timestamp]
        byte[] Version { get; set; }

        [NotMapped]
        string DisplayLabel
        {
            get
            {
                return Code + " - " + Name;
            }
        }
    }
}

The index takes C# property names, such as nameof(Code), rather than SQL column names. The column named DisplayName continues to be exposed as Name in C#.

Nullability and defaults

For ordinary reference properties, nullable reference annotations affect whether the column permits NULL. An explicit [Required] also makes a property required. Nullable value types such as decimal? represent optional values.

For multilingual properties, use an explicit [Required] only when every configured translation must exist. A non-nullable C# reference annotation alone does not require all translations. Length, precision, and column options apply to the generated language columns.

Use [FallbackToDefaultLanguage] on a mapped [Multilingual] string to opt into default-language fallback for null and "". Whitespace remains unchanged. Fallback affects reads in SQL and RAM cache; writes still target the selected translation and [Required] continues to constrain stored values. See Default-language fallback for examples and query behavior.

DefaultValue defines a database default; it is not a general initializer for an object returned by Create(). Assign values the application needs explicitly. See Schema Synchronization for adding required fields to populated tables.

Read-only and computed properties

ReadOnly(true) leaves the setter available for initialization. Later changes are rejected on save, including changes to individual translations. This is a persistence rule and does not add a SQL constraint that prevents another application from editing the column.

NotMapped can expose a computed interface getter, as above. Evaluate it after loading the entity. A query using that property may not translate to SQL; a C# getter is not automatically a SQL expression.

Concurrency

Load the existing entity before editing it so that its concurrency token is available. Timestamp uses a generated byte[] rowversion. ConcurrencyCheck uses the supplied value of the annotated property as the expected stored value. Keep that token unchanged while editing other fields: Blueprint does not retain a separate change-tracker copy of the value originally read. If another writer changes the protected row, saving can throw DbUpdateConcurrencyException.

Queued updates and deletes in a DatabaseTransaction check affected rows and concurrency tokens. A missing target row also fails the transaction. Handle the conflict by reloading and deciding whether to retry with a new transaction; do not silently overwrite the other writer's changes.

A static predicate delete such as Product.Delete(item => item.ID == productID) expresses a SQL filter. It does not carry a previously loaded entity's rowversion; use a queued entity delete when that concurrency check is required.

Related topics

EShop - Checkout Tutorial · Relationships · Schema Synchronization · Transactions

Clone this wiki locally