B-Arts Documentation
Indice generale

BFramework - domande e casi d'uso

Scopo

La creazione iniziale di applicazioni e progetti non è trattata qui: deve seguire i modelli B-Arts, documentati separatamente.

Regole trasversali

Per qualunque richiesta:

  1. cercare una funzione già presente nel framework prima di scriverne una nuova;

  2. usare BConvert per le conversioni di valore supportate;

  3. usare BGlobal per formattare date, ore, numeri, booleani e testo;

  4. consultare tutte le classi di B.BStatics prima di implementare funzioni generali equivalenti;

  5. verificare B.BLists prima di proporre List<T>, Dictionary<TKey, TValue> o collezioni locali;

  6. usare comunque le collezioni standard .NET quando le classi B-Arts non coprono il requisito;

  7. non modificare i file generati da BStudio in BClasses;

  8. inserire le personalizzazioni delle classi generate nelle corrispondenti classi partial di BClassesPartial;

  9. non inventare membri, overload o comportamenti non documentati.

Dati e database

Domanda dello sviluppatore Percorso consigliato
Come apro una connessione al database? Istanziare direttamente BConnection con BSettingDatabase. Non proporre factory o interfacce nel normale codice applicativo.
Come eseguo una stored procedure con parametri? using BConnection cnn = new BConnection(setting);, poi cnn.AddParameter(...) e cnn.ExecuteNonQuery(nome, CommandType.StoredProcedure). Se restituisce righe usare ApriDT; per più tabelle ApriDS. Vedere gli esempi di BConnection.
Come recupero un DataTable? BConnection.ApriDT; non proporre normalmente BCommand.
Come recupero più result set in un DataSet? BConnection.ApriDS(nomeStored); le tabelle sono disponibili in DataSet.Tables. Usare BDataSet solo se servono funzionalità specifiche come Reload.
Come eseguo INSERT, UPDATE o DELETE senza leggere righe? BConnection.ExecuteNonQuery direttamente sull'istanza della connessione.
Come gestisco una transazione? Apertura, commit e rollback negli esempi di BConnection.
Come inserisco massivamente un DataTable? BConnection.InsertDT con BColumnBind.
Quando conviene mappare i risultati in oggetti? Quando gli oggetti devono essere riutilizzati, modificati, validati, trasferiti tra livelli o devono contenere comportamento. Per consumo immediato, griglie, report ed esportazioni preferire ApriDT o ApriDS.
Devo usare BDataReader al posto di ApriDT? Solo se il requisito richiede esplicitamente una lettura sequenziale. Nel normale codice applicativo B-Arts preferire ApriDT; non proporre automaticamente BDataReader.
Come importo un file delimitato o a larghezza fissa? Overload ApriDT documentati in BConnection, BCodificaTracciato e relativi campi.
Come importo dati che contengono anche byte[]? Formato BIFFile, pensato per popolamenti iniziali e patch dati B-Arts.
Come aggiorno la struttura o gli oggetti del database? BAggiornaDB.
Come analizzo colonne, indici e chiavi primarie SQL? Namespace B.BUtility.BSQL.

Modelli e classi generate

Domanda dello sviluppatore Percorso consigliato
Da quale classe derivano i modelli BStudio? BBaseObject.
Dove aggiungo proprietà o logica a una classe generata? Classe omonima partial in BClassesPartial; non modificare BClasses. Vedere gli esempi di BBaseObject.
Come mappo una DataRow su un oggetto B-Arts? Contratto e hook di BBaseObject, più BReflection quando serve operare dinamicamente.
Come descrivo caption, ordine, foreign key o autocomplete? Namespace B.BAttributes.
Come leggo o assegno una proprietà dinamicamente? BReflection e BValueProperty.

Conversioni, formattazione e JSON

Domanda dello sviluppatore Percorso consigliato
Come converto un valore proveniente dal database senza usare Parse? BConvert.
Come gestisco null e DBNull? Metodi di controllo e conversione di BConvert.
Come formatto una data, un'ora o un numero secondo B-Arts? BGlobal: FormattaData, FormattaOra, FormattaNumero e VisionaNumero.
Come formatto booleani o testo? FormattaBool, FormattaTesto e FormattaTestoNumerico in BGlobal.
Come serializzo o deserializzo JSON? BJSON.
Come salvo tutte le proprietà di un setting? BBaseSetting, salvataggio JSON completo.
Come salvo soltanto le proprietà marcate come setting? BBaseSetting.UpdateOnlyBFieldSetting con BFieldSettingAttribute.
Come lavoro con enum condivisi? BEnum e BEnumerations.

Liste, dictionary e collezioni

Domanda dello sviluppatore Scelta consigliata
Mi serve un dizionario consultabile sia per chiave sia per posizione di inserimento? BDictionary<TKey, TValue>. Supporta gli indicizzatori per chiave e per indice e la rimozione in entrambe le forme.
Devo trasformare un DataTable, DataView, enum, dictionary o lista di oggetti in coppie ID/descrizione? BDictionary<string, string>.CreateInstanceFromSource.
Se una chiave non esiste voglio ottenere il valore predefinito senza un'eccezione? L'indicizzatore per chiave di BDictionary restituisce default; verificare comunque se questo comportamento è adatto al caso d'uso.
Devo conservare valori B-Arts identificati da un codice stringa? BCollection quando servono direttamente BItemField e accesso collection["codice"].
Devo contare quante volte compare una stringa senza distinguere maiuscole e minuscole? BGroupList: AddItem incrementa e DeleteItem decrementa fino a rimuovere la voce.
Devo associare codici a valori B-Arts e cercare anche le chiavi o gli elementi a partire dal valore? BListOfBItemField.
Devo rappresentare una versione B-Arts scomposta in revisione e versione maggiore/minore? BItemVersion.
Mi serve soltanto una sequenza generica tipizzata, senza indicizzazione o comportamento B-Arts? Usare List<T> o un'altra interfaccia/collezione .NET adeguata. Non forzare BCollection, che contiene specificamente BItemField.
Mi serve un dizionario standard senza accesso per posizione o conversioni B-Arts? Usare Dictionary<TKey, TValue>.
Mi serve un comparer personalizzato, per esempio chiavi senza distinzione tra maiuscole e minuscole? Usare un Dictionary<TKey, TValue> costruito con il comparer appropriato: BDictionary espone attualmente il solo costruttore senza parametri.
Più thread devono aggiornare contemporaneamente il dizionario? Usare ConcurrentDictionary<TKey, TValue>; BDictionary non dichiara garanzie di thread safety.
Devo conservare chiavi duplicate o più valori per la stessa chiave? Usare una struttura .NET adeguata, per esempio List<T>, ILookup<TKey, TValue> o Dictionary<TKey, List<TValue>>; BDictionary richiede chiavi univoche.
Mi servono semantiche di coda, pila, set o collezione immutabile? Usare rispettivamente le collezioni .NET dedicate; le classi B.BLists non devono essere scelte soltanto perché appartengono al framework.

Regola di scelta

Preferire una classe B.BLists quando almeno una sua funzione specifica coincide con il requisito. Preferire la collezione .NET più semplice e semanticamente corretta quando serve soltanto il comportamento standard o quando sono richieste concorrenza, immutabilità, comparer personalizzati, duplicati, code, pile o set.

File, configurazione e contenuti

Domanda dello sviluppatore Percorso consigliato
Come leggo o scrivo testo e byte? BFile oppure le funzioni compatibili in BSystem.
Come concateno più parti di un percorso Web? BSystem.CreatePathWeb(part1, part2, ...); per aggiungere un singolo nome file usare BSystem.CreatePathFileWeb. Vedere gli esempi di BSystem.
Come concateno parti di un percorso del filesystem? BSystem.CreatePath(part1, part2, ...); per aggiungere un singolo nome file usare BSystem.CreatePathFile.
Come adatto uno stream esistente? BFileStream.
Come leggo o aggiorno un file INI? BINI.
Come leggo o scrivo appSettings? BConfigurationManager e BConfigSetting.
Come creo o estraggo un archivio ZIP? BZip.
Come minifico JavaScript o CSS? BMinifier.
Come genero un QR code? BQRCode.

Markdown e contenuti HTML

Domanda dello sviluppatore Percorso consigliato
Come converto una stringa Markdown in HTML senza librerie esterne? BMarkdownParser e BMarkdownDocument.ToHTML; vedere gli esempi.
Come leggo e converto direttamente un file .md? BMarkdownFile, che riutilizza BFile per la lettura.
Come personalizzo le classi CSS dell'HTML generato? BMarkdownHtmlRenderer e il foglio BMarkdown.css distribuito nel progetto.
Come ispeziono o modifico la struttura del documento Markdown? BMarkdownDocument e BMarkdownNode.
Posso renderizzare Markdown ricevuto da utenti non affidabili? Il testo viene codificato, ma i nodi HTML sono emessi senza sanitizzazione: applicare una sanitizzazione adeguata prima del rendering.
Il parser implementa tutto CommonMark/GFM? Non dichiararlo: usare soltanto le funzionalità elencate nel README del namespace.

Sicurezza e Web API

Domanda dello sviluppatore Percorso consigliato
Come cifro e decifro un valore? BCrypter; usare BCrypterLegacy soltanto per leggere e migrare dati storici.
Come proteggo una chiamata Web API B-Arts? Flusso completo Secure Key negli esempi di BApiServiceSecureKey.
Come invio la Secure Key? Generarla con BCrypter.GetSecurePassword e inviarla nell'header B-SECURE-KEY, sempre tramite HTTPS.
Come verifico la Secure Key sul server? Leggerla con BApiServiceSecureKey, generare il valore server dalla stessa chiave e usare BCrypter.CheckSecurePassword.
Come restituisco una risposta API uniforme? BHTTPApiResponse<T>; impostare coerentemente anche lo status HTTP reale.
Come leggo un file P7M/CMS? BSignedFile.
Come gestisco una licenza desktop o Web? BLicense e BLicenseWeb.
Come eseguo codice con un'identità Windows? BAuthentication.

Rete, posta e servizi esterni

Domanda dello sviluppatore Percorso consigliato
Come eseguo GET, POST o DELETE HTTP? BHttp. Per la Secure Key Web API consultare anche B.BWebApi.
Come trasferisco file via FTP/FTPS? BFTPClient e BFtpItem.
Come collego una condivisione di rete Windows? BNetUse.
Come invio una email? BSMTP e BSenderMailConfig.
Come autentico tramite Google, Microsoft o Apple? Namespace B.BNet.BSocial, scegliendo il provider e normalizzando il risultato in BSocialUser.

Logging e diagnostica

Domanda dello sviluppatore Percorso consigliato
Come accumulo messaggi di log in memoria? BLogText; abilitarne il lock se condiviso tra flussi concorrenti.
Come scrivo log su file o Event Log? BLogTracer e BLogTracerConfig.
Come misuro la durata di un'operazione? BCrono.
Dove recupero informazioni sull'applicazione in esecuzione? BAppInfo.

Attività concorrenti e servizi

Domanda dello sviluppatore Percorso consigliato
Come accodo elaborazioni asincrone con concorrenza e retry? BTaskQueue e BTaskWrapperBase.
Come gestisco una coda sincrona protetta? BSyncQueue.
Come eseguo elaborazioni basate esplicitamente su thread? BThreadQueue, BThreadLockQueue e BThreadWrapperBase.
Come eseguo un callback periodico? BTimer.
Come implemento un worker ospitato? BBaseWorkerService.
Come implemento un servizio o batch B-Arts? BBaseService e BBaseBatch.

Per nuovo codice asincrono ordinario, partire dallo standard .NET Task/async/await; scegliere le classi esplicite basate su thread solo quando il requisito lo richiede.

Office, colori e utilità applicative

Domanda dello sviluppatore Percorso consigliato
Come creo un foglio Excel formattato? BExcel e i tipi BExcelSheet, BExcelRow, BExcelCell e BExcelStyle.
Quale formato produce BExcel? SpreadsheetML 2003 XML; non presentarlo come vero file .xlsx.
Come rappresento o converto un colore? BColor.
Come ottengo i colori standard o una palette ordinata? BColors e BColorBrightnessHueComparer.
Come eseguo calcoli di percentuale o arrotondamento? BMaths.
Come gestisco intervalli, mesi e festività? BCalendar.
Come compongo condizioni o espressioni testuali? BCondition e BExpressions, attenendosi ai comportamenti documentati.

Reportistica

Domanda dello sviluppatore Percorso consigliato
Come genero un PDF partendo da un file RDLC locale? BReportingService con eEngine.BReportEngine; vedere gli esempi.
Come passo dati e parametri a un RDLC? BReport: DataSource, Parameters e SubReports.
Come eseguo un report pubblicato su SQL Server Reporting Services? BReportingService costruito con eVersion, server e opzione SSL.
Come pubblico cartella, origine dati e file RDL su SSRS? CreateReportFolderAsync, CreateDataSourceAsync e CreateReportAsync.
Come salvo il report direttamente su disco? Impostare BReport.Result = Save e valorizzare PathSave.
Come restituisco il report da una Web API o da una UI? Usare il BFile contenuto in BReportResult; Preview e Download non producono direttamente una risposta UI/HTTP.