# BFRAMEWORK ## Scopo Il presente documento descrive `BFramework`, la libreria di base dell'ecosistema B-Arts, e costituisce il punto di ingresso per la consultazione delle sue API. La documentazione è progettata per consentire agli sviluppatori e agli assistenti basati su Intelligenza Artificiale di individuare e riutilizzare le funzionalità già presenti nel framework prima di proporre implementazioni locali equivalenti. --- ## Identità - Pacchetto: `BFramework`. - Versione documentata: `5.0.1`. - Target framework: `.NET 8`, `.NET 9` e `.NET 10`. - Autore: Marco Balsamo. - Ruolo architetturale: Livello 0 dell'ecosistema B-Arts. `BFramework` è indipendente dalla tecnologia utilizzata per l'interfaccia utente e contiene classi di base, accesso ai dati, collezioni, conversioni, configurazione, logging, networking, sicurezza, reflection e utilità generali. I framework specializzati, tra cui `BFrameworkControls`, `BFrameworkWebControls` e `BFrameworkMAUI`, possono dipendere da `BFramework`. --- ## Regola fondamentale per le AI Prima di generare una nuova funzione, classe di supporto o implementazione infrastrutturale, verificare se il requisito è già coperto da un tipo di `BFramework`. Durante la generazione del codice: - utilizzare namespace, nomi dei tipi e firme esattamente come documentati; - non inventare overload o comportamenti non presenti nelle schede; - consultare gli esempi verificati quando disponibili; - rispettare le regole definite in `RULES.md`, `DESIGN.md` e `ASSISTANTS.md`; - considerare il codice sorgente come fonte di verità in caso di discrepanza; - richiedere chiarimenti quando il contratto pubblico non definisce il comportamento necessario. Per conversioni e formattazioni, consultare sempre prima `B.BStatics`. Utilizzare `BConvert` per le conversioni supportate e `BGlobal` per la rappresentazione coerente di date, ore, numeri, valori booleani e testo. Non reimplementare localmente funzioni già disponibili nel framework. --- ## Organizzazione della documentazione La documentazione dettagliata si trova nella cartella [`BFramework`](BFramework/README.md). La mappa [`Domande e casi d'uso`](BFramework/USE_CASES.md) indirizza le richieste tipiche degli sviluppatori verso le classi e gli esempi appropriati. Per ogni namespace sono disponibili: - un file `README.md` con l'elenco dei tipi pubblici; - un file `.md` per ogni tipo pubblico; - un file `.Examples.md` separato quando esiste un esempio utile e verificato. Le schede dei tipi riportano il contratto pubblico ricavato dall'assembly `BFramework` versione `5.0.1`: dichiarazione, classe base, interfacce, costruttori, proprietà, campi, eventi, metodi e tipi annidati. --- ## Aree funzionali principali | Area | Namespace principale | Responsabilità | |---|---|---| | Attributi | `B.BAttributes` | Metadati dichiarativi utilizzati dall'ecosistema. | | Classi base | `B.BBaseClass` | Oggetti, servizi, batch, impostazioni e worker service di base. | | Configurazione | `B.BConfigurations` | Impostazioni applicative e configurazione dei bundle. | | Dati | `B.BData` | Connessioni, comandi, parametri, reader, tabelle, dataset e modelli dati comuni. | Per il database, il codice applicativo deve usare `BConnection`: `ApriDT` restituisce un `DataTable`, `ApriDS` restituisce un `DataSet` e i metodi `Execute*` eseguono direttamente i comandi dalla connessione. `BCommand` è un componente di basso livello e non va normalmente proposto dalle AI. | Disegno | `B.BDrawing` | Rappresentazione e conversione dei colori. | | Formule | `B.BFormules` | Condizioni ed espressioni componibili. | | Contratti | `B.BInterfaces` | Interfacce condivise dai componenti B-Arts. | | File e stream | `B.BIO` | Lettura, scrittura e rappresentazione dei file. | | Collezioni | `B.BLists` | Collezioni e dizionari specializzati. | | Logging | `B.BLog` | Testi di log, configurazione e tracciamento. | | Posta elettronica | `B.BMail` | Configurazione e invio SMTP. | | Markdown | `B.BMarkdown` | Parsing Markdown, albero dei nodi e rendering HTML personalizzabile. | | Rete | `B.BNet` | HTTP, FTP e accesso a risorse di rete. | | Social authentication | `B.BNet.BSocial` | Provider e modelli per autenticazione social. | | Office | `B.BOffice` | Creazione e rappresentazione di documenti Excel. | | Reflection | `B.BReflections` | Ispezione e gestione di proprietà e tipi. | | Report | `B.BReports` | Modelli e servizi di reporting. | | Sicurezza | `B.BSecurity` | Autenticazione, cifratura, licenze e file firmati. | | Funzioni generali | `B.BStatics` | Conversioni, JSON, calendario, enumerazioni e utilità statiche. | | Threading | `B.BThreading` | Code, wrapper e timer per attività e thread. | | Utilità | `B.BUtility` | Cronometria, file INI, minificazione, QR code e archivi ZIP. | | SQL | `B.BUtility.BSQL` | Analisi e supporto per strutture SQL. | | Web API | `B.BWebApi` | Risposte HTTP e sicurezza dei servizi API. | Alcuni tipi, come `BColors` e attualmente `BPascalCaseNamingPolicy`, sono esposti nel namespace globale. Le AI devono utilizzare il namespace reale indicato nella relativa scheda e non devono inventare o normalizzare autonomamente un namespace `B.*`. --- ## Percorso consigliato 1. Consultare l'[indice completo delle API](BFramework/README.md). 2. Individuare il namespace relativo al requisito. 3. Aprire la scheda del tipo candidato. 4. Verificare costruttori, proprietà, metodi e overload. 5. Consultare l'eventuale file `.Examples.md`. 6. Generare codice conforme alle convenzioni B-Arts. --- ## Limiti della documentazione Una firma pubblica dimostra che un membro è disponibile, ma non descrive necessariamente tutti gli effetti collaterali, le eccezioni o i vincoli operativi. Quando tali informazioni non sono documentate, il comportamento deve essere considerato non definito fino alla verifica del codice sorgente o all'integrazione della scheda. --- ## Documenti correlati - `START.md` - `RULES.md` - `DESIGN.md` - `ECOSYSTEM.md` - `ASSISTANTS.md` - `BSTUDIO.md`