Signum Framework

Modeling

Entities

Operations

Mixins & Symbols

• Entities are the basic building blocks of any Signum Framework application. They represent the shape of the data in the database and, most of the time, also influence the way the user interface looks.
• Operations are the most convenient way to let end-users create and manipulate entities.
• Mixins and Symbols allow shared-code to be more flexible, pushing code-reuse to the limits.

Designing entities

The entities are classes written by hand in C#, using a set of base classes, attributes and collection that serve us as standard building blocks.

• Entity: Base class to create new entity types
• EmbeddedEntity: Base class to create small entities that will be stored in-line in the parent entity. Similar to database value-types.
• Lite<T>: It is a type-safe identity card for an entity. Stores the Id and ToString and it is the only mechanism for lazy-loading. Allows inheritance using covariance. Massively usefull (Combobox items, Autocomplete, Search control, many APIs,...).
• MList<T>: Alternative to List<T> for entity properties. Keeps track of changes and optionally preserves ordering in the database. T can be any type (e.g., entities, embedded entities, Lite<T>, or values).
• Values: Any simple data type that can be part of an entity property (e.g., strings, numbers, nullable values, enums, date, times and any UDT like geographic data).

This standards simplify your code dramatically, providing good default behaviors in the user interface, allowing generic programming in the business logic, and ensuring easy integration and good performance at the database schema.

Additionally, the entities type and properties are localizable. This way the consistency in the user interface is guaranteed and there are less messages to translate, sharing a common language with non-English speaking users.

Entities change

Entities play a central role in any application built with Signum Framework: database schema, business logic, queries, windows and web user interfaces, tests and even documentation depend on the way the entities have been designed.

Unfortunately... the entities are the ones that suffer more changes. When a new property is created, removed or renamed, it will affect all the dependent layers and there’s no dependency injection mechanism that can protect you from that.

By using statically typed code, and schema and documentation synchronization, we can absorb this impacts and let the entities change if necessary, keeping the artificial mismatch between what the users sees and how the information is structured to a minimum.

Powerful Validation

One of the main responsibilities of the entities is defining their validation rules. This rules will be checked before saving the entity, and the same rules will also be shown in the windows or web user interface, removing redundancy.

Signum Framework provides a wide range of options available to define this rules:

• Simple rules using attributes over the properties.
• More complicated rules using imperative C# code (with or without database access).
• Tables to define mandatory properties depending on the entity state.
• ...or even inject contextual validation rules to child entities.

All this rules can be overridden if the module is not written by you, and there’s support to disable any rule on entities loaded from legacy applications.

Embedded Change Tracking

Additionally, all the entities have a built-in change tracking system to commit only the necessary changes when the entity is saved in the database.

This mechanism lies in the entity itself, not in an external context. That means the entities can be safely serialized and sent to remote client applications, and still have change tracking and concurrency control working when they turn back.

Exposing the data

In today application is common that the database schema, the way the information is structured, is hidden for the end-user behind complicated naming conventions, table and column with out-dated names or not used anymore, or user interfaces that, trying to simplify some user case, complicate the overall picture.

While some of this decisions could be justified in some particular cases, in is necessary for power users to understand the data, so they can explore the information, design reports and, ultimately, share a common languages with the developers.

Signum Framework removes the technical impediments that keep the data hidden to the world, but gives you the security mechanisms to protect this data when necessary.

Operations

Types of Operations

Operations are actions to create and manipulate entities, and are available in the user interface. There are five types of operations:

• Construct: Create a new entity with no additional context (e.g., Create new Invoice)
• ConstructFrom: Create a new entity from another one (e.g., Create Invoice from Customer)
• ConstructFromMany: Create a new entity from many others (e.g., Create Invoice selecting Products)
• Execute: Modify an entity (e.g., Authorize Invoice, Cancel Invoice)
• Delete: Delete an entity from the database (e.g., Delete Order)

Most operations contain, not only the code that will run when executed, but also code to check the operation pre-conditions (CanExecute), returning an error message if not.

Additionally, operations can be embedded in a state machine, where each operation represents a transition between the states of the entity.

Advantages

While operations could be manually implemented using manual UI buttons/commands and business logic, they have important advantages that make them a more convenient way to creating and manipulate entities:

• Operations are defined in the Server, but create automatic buttons in the entity UI (or context menu on the search dialog) for Windows and Web applications.
• When the pre-condition is not satisfied by the entity, the button (or context menu) is disabled, and a useful tooltip with the message is shown to the end-user.
• Operation store a log every time they are executed, with the start and end dates, user, related entity, and maybe an exception.
• They can be overridden if special behavior is necessary in complex class hierarchies.
• Their implementation can also be replaced, making each operation an extensibility point.
• They all can share a common set of Web Service Operations (Windows) or Controller Actions (Web) saving you code.
• They are automatically transactional.
• When using Authorization module, they can easily be allowed / disallowed for certain roles.
• When using Processes module, they can easily be executed for multiple entities at once, using a context menu in the search dialog.

Mixins & Symbols

Once you start including in your database entities designed in third-party modules new challenges appear. We have created some new patterns to solve this challenges.

Mixins and Symbols let us push code-reuse to the limits, without scarifying a static-typed programming experience.

Mixins

In statically-typed languages like C# is not possible to add extra members to type without inheriting from it (creating a new, different type). Extensions method can add new functions, but adding new fields/properties (and database columns) requires changes in the memory layout of the entity, and there is no standard alternative to do it.

Using MixinEntity we have an standart mechanism to add new fields, properties or methods to any entity. Mixins are just like a EmbeddedEntity attached to the end of an entity.

When an entity is created, all the registered mixins for this entity type are attached to the end of it, and there is no way to remove them. Mixins are like limpets, so you can trust that your entity will have the new properties defined in the mixin.

Attached mixins have no name, and are accessible by type. Entities can have many mixins, but not two mixin of the same type.

Mixins are fully supported at all levels of the framework (e.g., ORM, LINQ, Window/Web user interface, Dynamic queries, Authorization ...) and their properties are indistinguishable from normal properties for the end-user.

There are extension points to modify third-party operations and (windows and web) user interfaces to make use of the new fields provided by the mixin.

Symbols

Enums are a common data-type to define a fixed amount of different values. Under the cover they are just numbers, but with a special superpower: Calling ToString on an enum value returns the name of the field where is was declared, not the underlying int. Enum values always remember their type and the field where they were declared.

Unfortunately, enums are not very flexible : There’s no way to add new values to an enum already declared in a third-party library. When this is necessary, the typical solution is to use magic strings instead of enums. But strings are not strongly typed: no auto-completion, no rename, no compile-time errors…

Symbols solve this problems. You can declare a new symbol type just by inheriting from Symbol, but you can declare new symbol fields/instances in any static class. Moreover, they inherit their name and type from the field where they were declared, just like enums.

Also, symbols are entities, so can be reference by other entities easily and with referential integrity. Moreover, the schema synchronizer understand and synchronizes the used symbols.

This features make symbols a replacement for magic strings that are as easy to use as enums and can be referenced in the database. They are simple read-only entities that are usually related to a piece of code in a dictionary, creating a strongly-typed bridge between code and data. (e.g.,Operations, Permissions, Process algorithms, etc... are all symbols) .

Database

ORM

Schema Sync

Avoid inline SQL queries without compromises:

• Signum Framework has a performant fluent ORM to store in-memory entities. Cycles? no problem.
• LINQ to Signum will brow your mind: Correlated sub-queries, extension methods, batch deletes/updates/inserts and much more....
• The Schema Synchronizer can adapt the database schema to your application, understanding renames, and with no additional meta-data. Trouble-free database evolution with multiple branches.

Avoid inline SQL

While SQL is the gold standard in database manipulation, it has some important flaws that make using it, especially from general purpose programing languages like C#, inconvenient.

Writing inline INSERT/UPDATE/DELETE in SQL is error-prone due to the lack of auto completion, and once the query is made, it will easily get out-dated when some field or table is renamed, creating bugs that won’t be catch at compile time. SQL Injection is also a source of security problems.

Database class

The most classical part of the ORM in Sigum Framework is represented by the Save extension method in Database static class. Still, under its simplistic appearance, it contains some interesting features:

• It allows saving arbitrary object graphs with cycles, polymorphic references and collections.
• Because entities and MList<T> have embedded change tracking, only the changes are commited.
• Before saving, it analyzes the object graph to validate that all the entities satisfy the validation rules.
• Under the covers, it uses run-time code generation/compilation to create fast INSERT/UPDATES calls to ADO.Net (just as the ones you could written).
• It has a built-in mechanism to avoid concurrency problems when two users changes the same entity at the same time.
• In order to improve performance when saving collection of entities, it generates bulk insert and update statements, but it does so generating stable statements that can be cached by the database query planner .
• Because there is no Context class, Save can be an extension method on a static class, becoming a nice fluent API.

LINQ

LINQ to Signum

Traditionally, an ORM is a library that let you manipulate database rows as if they were objects. While this is a convenient strategy for individual rows, it can cause performance problems when many rows are required, like complex queries and bulk inserts/updates/deletes.

LINQ (Language INtegrated Queries) is a technology invented by Microsoft to write queries in C# to in-memory object (like many other functional languages) and also to the database, requiring a library to translates a C# query to SQL (LINQ Provider).

LINQ queries are really powerful, letting you express complex operations (e.g., Joins, groupings, aggregates, correlated sub-queries, etc… ). Because of this, translating a LINQ query to SQL is a challenge comparable to write SQL compiler.

In Signum Framework we’re proud to have developed one of the most powerful LINQ Providers available.

Module-friendly Syntax

One difference between LINQ to Signum and other LINQ providers is that, instead of a property for each table, a generic method is used to access the tables.

This is important because this way your query is not tied to a particular Context / Database Schema, just some tables being there. This allows vertical modules to work in any other application.

Typical features

Here is a small resume of the typical features of a LINQ Providers that LINQ to Signum also support:

• Supports all the standard query operators (Select, Where, SelectMany, OrderBy, ThenBy , GroupBy, Join, Distinct, Skip , Take, etc...), aggregates (Count, Sum, Min, Max and Average) and collection-to-instance operators (Single, SingleOrDefault, First, FirstOrDefault, etc...).
• Support for the common .Net methods for string manipulation, math operations, date-time, etc…
• Automatic LEFT OUTER JOIN navigating object relationship through properties, simplifying all the joins through Foreign Keys (95%).
• Allow mixing in-memory objects and SQL statements seamlessly by automatically creating parameterized queries (avoiding SQL injection) and complex object graph materialization.
• Full support for enums.

Powerfull features

And here are some nice features that you couldn’t in other LINQ Providers:

• Bulk DELETE/UPDATE/INSERT directly with LINQ syntax, without materializing the entities. Of course, validation does not work in this case:
• Correlated sub-queries to retrieve hierarchical data, avoiding the N + 1 problem.
• Create expression properties/method that will be expanded on the query, letting you factor-out code for in-memory and in-database scenarios.
• Full support for inheritance/interface implementation using casting, polymorphic references (implemented with CASE or UNION statements), or GetType() method.
• Support for simple in-database property navigation using InDB extension method.
• Simpler syntax for writing LEFT/RIGHT/FULL OUTER JOINS.
• Extension points to allow filtering the visible rows transparently, to enforce security restrictions (used by Authorization, Disconnected and Isolation module).
• Extension point to allow automatic query simplification for cached master data (used by Cache module).

Schema Sync

Schema Generation

Signum Framework is able to generate the full database schema for the set of registered modules in the application, including:

• Tables: For any entity, MList<T> property, or enum referenced by entties.
• Columns: Determining SqlDbType, nullability, size and precission (and default constraints for sync)
• Indexes: Simple and multi-column unique indexes, and recommended non-unique indexes on foreign keys.
• Foreign keys: For any simple or polymorphic entity relationship.
• Rows: for some special tables
  • Enums
  • Symbols
  • Types
  • Queries
  • ...

Schema Synchronization

One of the most popular features of Signum Framework is the ability to, not only generate the schema for the the application, but also synchronize the schema to the one required by the application as it evolves.

The strategy is quite simple: A console application compares the current application with the current schema and asks the user for potential renames. At the end, it generates a SQL Script with the necessary changes, and the end user can review it, execute it, or store it for using it in the next deployment to production.

Since the synchronization mechanism doesn’t require any metadata information (like Migrations do) it’s much easier to collaborate with developers working in other branches.

It’s also easier to ensure that, when deploying to production, the database schema match perfectly with the application: Just sync one more time and check that no script is generated.

The Schema Generation/Synchronization infrastructure is expansible, letting modules do custom logic if necessary (e.g., UserQueries, UserCharts, EmailTemplates, ...)

User Interface

Windows & Web

Entity controls

Search control

• Signum Framework has been designed to provide first class support for Windows and Web user interfaces using the latest technologies on each field.
• Signum.Windows and Signum.Web provide a set of base Entity controls that, taking advantage of the rich entities, provide good default behaviors that make writing user interfaces a breeze.
• Both also provide a powerful Search control that lets end-user take advantage of a big subset of the LINQ provider in a user-friendly interface.

Both Signum.Windows and Signum.Web have been designed to create a standardized user interface for administrating entities with the focus put on being productive. This design, however, is completely customizable and flexible enough to satisfy all the user interface requirements in back-office scenarios.

In both cases, we use the latest technologies that we can expect a developer to know, so they can take advantage of their previous knowledge and not sacrifice their creativity.

Signum Windows

Signum.Windows takes advantage of WPF and XAML to build native windows experiences. It makes use of typical WPF concepts like Bindings, Templates and Styles.

Since the entities already implement INotifyPropertyChange, there is no need to create a ViewModel and by using Operations there’s no need to create WPF Commands, radically simplifying the necessary amount of code.

Typically, a WPF UserControl is associated with each entity type, contains one line of XAML for each entity property, and no code behind.

Signum Web

Signum.Web, on the other side, takes advantage of ASP.Net MVC 4.0 and Razor to create views in HTML5 for each entity. Using HtmlHelpers, a similar experience is provided in web, typically requiring one line of C# for each entity property.

The user interface is based on the popular Bootstrap 3.0 framework and can be customized with any of the available Bootstrap themes, or using CSS 3.0. Charting and Profiler modules in Signum Extensions also make use of D3.js.

In order to modify the client-side behavior of the application, Typescript and Require.js are used, ensuring best scripting experience and future maintainability.

The web user interface is designed to allows creating complex Line of Business forms, embedding sub-entities in the same page or opening pop-ups to view the details. Mappings allow fine grained control materializing a complex graph of entities from a HTTP POST FORM .

For front-office scenarios, typically web sites exposed to company customers, entity or search controls can still be used or in the worst case, where a more radical design is appropriate, you’ll still be able to develop this interface in the same application and using the same technologies. This is a big advantage over integrating with closed packages. 

Entity Controls

Entity Controls are controls specifically designed for manipulating entity properties. Taking advantage of the rich meta-data available in the entities they get good default behavior.

Most of the times, only one line of code per property is necessary to write a Windows and Web user interface for an entity, but there are extension points to add special behavior or, since they are just controls inside a XAML/HTML file, they can be easily replaced or combined with other custom controls.

Value Controls

For example, simple controls to manipulate value properties are auto-configured using ValueLine control:

1. The right control is choose depending the property type: TextBox, NumericTextBox, ComboBox, Date/TimePicker, ColorPicker, etc...
2. Entity controls take their labels from the localized name of the entity property.
3. ValueLine takes format and unit from the property attributes FormatAttribute and UnitAttribute.
4. Controls take advantage of the entity validation mechanism to inform the user the exact place where there’s an invalid input.
5. The controls automatically became read-only for read-only properties.
6. Additionally, there are extension points to make the controls invisible or read-only depending specific rules (used by Authorization and Disconnected module).

Entity Refereces and Collections

There are also Entity controls specifically designed to manipulate entity references, each optimized for a special user cases:

• EntityCombo: Select and entity from a small list of possible ones.
• EntityLine: Select an entity from the database using auto-complete.
• EntityLineDetail: Select or create an entity and show its content embedded in the parent window.

This entitiy controls also have some standard buttons for common actions:

• Create a new entity in a popup or embedded control.
• Find an existing entity using a Search control popup.
• View the current entity in a popup (if not embedded).
• Remove the current entity.

There are also Entity controls designed to manipulate list of entities, using similar buttons and, optionally, allowing re-ordering the entities with the Move button:

• EntityList: Find or create entities and show them in a list.
• EntityStrip: Find entities using auto-complete and show them in tag-like list.
• EntityRepeter: Create entities and show them in-line.
• EntityTabRepeater: Crete entities and show them in different tabs.

On this controls, designed to manipulate entity references or collections, even more default behavior can be inherited from the entity properties:

1. Create/View buttons are automatically hidden depending the type of the property and its role in the application (EntityKind). Even for polymorphic properties that could reference entities of different types.
2. Find button is automatically hidden depending if the type (or types) of the property have a query defined.
3. EntityLine and EntityStrip autocomplete is automatically setup to look for entities of matching types and, when Authorization module is enabled, filtering out the entities not visible by the user.
4. EntityLineDetail, EntityRepeater or EntityTabRepeater can look for the associated control of the current entity automatically, even for polymorphic properties.
5. All the controls for manipulating collections can show Move button depending if PreserveOrderAttribute is set in the MList<T> property.

All this sensible default behavior, inherited from the entities, can be overridden if necessary but most of the times works out the box. The end result is a dramatically increase in developer productivity and a flexible and consistent user interface.

Example Windows Control

Example Web Control

Search control

Video: Search Control in Signum Framework

Description

LINQ (or SQL) is powerful languages. With them, developers express complex queries to fill tables, draw charts and create reports.

Unfortunately, most of the applications trim down all this expressivity power to end-users. At most, they give them few options:

• Filter by a small set of previously-defined fields
• Order columns
• Control pagination

Search control

Our SearchControl build on top of the DynamicQueryManager, can do some useful new tricks:

• Navigate to related entities, the columns of the search control can not be basic types (e.g., numbers, strings, dates,...) but references to entities (Lite<T>), allowing navigation and filters with auto-complete.
• Remove any column, simplifying the underlying query.
• Add any arbitrary column that is accessible from the current query, creating the necessary join as the user navigates through properties.
• Filter by any arbitrary column, using in each case the right set of comparison operations depending of the type of the selected column.
• Navigate through collections for adding filters (Any, All, None, AnyNot) or multiply the results (Element).

Dynamic Query Manager

The DynamicQueryManager is cool technology that, using a simple sequence of combo boxes, lets the end-user express easily complex queries.

Since it’s just a sequence of combo boxes, and the names of the properties are localized, this query language is simple enough for any power user to understand.

The DynamicQueryManager is build on top of LINQ to Signum and, while not as expressive as SQL or LINQ, it reduces the gap considerably, giving user much more power and freedom without complicating the simple use cases.

Of course, this freedom can be reduced depending on the user role, or augmented registering LINQ expression method or properties in the DynamicQueryManager.

To use the Search Control, just register a query in the DynamicQueryManager , this will be the base query for the user to modify:

Demo of Web Search Control

This small demo show how the Web SearchContol manage:

• Ordering and Multiple Ordering
• Pagination
• Quick filters
• Remove columns
• Add new columns (even photos!)

Demo of Windows Search Control

Here we use the Windows SearchContol to manage collections:

• Add the Count column
• Add columns inside the Elements of the collection, multiplying results.
• Filtering using Any operator, without multiplying results.

Legacy Videos

Philosopy

0 Basics

1 Entities

2 Logic

3 Windows

This videos were made in 2009 and are now a little bit outdate.

Still, they are the most entertaining way to know the philosophy and learn the basics of the Signum Framework, but keep in mind Patch Notes!.

Enjoy them!

Description

Cartoon animation explaining the philosophy behind Signum Framework:

• The historical context: ORMs and Linq
• What Signum Framework offers to the development of data-centric applications.
• Finally, a very concrete example shows how Signum Framework simplifies the development and maintenance of an hypothetical application.

Description

This is the Getting Started Tutorial to get used with the ORM doing simple things in a Console Application.

We will learn to:

• Model a simple entity class
• Create the database
• Create an entity object using object initializers
• Save the entity
• Retrieve the entity in many different ways (Retrieve, Query or through Lite)

Description

This is the first of three tutorials that will show you how to build an application for a shop.

In this tutorial we explain:

• The typical architecture of a client-server system
• How to create all the projects using the Signum Framework Client - Server Template Project
• How to model the entities, the first and more important step when building an application using Signum Framework

Description

This is the second of three tutorials that will show you how to build an application for a shop.

In this tutorial we explain how to:

• Create the database
• Load legacy data
• Write the business logic
• Set-up the web server that will be used by the client applications

Description

This is the third and last tutorial that will show you how to build an application for a shop.

In this tutorial we explain:

• Create UserControls for our entities using the Signum Entity Control Item Template.
• Associate controls to entities in the navigator.
• Write Linq queries in the server that will be used by the search windows.
• Customize an UserControls for an entity.
• End of course surprise :)