Merge Semantics Contract

The Merge Semantics Contract defines predictable, testable merge behavior across UI and non-UI flows and applies to:

• POCO merge: dataset to dataset (PocoDataSet.Extensions)
• Observable merge: dataset to observable dataset (PocoDataSet.ObservableExtensions)

Terminology

• Current - the dataset (or observable dataset) currently held in memory / bound to UI.
• Refreshed - a snapshot from the backend (search results, expanded children, reloaded state, post-save response).
• Clean baseline - rows represent persisted / server truth and are in Unchanged state.

Public API (Do* merge methods)

The merge API is expressed as four explicit dataset extension methods:

• DoPostSaveMerge
• DoRefreshMergeIfNoChangesExist
• DoRefreshMergePreservingLocalChanges
• DoReplaceMerge

MergeWith exists for backward compatibility only and is marked [Obsolete]. New code should call the explicit Do* methods.

Dataset Level Contract

Table discovery

• Existing tables are merged according to the selected merge method.
• Tables missing from current but present in refreshed may be added, unless excluded.

Exclusions

• ExcludeTablesFromMerge - skip merging that table entirely.
• ExcludeTablesFromRowDeletion - never delete rows from that table due to "missing in refreshed".

Table-Level Contract

Tables with primary key

• Use primary key matching (PK index matching).
• Invariant: no duplicate PK values among non-deleted rows after merge.
• Refreshed rows must have non-null PK values (enforced in refresh-preserving mode).

Tables without primary key

Current contract: tables without primary keys use "Replace-like" semantics during refresh operations because safe row-by-row reconciliation is not reliable without keys. This avoids false matches and accidental data corruption.

• All current rows are removed.
• All refreshed rows are added.
• Rows end as Unchanged.

Merge Methods (Policies)

POCO DataSet and Observable POCO DataSet use the same policies. The only difference is that Observable POCO DataSet raises notification events about changes during the merge process.

1) DoRefreshMergePreservingLocalChanges (non-destructive refresh)

Intent: refresh current content with server truth without overwriting local edits.

• Rows in Unchanged state may be overwritten by refreshed values.
• Rows with local pending changes (Added, Modified, and Deleted) are preserved.
• Rows present in refreshed but missing locally are added as Unchanged.
• Rows missing from refreshed may be removed only when the current row is Unchanged (and the rows are not excluded from deletion).
• Row matching is performed using primary key values.
• Refreshed rows must have non-null primary key values; otherwise an exception is thrown.

Current row state	Refreshed row exists	Action	Result	Observable Events
Unchanged	Yes	Copy refreshed values	Unchanged	IObservableDataRow.DataFieldValueChanged
Unchanged	No	Remove row (unless rows excluded from deletion)	Row removed	IObservableDataTable.RowsRemoved
Modified	Yes/No	Preserve local edits	Modified	None
Added	Yes/No	Preserve local new row	Added	None
Deleted	Yes/No	Preserve pending delete	Deleted	None

Outcome: local edits remain as is; server-applied updates become baseline (Unchanged) for eligible rows.

2) DoRefreshMergeIfNoChangesExist (refresh-only-when-clean)

Intent: enforce that refresh can only happen when the current dataset is a clean baseline. This mode is appropriate for read-only screens, polling, and search result scenarios where local edits are not expected.

• If any current rows are in Added, Modified, or Deleted state, an exception is thrown and no merge occurs.
• Otherwise, rows may be overwritten by refreshed values.
• Rows present in refreshed but missing locally are added as Unchanged.
• Rows missing from refreshed may be removed (unless they are excluded from deletion).

Precondition	Current state	Refreshed snapshot	Action	Result	Observable Events
Must be clean	Any row is Added/Modified/Deleted	Any	Throw and do not merge	No changes applied	None
Clean baseline	All rows are Unchanged	Row exists with same PK	Copy refreshed values	Row stays Unchanged	None
Clean baseline	All rows are Unchanged	Row missing for a current PK	Remove row (unless excluded from deletion)	Row removed	None
Clean baseline	All rows are Unchanged	New row exists (PK not present in current)	Add row	Row becomes Unchanged	None

3) DoPostSaveMerge (reconciliation after successful save)

Intent: apply server-confirmed values (identity, rowversion, computed fields), finalize deletes, and end in a clean baseline.

• Applies server-confirmed values back onto matching current rows.
• Finalizes deletes by permanently removing deleted rows.
• May correlate rows using primary key values and (when applicable) a client key used for temporary identity.
• Calls AcceptChanges() to commit the clean baseline.

Current row state	Server row exists	Action	Result	Observable Events
Added	Yes	Propagate identity/rowversion/computed fields	Unchanged	IObservableDataRow.DataFieldValueChanged IObservableDataRow.RowStateChanged
Modified	Yes	Propagate server-confirmed fields	Unchanged	IObservableDataRow.DataFieldValueChanged IObservableDataRow.RowStateChanged
Deleted	Yes/No	Remove from table (finalize delete)	Row removed	IObservableDataTable.RowsRemoved
Unchanged	Yes	Copy refreshed values	Unchanged	IObservableDataRow.DataFieldValueChanged

Outcome: all remaining rows end as Unchanged.

4) DoReplaceMerge (destructive reload)

Intent: replace the entire local result set (new search results, "load children from scratch", etc.). This mode intentionally does not attempt row-level reconciliation and therefore is not considered a merge in the strict sense.

• Clears current rows.
• Copies all refreshed rows into the current table as Unchanged.

Current content	Refreshed snapshot	Action	Result	Observable Events
Any rows (including pending edits)	Any	Remove all current rows	Table becomes empty	IObservableDataTable.RowsRemoved
Empty after clear	All refreshed rows	Add all refreshed rows	All rows are Unchanged	IObservableDataTable.RowsAdded

Replace Schema Contract

Replace is easy to accidentally change later. The current policy is:

• The current schema is authoritative.
• Extra columns in refreshed are ignored.
• If a column exists in both current and refreshed and the data type differs, Replace throws to avoid silent corruption.
• If refreshed is missing a column that exists in current, the column remains in schema; new rows simply do not contain that field value.

 

Table of Content POCO DataSet Concepts

 

---

Business Process Programming in .Net
© 2004–2026 Laskarzhevsky Software Inc.
Unless otherwise noted, the content of this website is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).
Code examples are provided under the MIT License.
You are free to share and adapt the material provided that appropriate credit is given and any modifications are clearly indicated.
The information provided on this website is for educational purposes only.
The author and publisher make no warranties regarding the completeness or suitability of the information and are not responsible for any damages resulting from its use.