DP44/enriched-partialglm/Common/DTS.CommonCore/Interface/Database.md

---
source_files:
  - Common/DTS.CommonCore/Interface/Database/IDatabaseCopyView.cs
  - Common/DTS.CommonCore/Interface/Database/IDatabaseSwitchView.cs
  - Common/DTS.CommonCore/Interface/Database/IDatabaseStatusBarView.cs
  - Common/DTS.CommonCore/Interface/Database/IDatabaseSwitchViewModel.cs
  - Common/DTS.CommonCore/Interface/Database/IUserDbRecord.cs
  - Common/DTS.CommonCore/Interface/Database/IDatabaseCopyViewModel.cs
  - Common/DTS.CommonCore/Interface/Database/IDatabaseStatusBarViewModel.cs
generated_at: "2026-04-16T12:08:57.334036+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "142a1b67b74ee9e9"
---

# Documentation: DTS.Common.Interface.Database

## 1. Purpose

This module defines the contract layer for database-related UI operations within the DTS system. It provides interfaces for views and view models that handle database copying from remote to local databases, switching between remote and local database connections, displaying database connection status in a status bar, and representing user records stored in the database. The module follows a Model-View-ViewModel (MVVM) pattern, with all view models extending from `IBaseViewModel` and views extending from `IBaseView`.

---

## 2. Public Interface

### IDatabaseCopyView
```csharp
public interface IDatabaseCopyView : IBaseView { }
```
Marker interface for a view associated with database copy operations. No members defined.

---

### IDatabaseSwitchView
```csharp
public interface IDatabaseSwitchView : IBaseView { }
```
Marker interface for a view associated with database switching operations. No members defined.

---

### IDatabaseStatusBarView
```csharp
public interface IDatabaseStatusBarView : IBaseView { }
```
Marker interface for a view associated with the database status bar. No members defined.

---

### IDatabaseSwitchViewModel
```csharp
public interface IDatabaseSwitchViewModel : IBaseViewModel
```
ViewModel interface for transferring a remote database to a local database. Clears the local database and populates it with the remote database.

**Properties:**
| Signature | Description |
|-----------|-------------|
| `IDatabaseSwitchView View { get; set; }` | The view associated with the model |
| `bool RemoteIsActive { get; }` | Indicates whether remote database is currently active |
| `string DefaultDbName { get; }` | Gets the default database name |
| `string DbHost { get; }` | Gets the database host |
| `bool NTLMAuthentication { get; }` | Gets whether NTLM authentication is enabled |
| `string DbUser { get; }` | Gets the database user |
| `string DbPassword { get; }` | Gets the database password |

**Methods:**
| Signature | Description |
|-----------|-------------|
| `void Unset()` | Frees up any memory associated with the viewmodel |
| `void InitializeDbSettings(string defaultDbName, string dbHost, bool ntlmAuthentication, string dbUser, string dbPassword)` | Initializes database connection settings |
| `void SwitchRemote()` | Switches to the remote database |
| `void SwitchLocal()` | Switches to the local database |

---

### IUserDbRecord
```csharp
public interface IUserDbRecord
```
Interface representing a user record in the database.

**Properties:**
| Signature | Description |
|-----------|-------------|
| `int ID { get; set; }` | Database ID of the user |
| `string UserName { get; set; }` | User name of the user. **Must be unique** |
| `string DisplayName { get; set; }` | String to use when displaying user in UI |
| `string Password { get; set; }` | Hashed and salted password value (plain text passwords are not stored) |
| `short Role { get; set; }` | Role of the user |
| `DateTime LastModified { get; set; }` | DateTime the user was last modified |
| `string LastModifiedBy { get; set; }` | User that last modified this user record |
| `bool LocalOnly { get; set; }` | Whether user should be synchronized between local and remote databases. **Deprecated** |

---

### IDatabaseCopyViewModel
```csharp
public interface IDatabaseCopyViewModel : IBaseViewModel
```
ViewModel interface for transferring a remote database to a local database. Clears the local database and populates it with the remote database.

**Properties:**
| Signature | Description |
|-----------|-------------|
| `IDatabaseCopyView View { get; set; }` | The view associated with the model |
| `string DbName { get; }` | Gets the database name |
| `IStatusAndProgressBarView OverallProgressBarView { get; }` | The overall status/progress view |
| `IStatusAndProgressBarView CurrentTaskProgressBarView { get; }` | Current task status/progress view |
| `DbType DatabaseType { get; }` | Gets the database type |
| `bool CopyEnabled { get; }` | Gets whether copy operation is enabled |
| `bool IsCopyVisible { get; set; }` | Gets or sets copy visibility |

**Methods:**
| Signature | Description |
|-----------|-------------|
| `void Unset()` | Frees up any memory associated with the viewmodel |
| `void CopyDatabase()` | Copies from remote database to local database (uses `DTS.Common.Storage` to determine local and remote) |
| `void InitializeState(DbType dbType, string dbName)` | Initializes viewmodel state |

---

### IDatabaseStatusBarViewModel
```csharp
public interface IDatabaseStatusBarViewModel : IBaseViewModel
```
ViewModel interface handling the logic for database status in a UI, including current connection and status.

**Properties:**
| Signature | Description |
|-----------|-------------|
| `IDatabaseStatusBarView View { get; set; }` | The associated view for the model |
| `DbType DatabaseType { get; }` | Gets the database type (populated via `InitializeValues`) |
| `bool RemoteConnected { get; }` | Gets whether the remote database is connected (populated via `InitializeValues`) |
| `string ServerName { get; }` | Gets the server name, not database name (populated via `InitializeValues`) |
| `string ActiveDbName { get; }` | Returns the current active database name (either server name or local depending on db type and remote connection status) |
| `Brush BackgroundBrush { get; }` | Returns the background brush for the active database name |

**Methods:**
| Signature | Description |
|-----------|-------------|
| `void Unset()` | Frees up any memory associated with the viewmodel |
| `void InitializeValues(DbType dbType, string serverName, bool remoteConnected)` | Sets the initial values for database type, server name, and remote connection status |

---

## 3. Invariants

- **IUserDbRecord.UserName** must be unique across all user records.
- **IUserDbRecord.Password** must be a hashed and salted value; plain text passwords must never be stored in the database.
- **IDatabaseCopyViewModel** and **IDatabaseSwitchViewModel** require that the local database already has the correct tables and stored procedures before copy/switch operations can be performed.
- All ViewModels must have their initialization methods called (`InitializeState`, `InitializeDbSettings`, or `InitializeValues`) before their properties can be meaningfully accessed.
- `Unset()` should be called to clean up resources when a ViewModel is no longer needed.

---

## 4. Dependencies

### This module depends on:
- **DTS.Common.Base** — Provides `IBaseView`, `IBaseViewModel`, and `IStatusAndProgressBarView`
- **DTS.Common.Enums.Database** — Provides `DbType` enumeration
- **DTS.Common.Storage** — Referenced in documentation as the source for determining local and remote database locations (actual dependency not visible in imports)
- **System.Windows.Media** — Provides `Brush` class (used in `IDatabaseStatusBarViewModel`)
- **System** — Provides `DateTime` (used in `IUserDbRecord`)

### What depends on this module:
- Cannot be determined from source alone. Concrete implementations of these interfaces would exist elsewhere in the codebase.

---

## 5. Gotchas

1. **Deprecated Property**: `IUserDbRecord.LocalOnly` is marked as deprecated. New code should not rely on this property for synchronization logic between local and remote databases.

2. **Preconditions for Copy/Switch**: Both `IDatabaseCopyViewModel` and `IDatabaseSwitchViewModel` explicitly require that the local database already has the correct schema (tables and stored procedures) before operations can succeed. This is not validated by the interfaces themselves.

3. **ServerName vs Database Name**: `IDatabaseStatusBarViewModel.ServerName` returns the server name, not the database name. The actual active database name is available via `ActiveDbName`.

4. **Commented-Out Method**: `IDatabaseSwitchViewModel` has a commented-out method signature `//void SetDefaultDbName(string defaultDbName);` suggesting this functionality was removed or never implemented. The reason is unclear from source alone.

5. **WPF Dependency**: The use of `System.Windows.Media.Brush` in `IDatabaseStatusBarViewModel` indicates a WPF-specific dependency, which may limit portability to other UI frameworks.