Table of Contents

DataManager

Libreria di classi VB.NET (net48) che fornisce il motore condiviso di accesso dati su cui poggiano tutte le DAL del verticale RequestCenter (e, più in generale, il codice web che usa GlobalDataManager). Espone apertura connessione Oracle, transazioni, esecuzione di comandi per nome di stored procedure e riempimento di DataSet/IDataReader. Classificazione complessiva: VERIFIED (sorgente + metadati di progetto concordanti).

Scopo

DataManager incapsula il plumbing ADO.NET provider-agnostic: creazione della connessione tramite DbProviderFactory, gestione del ciclo di vita della connessione, transazioni con IsolationLevel, e le primitive di esecuzione (ExecuteReader, ExecuteNonQuery, ExecuteScalar, Fill, GetTable, GetDataSet) invocate dalle DAL passando il nome del package/stored procedure e un elenco di DbParameter. Le DAL non aprono connessioni inline: ricevono un'istanza di GlobalDataManager (convenzionalmente la variabile cm) e delegano ad essa ogni accesso al DB. [SUPPORTED]

Posizione nel repository

  • Repo: InfocadWeb
  • Progetto net48: WebMachine/DataManager/DataManager.vbproj
  • Progetto net8 (re-link): WebMachine/DataManagerXNET/DataManagerXNET.vbproj

Tipo di progetto

Libreria di classi (<OutputType>Library</OutputType>). Nessun servizio, nessun host WCF, nessuna UI. [VERIFIED]

Framework e runtime

  • DataManager.vbproj: MSBuild legacy (ToolsVersion="12.0", schema 2003), TargetFrameworkVersion v4.8, linguaggio VB.NET, OptionStrict On, RootNamespace Descor.DataManager, AssemblyName DataManager. [VERIFIED]
  • DataManagerXNET.vbproj: SDK-style, TargetFramework net8.0, AssemblyName DataManagerXNET, stesso RootNamespace Descor.DataManager. Non duplica il codice: re-linka i tre sorgenti del progetto net48 via <Compile Include="..\DataManager\*.vb" Link="..." /> (Enums.vb, GlobalDataManager.vb, NullFieldUtility.vb). [VERIFIED]

Responsabilità

  • Astrazione del provider dati tramite DbProviderFactory (registrazione/lookup del factory per providerName). [SUPPORTED]
  • Gestione della connessione: Open, Close, CloseIfNeeded, Reset, pattern IDisposable. [SUPPORTED]
  • Gestione delle transazioni: BeginTransaction (con e senza IsolationLevel), CommitTransaction, RollbackTransaction, proprietà InTransaction. [SUPPORTED]
  • Esecuzione di comandi: ExecuteNonQuery, ExecuteReader, ExecuteDbReader, ExecuteScalar, ExecuteInt32ReturnQuery, ExecuteInt64ReturnQuery. [SUPPORTED]
  • Materializzazione dei risultati: Fill(DataSet, ...), GetTable, GetDataSet. [SUPPORTED]
  • Factory di comandi e parametri: CreateCommand, CreateParameter, CreateReturn*Parameter, CreateDataAdapter. [SUPPORTED]
  • Conversione dei valori DB nulli tramite NullFieldUtility. [SUPPORTED]

Entry point

Nessun entry point eseguibile (libreria). L'ingresso funzionale è il costruttore GlobalDataManager.New(providerName, connectionString) (o l'overload con IDbConnection), tipicamente invocato non dalle DAL ma da un factory di configurazione (per RequestCenter: Configuration.Settings.GetConnectionManager, che restituisce l'istanza cm). [SUPPORTED]

Struttura interna

File compilati (dal .vbproj): [VERIFIED]

  • GlobalDataManager.vb — la classe motore (connessione, transazioni, esecuzione, factory).
  • Enums.vb — OpenConnectionResult (Opened / AlreadyOpen), PendingTransactionAction (Commit / Rollback).
  • NullFieldUtility.vb — classe statica NotInheritable con i convertitori To<Type>/ToNullable<Type> che mappano DBNull.Value su un valore di default.
  • My Project/*.Designer.vb — generati (non documentati).

Namespace principali

Descor.DataManager (da RootNamespace; nessun blocco Namespace esplicito nei sorgenti, quindi i tipi risultano Descor.DataManager.GlobalDataManager, Descor.DataManager.NullFieldUtility, ecc.). [VERIFIED]

Dipendenze in ingresso

Referenziato dalle DAL e dal codice di configurazione del verticale RequestCenter. Esempi diretti:

  • RequestCenter.DAL.OracleODP — ogni DAL ottiene Dim cm As GlobalDataManager = Configuration.Settings.GetConnectionManager e vi delega gli accessi (vedi RequestDAL.vb, ComplaintDAL.vb, CallTypeDAL.vb, …). [VERIFIED]
  • RequestCenter (BL) — Configuration/Settings.vb espone GetConnectionManager(...) As GlobalDataManager. [SUPPORTED]

L'uso è pervasivo oltre RequestCenter (il tipo GlobalDataManager è la convenzione condivisa di accesso dati del web tier); qui è mappato solo il perimetro del verticale. [INFERRED]

Dipendenze in uscita

  • DataManager.vbproj: solo assembly del framework — <Reference> a System, System.Data, System.Xml. Nessuna ProjectReference, nessun riferimento diretto a un driver Oracle: il provider concreto è risolto a runtime via DbProviderFactories.GetFactory(providerName). [VERIFIED]
  • DataManagerXNET.vbproj: PackageReference a Oracle.ManagedDataAccess.Core 23.4.0; il codice registra esplicitamente OracleClientFactory.Instance sotto la guardia #If NET5_0_OR_GREATER prima del lookup del factory. [VERIFIED]

Configurazione

Il progetto non legge direttamente file di configurazione. providerName e connectionString sono forniti dal chiamante (il factory di configurazione del verticale). Il connectionString seguito è quello Oracle applicativo (MainConnection per RequestCenter, secondo la convenzione di deploy descritta in CLAUDE.md — non verificato in questo progetto). [INFERRED]

Parametri di sessione DB opzionali: la proprietà DbSessionParams (Dictionary(Of String, String)), se valorizzata, viene serializzata in XML e passata alla stored procedure SET_CONTEXT_VALUE durante Open() (usata da RequestCenter per propagare DBUSERSESSION/DBSOURCESESSION). [VERIFIED]

API esposte

Nessuna API remota (SOAP/WCF/REST). Superficie pubblica = i membri della classe GlobalDataManager (vedi class-GlobalDataManager.md) più gli enum e NullFieldUtility. [VERIFIED]

Accesso ai dati

È il layer di accesso ai dati stesso, ma provider-agnostic: usa esclusivamente le astrazioni System.Data/System.Data.Common (IDbConnection, IDbTransaction, DbCommand, DbParameter, DbDataAdapter, IDataReader, DataSet). Il DefaultCommandType viene impostato a CommandType.StoredProcedure in Initialize() quando non specificato: le DAL passano quindi il nome del package/procedure Oracle (es. "GETREQUEST", GESTREQUEST.ADDDESCRIPTIONTOREQUEST, GESTREQUEST_T2.ADDREQUEST) come CommandText. Package Oracle e procedure del verticale sono documentati in ../../../05-databases/REQUESTCENTER_TEST38/procedures.md; la matrice CRUD in ../../../05-databases/crud-matrix.md. [VERIFIED]

Job e processi in background

Nessuno. [VERIFIED]

Integrazioni

Nessuna integrazione esterna diretta oltre al DB Oracle raggiunto via provider factory. [SUPPORTED]

Gestione degli errori

  • Le primitive di esecuzione rilanciano (Throw) preservando la connessione secondo CloseIfNeeded; alcuni blocchi Catch/Throw sono compilati solo sotto #If DEBUG (in Release l'eccezione risale senza intercettazione esplicita ma il Finally esegue comunque dispose/close). [VERIFIED]
  • Accessi dopo Dispose sollevano ObjectDisposedException; command Is Nothing solleva ArgumentNullException. [VERIFIED]
  • Dettaglio per-metodo in class-GlobalDataManager.md.

Logging

Nessun framework di logging. ExecuteReader(IDbCommand, CommandBehavior) emette Debug.WriteLine(command.CommandText); un commento 'Todo: Loggare l'errore in Open() segnala logging non implementato. [VERIFIED]

Test

Nessun test automatico nel repository (0 progetti xUnit/NUnit/MSTest). Copertura non misurata. [VERIFIED]

Procedure di build

  • net48 (Windows, NON verificato su questo host macOS/no Oracle Client): msbuild InfocadWeb/WebMachine/DataManager/DataManager.vbproj -p:Configuration=Debug. [UNKNOWN sull'host corrente]
  • net8 (DataManagerXNET): compila headless — l'artefatto Assembly/net8.0/DataManagerXNET.dll è presente (build 0 errori/0 warning secondo l'orchestratore; verificata la sola presenza del .dll). [SUPPORTED]

Procedure di debug

Debug.WriteLine del CommandText in ExecuteReader è l'unico ausilio integrato. Per la connettività Oracle senza lo stack Windows si può usare python-oracledb in thin mode (read-only) contro il DB dev. [SUPPORTED]

Come estendere il progetto

Aggiungere primitive di esecuzione/factory alla classe GlobalDataManager mantenendo il pattern provider-agnostic (nessun tipo Oracle diretto sotto net48; i tipi concreti solo dietro #If NET5_0_OR_GREATER). Poiché _factory è Shared, evitare di introdurre stato statico dipendente dal provider quando coesistono più connection string. [INFERRED]

Aree rischiose

  • _factory è Shared: il primo New(...) fissa il factory per l'intero processo; provider eterogenei nello stesso processo sono un rischio. [SUPPORTED]
  • La classe non è thread-safe (stato di istanza _connection/_transaction); l'istanza cm è pensata per essere per-richiesta (cache RCCONNECTIONMANAGER in HttpContext.Current.Items). [INFERRED]
  • Il ciclo di vita dei reader restituiti (ExecuteReader/ExecuteDbReader) è a carico del chiamante: CommandBehavior.CloseConnection viene usato solo se la connessione era chiusa all'ingresso. [VERIFIED]

Debito tecnico

  • Logging degli errori non implementato ('Todo: Loggare l'errore). [SUPPORTED]
  • Catch/Throw condizionati a #If DEBUG in Open/ExecuteNonQuery/ExecuteScalar (comportamento di intercettazione divergente tra Debug e Release). [SUPPORTED]
  • La reference DocFX generata per questo progetto è rinviata: DataManagerXNET compila ma docfx metadata fallisce con BC30002 (tipo System.Data... non trovato in fase di metadata). Questa pagina resta concettuale (spec §27). [SUPPORTED]

Flussi correlati

Regole di business correlate

Evidenze

  • InfocadWeb/WebMachine/DataManager/DataManager.vbproj:9-11 (OutputType Library, RootNamespace Descor.DataManager, AssemblyName DataManager), :23 (TargetFrameworkVersion v4.8), :13 (OptionStrict On), :158-160 (Reference System/System.Data/System.Xml — nessuna ProjectReference), :172-190 (Compile Enums.vb/GlobalDataManager.vb/NullFieldUtility.vb).
  • InfocadWeb/WebMachine/DataManagerXNET/DataManagerXNET.vbproj:4-6 (RootNamespace/net8.0/AssemblyName), :20-22 (<Compile ... Link=...> re-link 3 file), :26 (PackageReference Oracle.ManagedDataAccess.Core 23.4.0).
  • InfocadWeb/WebMachine/DataManager/GlobalDataManager.vb:9 (Public Class GlobalDataManager), :15 (Shared _factory As DbProviderFactory), :34-37 (registrazione factory sotto #If NET5_0_OR_GREATER), :104-131 (Open + SET_CONTEXT_VALUE), :580-588 (Initialize -> CommandType.StoredProcedure), :325 (Debug.WriteLine(command.CommandText)), :120-121 ('Todo: Loggare l'errore).
  • InfocadWeb/WebMachine/DataManager/Enums.vb:2-10 (OpenConnectionResult, PendingTransactionAction).
  • InfocadWeb/WebMachine/RequestCenter/Configuration/Settings.vb:242 (GetConnectionManager(...) As GlobalDataManager), :244-258 (cache RCCONNECTIONMANAGER, DbSessionParams).
  • InfocadWeb/WebMachine/RequestCenter.DAL.OracleODP/RequestDAL.vb:31,52,646,667 (cm.Fill/cm.ExecuteReader con nome procedure), ComplaintDAL.vb:17 / CallTypeDAL.vb:17 (Dim cm As GlobalDataManager = Configuration.Settings.GetConnectionManager).
  • Artefatto: Assembly/net8.0/DataManagerXNET.dll (presente).
  • Assenza di test: nessun progetto xUnit/NUnit/MSTest nel repo (da CLAUDE.md).