DataConnection System

BeepDataConnection component -- design-time connection management, IBeepService integration, BeepConnectionRepository with Project/User/Machine storage scope, and ConnectionsChanged event

Table of Contents

Overview

Namespace: TheTechIdea.Beep.Winform.Controls
Inheritance: System.ComponentModel.Component
Designer: BeepDataConnectionDesigner (design-time component tray support)
Associated enum: ConnectionStorageScope { Project, User, Machine }

BeepDataConnection is a design-time Component for managing database connections. It wraps IBeepService for data operations, persists connections using BeepConnectionRepository across three storage scopes, and provides change notification via the ConnectionsChanged event. At design time, it appears in the Visual Studio component tray below the form designer.

Key Properties

PropertyTypeCategoryDescription
BeepServiceIBeepService?RuntimeService provider for data operations. Read-only. Owned internally or shared.
AppRepoNamestringPersistenceRepository name for connection storage. Default: "BeepPlatformConnections". Browsable.
DirectoryPathstringPersistenceFilesystem directory for connection file storage. Default: "". Browsable.
DataConnectionsList<ConnectionProperties>RuntimeCollection of managed database connection properties (server, database, credentials, driver).

Constructor Behavior

The constructor executes a four-step initialization:

  1. InitializeBeepService() -- Creates or resolves an IBeepService instance. If the component owns the service (no external injection), sets _ownsBeepService = true for cleanup responsibilities.
  2. DataConnections initialization -- Creates an empty List<ConnectionProperties>.
  3. InitializeRepository() -- Creates a BeepConnectionRepository using AppRepoName and DirectoryPath. Subscribes to repository change events via _repositoryChangedHandler.
  4. ReloadConnections() -- Loads persisted connections from the repository into the DataConnections list.

Both AppRepoName and DirectoryPath property setters call OnStorageConfigurationChanged() to reinitialize the repository when persistence settings change.

Connection Repository

BeepConnectionRepository handles the store/load cycle for connection definitions:

  • Store -- Serializes DataConnections list to a file in the configured directory
  • Load -- Deserializes connection definitions from file to DataConnections list
  • Scope resolution -- File location depends on ConnectionStorageScope (Project, User, or Machine)
  • Change notification -- Fires events when connections change on disk, triggering ConnectionsChanged

Storage Scopes

ScopeStorage LocationUse Case
ProjectProject directory relative to executable/solutionConnections specific to the current application project
UserUser's appdata/local folderPer-user connections, persists across projects
MachineCommon application data folderMachine-wide shared connections, all users

IBeepService Integration

The component wraps IBeepService for database operations:

  • Creates data sources from connection properties
  • Provides connection testing/validation
  • Manages the service lifecycle (creation, disposal)
  • The _ownsBeepService flag determines whether Dispose should clean up the service

Events

EventTypeFires When
ConnectionsChangedEventHandler?Connection list is modified (add, remove, update) or repository detects changes

Design-Time

The BeepDataConnectionDesigner provides the Visual Studio design-time experience:

  • Appears in the component tray below the form (non-visual component)
  • Properties (AppRepoName, DirectoryPath) browsable in the Properties window under "Persistence" category
  • Connection list editable via collection editor at design time

Code Examples

var dc = new BeepDataConnection();
dc.AppRepoName = "MyAppConnections";
dc.DirectoryPath = @"C:\MyApp\Data";

// Add a connection
dc.DataConnections.Add(new ConnectionProperties
{
    Name = "MainDB",
    Server = "localhost",
    Database = "MyDatabase",
    Driver = "SQLServer"
});

dc.ConnectionsChanged += (s, e) =>
    Console.WriteLine("Connections modified");

// Change storage scope at runtime
// ConnectionStorageScope enum: Project, User, Machine