DEV Community: Theodoros Bebekis

Fundamental Concepts of Business Applications IV: Building a Locator

Theodoros Bebekis — Tue, 07 Jul 2026 12:04:31 +0000

From declaration to runtime

In the previous parts we examined the problem: a business application needs a reliable way to turn a human reference into a business entity.

A user types a customer code, a product name, a tax number, an external identifier, or a fragment of a description. The application needs to arrive at something stable: the canonical identity of the record.

That is the role of the Locator.

In the previous article we saw how a Locator can be described declaratively. We described fields, search fields, result fields, key field, and policies. But a definition by itself is just data. It needs a runtime.

In this article we move to the practical part:

Locator Definition
        ↓
Runtime Request
        ↓
Execution Engine
        ↓
Locator Result

We will see which objects are needed, what their roles are, how they cooperate, and how a declarative definition becomes an executable mechanism.

The article uses the Locator as a case study, but the idea is broader. Many business frameworks follow the same path: we describe something declaratively and then build a runtime that can execute it.

1. The problem solved by the Locator

In a sales application, the user may type:

ALFKI

or:

Alfreds

or select a row from a result list.

For the UI, these look like text input or a dropdown selection. For the business layer, they are something else: an attempt to resolve a reference.

The application wants to answer:

Which record does this refer to?
Is there exactly one record?
Are there multiple records and should the user choose one?
Is the search too broad?
Is the request invalid?
Is there a context problem, such as wrong company or permissions?

If this logic stays inside event handlers, SQL snippets, or controllers, the system fills with repetition and special cases. The Locator provides a stable runtime contract.

2. The basic runtime pieces

A Locator needs five basic objects:

LocatorDefinition
LocatorRequest
LocatorContext
LocatorEngine
LocatorResult

Their roles are clear:

LocatorDefinition: describes what the locator knows.
LocatorRequest: describes what the caller is asking for now.
LocatorContext: carries runtime information.
LocatorEngine: executes the process.
LocatorResult: returns outcome and data.

These objects are the minimum runtime model. They are more than classes for organizing code: they are the boundaries of the mechanism.

3. LocatorDefinition

The definition is the declarative part.

A simple shape:

public class LocatorDefinition
{
    public string Name { get; set; }
    public string ClassName { get; set; }
    public string Source { get; set; }
    public string KeyField { get; set; }

    public List<LocatorFieldDefinition> Fields { get; } = new();
    public List<string> SearchFields { get; } = new();
    public List<string> ResultFields { get; } = new();

    public int MinimumSearchLength { get; set; }
    public int MaximumResultCount { get; set; }
    public string OrderBy { get; set; }
}

Example:

var customerLocator = new LocatorDefinition
{
    Name = "Customer",
    ClassName = "SqlLocator",
    Source = "Customer",
    KeyField = "Id",
    OrderBy = "Name",
    MinimumSearchLength = 2,
    MaximumResultCount = 50
};

customerLocator.AddField("Id", FieldType.String);
customerLocator.AddField("Code", FieldType.String);
customerLocator.AddField("Name", FieldType.String);

customerLocator.AddSearchField("Code");
customerLocator.AddSearchField("Name");

customerLocator.AddResultField("Id");
customerLocator.AddResultField("Code");
customerLocator.AddResultField("Name");

This code describes the Locator. Search, connection, UI, and result state belong to the runtime.

The definition answers:

What is the locator name?
Which engine will execute it?
Which source will the engine use?
Which field is the canonical identity?
Which fields participate in search?
Which fields are returned?
Which policies apply?

The definition stays stable. The request and context change on every execution.

4. Name, ClassName, and Source

The three fields Name, ClassName, and Source are easy to confuse, so it is worth separating them.

Name
    locator identity in the registry

ClassName
    engine/handler type that will execute the definition

Source
    provider-specific source used by the engine

Name is the registry key:

Customer

The runtime uses it to find the definition.

ClassName selects the engine:

SqlLocator
ServiceLocator
ObjectLocator

Source is input to the engine. For a SQL engine it may be a table:

Customer

or a select:

select Id, Code, Name
from Customer
where IsActive = 1

For a service engine it may be an endpoint:

/api/customers/search

For an object engine it may be the name of an in-memory collection.

The architecture remains provider-neutral. Interpreting Source belongs to the engine.

5. LocatorRequest

The request is the runtime intention of the caller.

A simple shape:

public class LocatorRequest
{
    public object KeyValue { get; set; }
    public string SearchTerm { get; set; }
    public string SearchField { get; set; }
    public bool IsMultiRow { get; set; }

    public LocatorContext Context { get; set; } = new();
}

KeyValue is used when the caller already has a possible canonical identity and wants to load or verify it.

SearchTerm is used for text search.

SearchField optionally limits the search to a specific field.

IsMultiRow gives a hint about the UI scenario, for example a grid lookup instead of a simple editor.

The request expresses the caller's intention. Fields, policies, and source belong to the definition.

The request says:

I want to resolve this now.

6. LocatorContext

The context carries runtime conditions.

The same search may produce different results per company, branch, tenant, language, connection, date, or user permissions.

A practical shape:

public class LocatorContext
{
    public string LocatorName { get; set; }

    public Dictionary<string, object> Parameters { get; } = new();
}

Example:

request.Context.LocatorName = "Customer";
request.Context.Parameters["CompanyId"] = currentCompanyId;
request.Context.Parameters["Language"] = currentLanguage;
request.Context.Parameters["ConnectionName"] = connectionName;

The dictionary is a practical choice. The context works as a runtime carrier, not as an entity schema. It needs room for parameters that vary per application or provider.

In stricter implementations there may be a strongly typed context. The basic contract remains the same: the context brings information that affects execution.

LocatorName in the context is registry identity. The runtime uses it to find the definition.

7. LocatorResult

The result is an outcome, not just a list.

A search function usually returns rows. A Locator must return the state of the resolution attempt.

A simple shape:

public class LocatorResult
{
    public LocatorResultStatus Status { get; set; }
    public string Message { get; set; }

    public object Data { get; set; }

    public int Count { get; set; }
}

The basic states:

public enum LocatorResultStatus
{
    None,
    InvalidRequest,
    InvalidContext,
    NoResult,
    SingleResult,
    MultipleResults,
    TooManyResults,
    Error
}

The distinction has practical value:

NoResult: the request was valid, but the search returned an empty result.
SingleResult: one record was found and the reference was resolved.
MultipleResults: a small set of records was found and the user can choose.
TooManyResults: the search was too broad.
InvalidRequest: input is missing or invalid.
InvalidContext: the runtime context is incomplete or incompatible.
Error: a technical or unexpected failure.

The UI can react differently to each state.

For example:

SingleResult
    write CustomerId and related fields

MultipleResults
    show selection list

TooManyResults
    ask for more characters

NoResult
    show message or allow new record

This is where the Locator becomes a business mechanism instead of a simple search helper.

8. LocatorEngine

The engine executes.

A clean contract:

public abstract class Locator
{
    public abstract LocatorResult Execute(
        LocatorDefinition definition,
        LocatorRequest request);
}

The engine receives a definition and a request. The context is inside the request.

Its role:

Validate Request
Read Definition
Apply Context
Resolve
Produce Canonical Identity
Produce Projection
Determine Result State
Return Result

The implementation may be SQL, service, object, cache, directory, or something else.

The contract remains the same.

9. Facade, Registry, and Factory

The caller needs a simple entry point.

The facade takes responsibility for:

find definition
validate definition
create engine
execute engine
interpret result

It needs an application-level service.

Example:

public static class Locators
{
    public static LocatorResult Execute(LocatorRequest request)
    {
        if (request == null)
            throw new ArgumentNullException(nameof(request));

        if (request.Context == null)
            return LocatorResult.InvalidContext("Missing locator context.");

        if (string.IsNullOrWhiteSpace(request.Context.LocatorName))
            return LocatorResult.InvalidContext("Missing locator name.");

        LocatorDefinition definition =
            LocatorRegistry.Get(request.Context.LocatorName);

        definition.Check();

        Locator locator =
            LocatorFactory.Create(definition.ClassName);

        return locator.Execute(definition, request);
    }
}

The roles:

Registry: finds a definition by locator name.
Factory: creates an engine based on ClassName.
Facade: gives the caller a simple entry point.
Engine: executes resolution.

This keeps UI and callers clean.

10. The execution pipeline

Now let us look at the pipeline as practical steps.

Caller
  ↓
LocatorRequest
  ↓
LocatorContext.LocatorName
  ↓
LocatorRegistry
  ↓
LocatorDefinition
  ↓
LocatorFactory
  ↓
LocatorEngine
  ↓
LocatorResult

Validate Request

The engine checks input first.

Example:

if (request.KeyValue == null &&
    !string.IsNullOrWhiteSpace(request.SearchTerm) &&
    request.SearchTerm.Length < definition.MinimumSearchLength)
{
    return new LocatorResult
    {
        Status = LocatorResultStatus.InvalidRequest,
        Message = "The search term is too short."
    };
}

The limit lives in the definition. The check happens at runtime.

Read Definition

The engine reads:

Source
KeyField
SearchFields
ResultFields
Policies

The definition provides materials and rules. The engine decides how to use them.

Apply Context

The context may select connection, company, tenant, language, or permissions.

The same definition can execute differently per context.

Resolve

This is the provider-specific part.

In a SQL engine, a query is produced.

In a service engine, a service call is made.

In an object engine, a collection is searched.

The result of this step is raw resolved data.

Produce Canonical Identity

The Locator targets canonical identity.

KeyField declares which field plays that role.

KeyField = Id

The user may have typed a code or name. The system ultimately wants Id.

Produce Projection

Often the caller needs additional fields:

Id
Code
Name
TaxNumber
PaymentTermId

ResultFields define that projection.

The projection belongs to the result.

Applying those fields to a target row or target object is the job of another component, usually a mapper.

Determine Result State

The engine decides the status.

Example:

if (count == 0)
    status = LocatorResultStatus.NoResult;
else if (count == 1)
    status = LocatorResultStatus.SingleResult;
else if (count > definition.MaximumResultCount)
    status = LocatorResultStatus.TooManyResults;
else
    status = LocatorResultStatus.MultipleResults;

The result state drives the UI and the workflow.

Return Result

The result returns:

Status
Message
Data
Count

Data may be a table, DTO list, object list, or another container. That is an implementation concern.

11. SQL-based engine

In many business applications the first engine will be SQL-based.

That is practical, while the architecture remains provider-neutral.

For a SQL engine, Source may be a table:

Customer

or a select:

select Id, Code, Name
from Customer
where IsActive = 1

A SELECT as source is a convenience of the SQL implementation. It fits because SQL is a declarative language. It describes a result, not imperative steps.

Other engines will interpret Source differently.

The shared contract stays stable.

12. Declarative policies

Policies belong to the definition:

MinimumSearchLength
MaximumResultCount
OrderBy

The engine applies them.

MinimumSearchLength protects against overly short searches.

MaximumResultCount protects the UI and backend from oversized result sets.

OrderBy determines presentation.

The definition declares. The engine executes.

That is the essence of the runtime model.

13. Resolution states in practice

The states deserve special attention because they directly affect the UI.

NoResult

The request executed and the search returned an empty result.

The UI may show a message, clear the field, or suggest creating a new record.

SingleResult

The reference was resolved cleanly.

The caller receives canonical identity and result fields.

MultipleResults

There are multiple records, but the count is manageable.

The UI shows choices.

Example:

SearchTerm = John
Result count = 5

TooManyResults

There are many records and the search is too broad.

Example:

SearchTerm = s
Result count = 500
MaximumResultCount = 50

The UI asks for more specific input.

The distinction from MultipleResults is critical:

MultipleResults
    show choices

TooManyResults
    ask for narrower search

InvalidRequest

The input is invalid.

Examples:

Search term too short
Unknown search field
Missing required input
Invalid key value type

InvalidContext

The context is missing, incomplete, or incompatible with execution.

Examples:

Missing company
Missing tenant
Invalid connection
Insufficient permissions
Unsupported language context

Error

A technical or unexpected failure.

Examples:

Database error
Service unavailable
Timeout
Serialization error
Unexpected exception

Business states and technical errors should stay separate.

14. Extensibility

Extensibility comes from the boundaries.

The definition is declarative.

The request is runtime input.

The context is runtime environment.

The result is outcome.

The engine is interpreter.

With these boundaries, we can have many engines:

SqlLocator
ServiceLocator
ObjectLocator
CacheLocator
DirectoryLocator
GraphLocator

All of them implement the same basic contract:

public abstract class Locator
{
    public abstract LocatorResult Execute(
        LocatorDefinition definition,
        LocatorRequest request);
}

The application continues to call Locators.Execute(request).

The engine change happens behind the definition.

This is practical extensibility. The caller stays free of if/else logic for every provider.

15. Mapper: a neighboring component

When the user selects a record, more than one field is often updated.

Example:

CustomerId
CustomerCode
CustomerName
PaymentTermId
VatRegimeId

The Locator answers:

Which record corresponds to this reference?

The Mapper answers:

How are the result fields written to the consumer?

The Mapper consumes LocatorResult. It is a neighboring mechanism, outside the Locator core.

It deserves a separate article because it has its own concerns: field mapping, target object, target row, validation, overwrite policy, and transactional behavior.

16. Result materialization

The Data of the result is an implementation detail.

In a SQL engine it may be a table.

In a service engine it may be a DTO list.

In an object engine it may be an object list.

The contract asks for:

Status
Message
Data
Count

The container is selected by the implementation.

This keeps the pattern clean.

17. Conclusion

The Locator starts from a practical business problem: how a user reference becomes a stable business identity.

The solution needs more than a search function.

It needs a runtime contract:

LocatorDefinition
        ↓
LocatorRequest
        ↓
LocatorContext
        ↓
LocatorEngine
        ↓
LocatorResult

The definition declares.

The request asks.

The context carries runtime conditions.

The engine interprets and executes.

The result returns outcome and data.

This model gives clear boundaries:

The UI sends a request and reads a result.
The registry finds the definition.
The factory creates an engine.
The engine applies policies and provider-specific logic.
The result says what happened.

The same grammar appears in many parts of a business application framework:

Problem
        ↓
Architectural Concept
        ↓
Declarative Definition
        ↓
Executable Runtime Model
        ↓
Concrete Implementation

The Locator is a good example because it is small, useful, and complex enough to show the pattern clearly.

A Locator is only one example. The important idea is the transformation itself: a declarative description becomes an executable runtime model. Once that pattern is established, the same architecture can be applied to forms, reports, workflows, validation rules, document handlers, and many other business components. The Locator simply provides a compact case study of a much broader architectural principle.

In the end, the goal is something larger than another helper class: a mechanism that can be reused, extended, and integrated into different UIs, data sources, and business workflows.

Fundamental Concepts of Business Applications III: Locator Definitions

Theodoros Bebekis — Mon, 06 Jul 2026 09:37:25 +0000

In the previous article, we argued that a Locator is neither a UI control nor a search mechanism. It is an architectural concept that resolves business references within a specific business context and transforms them into canonical business identities.

If that is true, however, an obvious question immediately follows.

How can a Locator be described?

Not how it is implemented.

Not how it is executed.

But how it can be described independently of any particular implementation.

This question is more important than it may seem at first glance. If two different development teams decide to implement a Locator, how can they be sure they are implementing the same concept? How can we discuss a Locator without referring to a particular library, programming language, or framework?

The answer is that, like any mature architectural concept, a Locator must first be separated from its implementation.

This distinction appears repeatedly throughout the history of software engineering.

Relational theory existed before relational database systems.

SQL does not describe how a query will be executed. It describes only the result we want to obtain. The choice of indexes, execution plans, and optimization algorithms is the responsibility of the query optimizer.

Exactly the same principle applies here.

A Locator should not be defined by the mechanism that implements it.

It should be possible to describe it independently of that mechanism.

This naturally leads to three distinct levels of abstraction.

Locator Pattern
        │
        ▼
Locator Definition
        │
        ▼
Execution Engine

The Locator Pattern is the architectural concept itself.

The Locator Definition is the declarative description of a particular resolution process.

The Execution Engine is the component responsible for interpreting that description and performing the actual resolution.

Each level has a different responsibility, and they should never be confused with one another.

This means that a Locator Definition is not an implementation artifact. It is neither a class, an API, a SQL query, nor a UI component.

It is a declarative description of a business reference resolution process.

Or, if you prefer, it is the contract that defines what it means to resolve a particular business reference without describing how that resolution should be performed.

This naturally leads to the next question.

What is the minimum amount of information required to describe a Locator completely?

The answer is that every Locator Definition must answer a small number of fundamental questions.

1. What can be resolved?

Which business entity is being resolved?

A Product?

A Customer?

A Warehouse?

An Account?

Notice that we are not talking about database tables or object-oriented classes.

We are talking about business concepts.

2. How can it be referenced?

How can users refer to that entity?

By code?

By name?

By barcode?

By registration number?

By account number?

These references represent the user's language rather than the internal language of the information system.

3. Under which business context?

The same business reference may represent different entities depending on the business context in which the resolution takes place.

The company.

The warehouse.

The customer.

The transaction date.

The active price list.

The actual values of this context belong to runtime. A Locator Definition does not contain those values. It merely describes that the resolution process may depend on them.

4. What is the canonical result?

If the resolution succeeds, what is the canonical business identity that is produced?

From that point onward, the rest of the application can safely use this identity without knowing how it was obtained.

5. What information becomes available after successful resolution?

Successful resolution produces more than a business identity.

It also makes available the information required for the business process to continue.

For example, resolving a product may also provide its description, unit of measure, VAT rate, or any other information required by the current business process.

The important point is that a Locator Definition does not describe specific fields. Instead, it defines the contract of the information that becomes available after a successful resolution.

Optionally, a Locator Definition may also describe the abstract source from which entities are resolved. That source is not necessarily a relational database. It may be a service, an object collection, or any other provider capable of participating in the resolution process. Even this information remains part of the description rather than the implementation.

It is equally important to understand the boundaries of a Locator Definition.

Its purpose is not to describe the technical details of execution. It does not define SQL, indexes, execution plans, caching strategies, or search algorithms. Nor does it dictate dialogs, combo boxes, grid controls, or any other user interface elements.

Those are the responsibility of the Execution Engine, which is free to choose the most appropriate implementation as long as it honors the contract defined by the Locator Definition.

In this sense, a Locator Definition resembles a small declarative language more than it resembles a class or an API.

It does not describe objects, algorithms, or implementations.

It describes a business intent.

It answers only one question:

What does it mean to resolve this business reference?

Everything else is the responsibility of the mechanism that interprets and executes that description.

So far, we have not written a single line of code.

And yet, we have already defined an architectural concept, the language used to describe it, and the information that such a description must contain.

This is perhaps the most important characteristic of a declarative architecture. The concept comes first. The description remains stable, while the mechanism that executes it may evolve, be replaced, or be completely redesigned without changing the concept itself.

The next natural question is therefore no longer what a Locator is, nor how it is described, but how such a declarative description can be transformed into a real, working software component.

That is the software engineering problem we will explore in the next article.

Fundamental Concepts of Business Applications IV: Building a Locator

Fundamental Concepts of Business Applications II: The Locator Pattern

Theodoros Bebekis — Sat, 04 Jul 2026 11:00:26 +0000

In the previous article, we argued that a ComboBox is not enough.

Not because there is anything wrong with the control itself, but because the problem it is designed to solve is much smaller than the actual problem faced by a business application.

That, however, is where we stopped.

We did not answer the next question.

If the problem is not selecting a value, then what exactly is it?

Let us put frameworks aside for a moment.

Forget about controls.

Forget even the word Locator.

Imagine we are editing a line in a sales order.

The user moves to the product field and types:

PROD-001

What should happen next?

The first answer seems obvious.

"The product should be found."

Agreed.

But is that really enough?

Let us assume the product has been found.

Are we finished?

Not at all.

The application still does not know which sales price applies, which unit of measure should be used, which VAT rate is applicable, or even whether the item is currently available in stock.

And in many cases, it must know even more.

Perhaps a different pricing policy applies to this particular customer.

Perhaps a different price list is currently active.

Perhaps even the document date changes the result.

This leads to the first truly interesting question.

Where does all this information come from?

Suddenly, the product is no longer simply the product.

It is the same product within a specific business context.

And that context is not an implementation detail.

It is not an internal state maintained by whatever mechanism performs the resolution.

It is an explicit input to the problem itself.

There is another important observation.

The user did not enter a ProductId.

They did not enter a GUID.

In fact, they are probably unaware that such an identifier even exists.

They entered:

PROD-001

In other words, they entered a business reference.

This is perfectly natural.

People do not think in terms of technical identifiers.

They think in product codes.

Names.

Barcodes.

Account numbers.

Concepts that carry meaning within the business itself.

That is their language.

The information system, however, operates differently.

Its relationships rely on unique, stable identities.

Primary keys.

GUIDs.

Surrogate keys.

Someone must therefore translate the language of the user into the language of the system.

And that translation must be correct.

Within the appropriate business context.

Up to this point, one could argue that we are simply describing a search.

I would probably agree.

At least until the first real business scenario appears.

Because a search merely returns results.

Here, however, we are not simply searching.

We are trying to answer a much more specific question.

Which business entity does the user actually mean?

That is a fundamentally different question.

It is not about discovering information.

It is about resolving a business reference.

Let us now give names to the individual steps of this process.

The user provides a business reference.

The application evaluates it within the current business context.

It attempts to resolve it.

It arrives at a canonical business identity.

Finally, it returns the information required for the task to continue.

Conceptually, the process looks like this:

Business Reference
        │
        ▼
 Business Context
        │
        ▼
    Resolution
        │
        ▼
Canonical Identity
        │
        ▼
   Projection

Notice something interesting.

There is no ComboBox.

No Grid.

No Dialog.

In fact, there is no user interface at all.

There is only a process.

That process does not always produce the same outcome.

It may find no matching entity.

It may find exactly one.

It may find a small number of possible candidates.

Or it may find so many that the result is no longer useful.

The last case deserves special attention.

If the system returns five products, we are dealing with normal business ambiguity.

The user can easily choose the correct one.

If, however, it returns five thousand products, we are no longer dealing with ambiguity.

We are dealing with a business reference that is simply too broad to be resolved.

The problem is not the list.

The problem is the reference itself.

The application should not ask the user to choose one product out of five thousand.

It should ask for a better business reference.

This distinction is fundamental.

Business ambiguity and resolution failure are not the same thing.

The more closely we examine this process, the harder it becomes to view it as just another UI control.

The same process can be used by a desktop application.

A web application.

A service.

A data import process.

An automated workflow.

The interaction changes.

The resolution process does not.

And when the same concept appears in exactly the same form regardless of the application type or user interface, it stops looking like a UI detail and starts looking like an architectural concept.

Perhaps this is the real meaning of the word Locator.

Not as a control.

Not as a search mechanism.

But as the name of an architectural concept.

A concept with one—and only one—purpose:

To transform human business references into canonical business identities within a specific business context.

This is what, in this article, we call The Locator Pattern.

If the Locator is indeed an architectural pattern, another question immediately follows.

How should it be described?

What is the minimum information required to define a Locator?

How can that description remain independent of the mechanism that executes it?

In other words,

Can a Locator be defined declaratively?

That is precisely what we will examine in the next article.

Fundamental Concepts of Business Applications III: Locator Definitions

Closing Question

Does this concept already exist, perhaps under a different name, in the framework or platform you use?

If so, I would genuinely like to learn about it.

Fundamental Concepts of Business Applications I: Why a ComboBox Is Not Enough

Theodoros Bebekis — Fri, 03 Jul 2026 11:53:16 +0000

Introducing the Locator

If you have developed even a single business application, chances are you have solved the same problem many times.

You have built a customer search dialog.

You have implemented product autocomplete.

You have written a custom editor for a data grid.

You have created a selection popup.

Every time, you were essentially solving the same problem.

Yet most UI libraries do not treat this requirement as a distinct concept. It usually appears as a lookup, an autocomplete, a popup dialog, or some other widget. The implementation changes, but the underlying problem remains exactly the same.

In this article, I would like to suggest that this recurring requirement deserves to be recognized as a fundamental concept of business applications. I will call it a Locator.

A Problem Found in Every Business Application

Almost every business application contains fields that reference other business entities.

A sales order references a customer.

An invoice references a supplier.

A warehouse transaction references a product.

A journal entry references an account.

In the database, these relationships are stored as stable identifiers. Users, however, never think in terms of CustomerId or ProductId. They think in terms of customer codes, names, tax numbers, barcodes, and other business identifiers that are meaningful to them.

The real problem is therefore not how to store an identifier.

The real problem is how users can locate the correct business entity using the information they already know.

Why a ComboBox Is Not Enough

When the dataset is small, a ComboBox is an excellent solution.

Countries.

Currencies.

Units of Measure.

Payment Methods.

These are reference tables containing a few dozen or perhaps a few hundred rows. Loading them into memory is perfectly reasonable, and selecting an item from a list is both fast and convenient.

The picture changes completely when we talk about Customers, Products, Suppliers, or General Ledger Accounts. Here the number of records may reach thousands—or even hundreds of thousands.

At this point, the problem is no longer selecting an item from a list.

The problem is locating the correct record.

And that is an entirely different problem.

The Locator

Most UI libraries provide general-purpose controls such as TextBox, ComboBox, ListBox, DataGrid, and TreeView.

Business applications, however, need something different.

They need a mechanism that allows users to locate a business entity using the information they naturally recognize, rather than its technical identifier.

This mechanism is what I call a Locator.

Its purpose is not to display a list.

Its purpose is not to suggest possible values.

Its purpose is to resolve a business reference.

A Locator Does Not Simply Return a Value

At first glance, a Locator may look like an advanced lookup control or an autocomplete widget.

In reality, it does something far more important.

It does not simply return a value.

It resolves a business reference.

Consider a sales order line containing a ProductId field.

The user searches for a product by typing its code or description.

Once the correct product has been selected, the application usually needs much more than the ProductId.

It may need the unit price.

The unit of measure.

The VAT rate.

The discount category.

It may even need different information depending on the customer, the company, the warehouse, or any other business context in which the search takes place.

A Locator therefore does not simply return a value.

It returns the result of resolving a business reference within a specific business context.

That is why it is much more than an advanced lookup control.

It Is Not a Control. It Is a Behavior.

This is perhaps the most important idea.

A Locator is not a particular user interface control.

It is a behavior.

In a desktop form, it may appear as two searchable fields.

In a data grid, it may be implemented as a custom cell editor.

In a web application, it may appear as an autocomplete field with a popup results list.

In a mobile application, it may open a dedicated search screen.

The appearance changes.

The behavior remains exactly the same.

User input

Code
Name
VAT
Barcode

        │
        ▼

     Locator

Searches
Disambiguates
Resolves

        │
        ▼

Target Context

Key
Display values
Business values

The User Experience

Experienced business application users work almost entirely with the keyboard.

A good Locator should never interrupt that workflow.

When a search produces a unique match, the selection should be completed immediately.

Only when multiple possible matches exist should the user be asked to choose the correct business entity.

A Locator is not only about searching.

It is also about disambiguation.

Why Every UI Library Should Include a Locator

Every serious business application solves this problem every day.

Yet most UI libraries do not recognize it as a fundamental abstraction.

Instead, every application ends up implementing search dialogs, autocomplete controls, custom editors, and selection popups over and over again.

The functionality is essentially the same.

Only the implementation differs.

I believe that the Locator represents a fundamental concept of business applications, one that is still treated primarily as a collection of unrelated UI widgets.

Perhaps it is time to recognize it for what it really is: a fundamental abstraction for building data-entry and business applications.

Because in business applications, the critical concept is not displaying a list.

It is enabling users to locate the correct business reference.

In the next article, I will leave philosophy behind and move on to architecture.

What information should a Locator know?

How should it be described?

And how can the same definition be reused across forms, data grids, and different user interface technologies?

Serialize and deserialize JSON using JsonSerializer

Theodoros Bebekis — Wed, 04 Jun 2025 12:16:53 +0000

This text explores the use of the JsonSerializer .Net class in serializing and deserializing .Net classes to JSON.

.Net types related to serialization are found in the following namespaces

System.Text.Json. Contains the JsonSerializer, the JsonSerializerOptions and other main types.
System.Text.Json.Serialization. Contains attributes, converters and similar auxiliary classes used in customizing serialization.

There is of course the excellent Newtonsoft.Json library but JsonSerializer is worth using it since it is the native solution provided by .Net and there is no need to install any NuGet package in order to use it.

JsonSerializer can be used with .Net Core 3.0 and later and with .Net Standard 2.0.

The full text and demo project can be found on GitHub.

Basics

The following code entities are used in this text.

public enum Status
{
    None,
    Pending,
    InProgress,
    AllCompleted
}

public class Part
{
    public string Code { get; set; }
    public decimal Amount { get; set; } 
    public bool IsCompleted { get; set; }
}

JsonSerializer is a static class. No need to create an instance.

// serialization
Part P = new(); 
string JsonText =  JsonSerializer.Serialize(P);

// de-serialization
Part P2 = JsonSerializer.Deserialize<Part>(JsonText);

// or
P2 = JsonSerializer.Deserialize(JsonText, typeof(Part)) as Part;

JsonSerializerOptions

The Serialize() and Deserialize() methods accept a JsonSerializerOptions parameter.

JsonSerializerOptions JsonOptions = new();

// serialization
Part P = new(); 
string JsonText = JsonSerializer.Serialize(P, JsonOptions);

// de-serialization
Part P2 = JsonSerializer.Deserialize<Part>(JsonText, JsonOptions);

// or
P2 = JsonSerializer.Deserialize(JsonText, typeof(Part), JsonOptions) as Part;

The JsonSerializerOptions controls the behavior of the JsonSerializer. It provides a great number of properties in order to customize the serialization operation.

Notable properties worth exploring are:

An example of creating a JsonSerializerOptions instance.

JsonSerializerOptions Result = new();

Result.PropertyNamingPolicy = null;
Result.PropertyNameCaseInsensitive = true;
Result.WriteIndented = true;
Result.IgnoreReadOnlyProperties = true;
Result.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;  
Result.ReadCommentHandling = JsonCommentHandling.Skip;
Result.AllowTrailingCommas = true;
Result.NumberHandling = JsonNumberHandling.AllowReadingFromString;
Result.ReferenceHandler = ReferenceHandler.Preserve;  

return Result;

Attributes

The System.Text.Json.Serialization namespace provides a great number of attributes that can be used with properties or classes in order to control the serialization.

Notable attributes worth exploring are:

[JsonConstructor]

Indicates a constructor that should be used by the serializer.

public class Part
{
    public Part() 
    {
    }
    [JsonConstructor]
    public Part(string code) 
    {
       Code = code;
    }
    public string Code { get; set; }  
    public decimal Amount { get; set; }  
    public bool IsCompleted { get; set; } 
}

[JsonConverter]

Specifies what converter type to be used in serialization.

[JsonConverter(typeof(JsonStringEnumConverter))]
public Status Status { get; set; }

[JsonConverter(typeof(DateOnlyConverter))]
public DateOnly BirthDate { get; set; }

The [JsonConverter(typeof(JsonStringEnumConverter))] can be used with enum types also.

[JsonConverter(typeof(JsonStringEnumConverter))]
public enum Status
{
    None,
    Pending,
    InProgress,
    AllCompleted
}

[JsonIgnore]

Indicates that the property should be ignored in serialization.

[JsonIgnore]
public string Secret { get; set; }

[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string Message { get; set; } // ignored when null, the default

[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
public int Value { get; set; } // ignored when 0, the default

[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
public int Value2 { get; set; } =  123; // ignored when 123, the default

[JsonInclude]

Forces serialization of a public field or a public property even when it has just a private setter.

[JsonInclude]
public int Age;

[JsonInclude]
public string ReadOnlyProperty { get; private set; }

[JsonNumberHandling]

Controls how a number is serialized or deserialized by using a JsonNumberHandling setting.

[JsonNumberHandling(JsonNumberHandling.AllowReadingFromString)]
public int Amount { get; set; }

[JsonPropertyName]

Controls the name under which the property is serialized to or deserialized from.

[JsonPropertyName("user_name")]
public string UserName { get; set; }

[JsonPropertyOrder]

Controls the serialization order of the property.

[JsonPropertyOrder(5)]
public string Name { get; set; }

[JsonRequired]

Dictates that the property must be present.

[JsonRequired]
public string Name { get; set; }

Attributes from other namespaces

None of the following attributes is used in System.Text.Json serialization.

Only the attributes found in System.Text.Json.Serialization are taken into account. The System.Text.Json namespace has its own attributes, all with Json as prefix.

Except of the System.Text.Json there are some other namespaces providing validation attributes.

System.ComponentModel.DataAnnotations namespace. Provides a number of attributes such as [MaxLength], [Required], [Range], etc. Used in Binary Serialization or SOAP Serialization. Also used in Asp.Net Core MVC and WebAPI model validation.
System.Runtime.Serialization namespace. Provides attributes such as [DataContract] and [DataMember]. Used by DataContractSerializer.
System.Xml.Serialization namespace. Provides attributes such as [XmlRoot], [XmlElement], [XmlAttribute]. Used in XML Serialization.

The static System.ComponentModel.DataAnnotations.Validator class can be used to manually validate classes annotated with ValidationAttribute derived attributes, such as MaxLength and Range.

MyModel Model = JsonSerializer.Deserialize<MyModel>(JsonText);

List<string> ErrorList = Validate(Model);

...

public List<string> Validate(object Instance)
{
    List<string> ErrorList = new();
    var validationContext = new ValidationContext(Instance);
    var validationResults = new List<ValidationResult>();

    // not valid?
    // collect validation errors in a list
    if (!Validator.TryValidateObject(Instance, validationContext, validationResults, true))
    {
        foreach (var validationResult in validationResults)
        {
            ErrorList.Add(validationResult.ErrorMessage);
        }        
    }

    return ErrorList; // empty list means Instance is valid
}

In Asp.Net Core MVC or WebAPI controllers the ModelState.IsValid is used to validate attributes based on System.ComponentModel.DataAnnotations namespace annotations.

Customize serialization with Converters

A converter converts an object or a value to and from JSON text.

A custom converter can also be used.

[JsonConverter(typeof(CustomDateOnlyConverter))]
public DateOnly BirthDate { get; set; }

...

public class CustomDateOnlyConverter : JsonConverter<DateOnly>
{
    public override DateOnly Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return DateOnly.Parse(reader.GetString());
    }

    public override void Write(Utf8JsonWriter writer, DateOnly value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(value.ToString("yyyy-MM-dd"));
    }
}

There are two patterns in creating a custom converter

Basic pattern. The custom converter derives from JsonConverter<TValue> class.
Factory pattern. The custom converter derives from JsonConverterFactory class.

A custom converter can be registered

by adding an instance of the custom converter to JsonSerializerOptions.Converters collection
by applying the [JsonConverter] to a class that represents a custom value type
by applying the [JsonConverter] to properties that require the custom converter.

When there are multiple converters applied then there are rules that dictate the order by which a converter is chosen in serialization.

Customize serialization with a Resolver and Modifier functions

The JsonSerializerOptions.TypeInfoResolver property provides a way to plug modifier functions of the type Action<JsonTypeInfo> into serialization.

Inline modifiers with lambda functions.

JsonSerializerOptions JsonOptions = new()
{
    TypeInfoResolver = new DefaultJsonTypeInfoResolver
    {
        Modifiers =
        {
            (TypeInfo) => {
                //...
            },
            (TypeInfo) => {
                //...
            }
        }
    }
};

Or usual methods in a class.

static public class Helper
{
    static public void ModifierFunc1(JsonTypeInfo TypeInfo)
    {
        //...
    }
    static public void ModifierFunc2(JsonTypeInfo TypeInfo)
    {
        //...
    }
}

JsonSerializerOptions JsonOptions = new();
Json.Options.Modifiers.Add(Helper.ModifierFunc1);
Json.Options.Modifiers.Add(Helper.ModifierFunc2);

Here is a custom resolver that excludes a list of specified properties from serialization.

public class ExcludePropertiesTypeInfoResolver : DefaultJsonTypeInfoResolver
{
    string[] ExcludeProperties = new string[0];

    static void RemoveAll<T>(IList<T> list, Predicate<T> predicate)
    {
        for (int i = 0; i < list.Count; i++)
        {
            if (predicate(list[i]))
            {
                list.RemoveAt(i--);
            }
        }
    }
    void ModifierFunc(JsonTypeInfo TypeInfo)
    {
        if (TypeInfo.Kind != JsonTypeInfoKind.Object)
            return;

        RemoveAll(TypeInfo.Properties, prop => ExcludeProperties.Contains(prop.Name)); 
    }

    public ExcludePropertiesTypeInfoResolver(string[] ExcludeProperties)
    {
        this.ExcludeProperties = ExcludeProperties;
        this.Modifiers.Insert(0, ModifierFunc);
    }
}

And here is how to use it.

var ExcludeProperties = new[] { "Prop1", "Prop2"};

JsonSerializerOptions JsonOptions = new()
{
    TypeInfoResolver = new ExcludePropertiesTypeInfoResolver(ExcludeProperties)
};

The JsonTypeInfo provides metadata about the type being serialized.

Regarding modifier functions .Net Core docs provide a number of examples.

Property Name Casing

The casing of a property name, such as camel-casing, is controlled by the JsonSerializerOptions.PropertyNamingPolicy.

PropertyNamingPolicy property is a JsonNamingPolicy derived class. When it is null, the default, property names remain unchanged.

That JsonNamingPolicy class provides a number of static properties that return a JsonNamingPolicy derived class instance, such as CamelCase or SnakeCaseLower. Each one for a specific casing.

JsonSerializerOptions JsonOptions = new();

JsonOptions.PropertyNamingPolicy = JsonNamingPolicy.CameCase;

The PopulateObject() problem.

System.Text.Json provides a solution under the title Populate initialized properties which is far from what is actully needed.

Frequently there are cases where there is an already constructed instance that needs to be populated using data coming as json text. This is a problem that the System.Text.Json has no solution to offer yet.

The JsonSerializer.Deserialize() methods always create and return a new instance. This is not always what an application needs.

But deep in the .Net source code there is a class containing a method that do just that. The Microsoft.Graph.DerivedTypeConverter contains a private method, named PopulateObject() which does exactly what it says.

The project that accompanies this text contains a static class under the name NetJson which provides, among other useful utilities, a PopulateObject() method. This PopulateObject() method is just the code from the Microsoft.Graph.DerivedTypeConverter.PopulateObject() private method.

static public void PopulateObject(object Instance, string JsonText, JsonSerializerOptions Options)

The Document Object Model (DOM) of System.Text.Json

Except of the JsonSerializer the .Net Core serialization sub-system provides a DOM model too.

The system provides two ways in building a DOM model.

System.Text.Json.JsonObject class, along with JsonNode, JsonArray and JsonValue classes
System.Text.Json.JsonDocument along with JsonElement class.

JsonObject, JsonNode, JsonArray and JsonValue

These are mutable classes, meaning the application may add, modify or remove elements in the DOM tree.

JsonNode is an abstract class. Besides that it provides a great number of static helper methods for adding elements to the DOM tree. It also serves as the base class for the others in this group.
JsonObject represents a mutable DOM object.
JsonArray represents a mutable DOM array object.
JsonValue represents a mutable DOM value object.

All the above provide the following properties

an integer indexer property Item[Int32]
a string indexer property Item[String]
a Count property

All the above provide the following methods

AsObject()
AsArray()
AsValue()
GetPath()
GetPropertyName()
GetType()
GetValue<T>()
GetValueKind() which returns a value of the JsonValueKind enum
ReplaceWith<T>(T)
ToJsonString()

The JsonObject and JsonArray provide the following methods too

Add()
Clear()
Remove()
RemoveAt()

Primitive Values using JsonValue.Create(AnyPrimitiveValue)

JsonObject properties are Key-Value pairs, i.e. JORoot.Add(PropertyName, PropertyValue).

The JsonValue.Create(AnyPrimitiveValue) is used with primitive Types such as string and integer, in creating new JsonValue objects.

JsonObject JORoot = new();
JORoot.Add("String", JsonValue.Create("This is a JsonValue"));
JORoot.Add("DateTime", JsonValue.Create(DateTime.Now));
JORoot.Add("Integer", JsonValue.Create(123));

Removing a Property

Using the Remove(PropertyName) removes the property.

JORoot.Remove("DateTime");

JsonObject is a Dictionary-like object

JsonObject instances are Dictionary-like objects and a new JsonObject can be initialized as following.

JsonObject JORoot = new JsonObject
{
    ["Key1"] = "This is a string",
    ["Key2"] = DateTime.Now,
    ["Key3"] = false,
};

The JsonNode.Parse() method

The JsonNode.Parse(JsonText) static method parses text and returns a JsonNode object.

JsonObject JORoot = new();
JORoot.Add("Person", JsonNode.Parse("""{ "Name": "John Doe", "Age": 30 }"""));

Using the JsonValue.Create<T>() with non-primitive Types

The JsonValue.Create<T>() is used with non-primitive Types such as user defined classes, in creating new JsonValue objects.

JsonObject JORoot = new();
JORoot.Add("Part", JsonValue.Create<Part>(new Part()));

Initializing a JsonArray

JsonObject JORoot = new();
JsonArray JOArray = new JsonArray() { 123, true, DateTime.Now, "string value" };
JORoot.Add("Array", JOArray);

Using a Dictionary

A Dictionary<string, JsonNode> can be used in adding a property to a JsonObject object.

The Dictionary<string, JsonNode> dictionary has to be converted to a JsonObject first.

This can be done because JsonObject provides a suitable constructor.

public JsonObject(IEnumerable<KeyValuePair<string, JsonNode?>> properties, JsonNodeOptions? options = null)

JsonObject JORoot = new();

var Dictionary = new Dictionary<string, JsonNode>
{
    ["Key1"] = "This is a string",
    ["Key2"] = DateTime.Now,
    ["Key3"] = false,
    ["Key4"] = JsonValue.Create<Status>(Status.InProgress),
};

JsonObject DicNode = new JsonObject(Dictionary);
JORoot.Add("Dictionary", DicNode);

Accessing Properties and Values

string DemoJsonText = """
        {
            "Id": 1,
            "Name": "Model 1",
            "Status": "InProgress",
            "Active": true,
            "Parts": [
                {
                "Code": "001",
                "Amount": 1.2,
                "IsCompleted": true
                },
                {
                "Code": "002",
                "Amount": 3.4,
                "IsCompleted": false
                }
            ],
            "Properties": {
            "John": "Doe",
            "NiceCar": "Volvo"
            },
            "DT": "2025-06-04T00:59:25.6948527+03:00"
        }
        """;

JsonNode RootNode = JsonNode.Parse(DemoJsonText);

// accessing array
JsonNode PartsNode = RootNode["Parts"];
JsonNode FirstPartNode = PartsNode[0]; 

// adding new property
JsonObject ThirdPartNode = new();
ThirdPartNode["Code"] = "003";
ThirdPartNode["Amount"] = 12.3;
ThirdPartNode["IsCompleted"] = true;

// get node as array
JsonArray ArrayNode = PartsNode.AsArray();
ArrayNode.Add(ThirdPartNode);

// typecasting nodes
JsonNode PropNode = ThirdPartNode["Amount"];
double V = (double)PropNode;
// 12.3

string S = (string)ThirdPartNode["Code"];
// 003

// using the GetValue<T>()
DateTime DateTimeNode = RootNode["DT"].GetValue<DateTime>();

// get the path
string S2 = RootNode["Parts"][0].GetPath();
// $.Parts[0]   where $ denotes the root node

JsonDocument

JsonDocument is used in building a read-only DOM. It provides the RootElement of type JsonElement.

JsonDocument elements are accessed using the JsonElement class.

The JsonElement class provides enumerators in order to iterate over its elements.

The JsonElement class provides methods such as GetInt32() and TryGetInt32() which convert JSON text to .Net primitive types.

NOTE: JsonElement is an IDisposable type.

double Total = 0;

using (JsonDocument Doc = JsonDocument.Parse(DemoJsonText))
{
    JsonElement Root = Doc.RootElement;
    JsonElement PartsProperty = Root.GetProperty("Parts");
    foreach (JsonElement PartProperty in PartsProperty.EnumerateArray())
    {
        if (PartProperty.TryGetProperty("Amount", out JsonElement AmountElement))
        {
            Total += AmountElement.GetDouble();
        }
    }
}