Il CSV non è "solo testo" ── La gestione pratica dei file CSV nelle applicazioni aziendali C# (codifica dei caratteri, compatibilità con Excel, protezione dalle injection)

L’integrazione dei dati tramite CSV è tuttora protagonista indiscussa nel mondo delle applicazioni aziendali. E proprio perché sembra “solo testo separato da virgole”, è anche un ambito in cui si ripetono continuamente incidenti come parser fatti in casa che si rompono davanti a una virgola dentro un campo, file che si corrompono nei caratteri quando vengono aperti con Excel, o numeri di telefono che perdono lo zero iniziale.

In questo articolo, immaginando un’applicazione aziendale in C# che legge e scrive file CSV, ripercorriamo nell’ordine in cui più spesso sorgono dubbi nella pratica: le specifiche del CSV (RFC 4180) e i suoi dialetti nella realtà, come decidere la codifica dei caratteri, i problemi di compatibilità con Excel, le contromisure contro la CSV injection e le insidie operative.

1. La conclusione prima di tutto (tabella decisionale)

Le decisioni di progettazione sul CSV vanno ricavate a ritroso partendo da “chi (o cosa) aprirà quel file”.

Ecco le conclusioni, prima di tutto.

• Il parsing CSV tramite String.Split(',') si rompe secondo le specifiche, anche se sembra funzionare. Il motivo è che non riesce a gestire virgole, ritorni a capo e virgolette all’interno di un campo. Restando nell’ambito standard di .NET, usate TextFieldParser (capitolo 3).
• Gli incidenti di codifica dei caratteri avvengono in base a “come li interpreta Excel”. Per i CSV che le persone aprono con Excel, oggi la scelta più prudente è UTF-8 con BOM. Inoltre, in .NET c’è un’insidia: se il BOM viene aggiunto o meno dipende da come si specifica l’Encoding (capitolo 4).
• In .NET (Core) lo Shift_JIS non è disponibile senza un pacchetto aggiuntivo. Encoding.GetEncoding("shift_jis") ha successo solo dopo aver registrato CodePagesEncodingProvider dal pacchetto System.Text.Encoding.CodePages. È un punto classico in cui un’elaborazione CSV migrata da .NET Framework genera un’eccezione per la prima volta proprio in produzione.
• La perdita degli zeri iniziali e la conversione in data non si possono prevenire dal lato CSV. Un fatto importante è che neppure racchiudere il campo tra virgolette risolve il problema (capitolo 5).
• Le applicazioni che scrivono input dell’utente in un CSV necessitano di contromisure contro la CSV injection. I campi che iniziano con = o + vengono interpretati da Excel come formule (capitolo 6).

2. Le “specifiche” del CSV ── l’RFC 4180 e i dialetti della realtà

Per il CSV esiste, come standard di fatto, l’RFC 4180¹. Le regole essenziali da tenere a mente nella pratica sono solo queste quattro.

1. Il separatore di record è il ritorno a capo (CRLF), il separatore di campo è la virgola.
2. Se un campo contiene virgola, ritorno a capo o virgolette doppie, l’intero campo va racchiuso tra virgolette doppie.
3. Le virgolette doppie all’interno di un campo si escapano raddoppiandole in "".
4. I campi che non necessitano di essere racchiusi possono esserlo o meno, a piacere.

In altre parole, la riga seguente è un record di tre campi.

1001,"株式会社サンプル 営業部","住所は""東京都○○区1-2-3""です,と入力された備考"

E l’RFC 4180 è uno standard “di fatto”: nella realtà il CSV presenta un’infinità di dialetti. Ritorno a capo solo con LF, assenza di gestione delle virgolette, separatore tab o punto e virgola, presenza o assenza della riga di intestazione──proprio per questo, indicare nel documento delle specifiche di integrazione la dicitura “conforme all’RFC 4180” ed esplicitare codifica dei caratteri, BOM, carattere di fine riga e presenza dell’intestazione è l’attività con il miglior rapporto costo/beneficio per prevenire problemi futuri.

3. Non scrivetelo in proprio con Split(‘,’) ── la pratica della lettura

Alla luce delle regole del capitolo precedente, è chiaro perché String.Split(',') si rompe. Una virgola dentro un campo produce una suddivisione in più parti del previsto, e un ritorno a capo dentro le virgolette spezza la riga a metà. Il fatto che “il file che arriva ora funziona perché non contiene dati con virgole” non è altro che una situazione che può rompersi in qualsiasi momento, a seconda dei dati.

Per leggere correttamente restando nell’ambito standard di .NET, si può usare Microsoft.VisualBasic.FileIO.TextFieldParser. Il namespace è quello di Visual Basic, ma si usa normalmente anche da C#.

using Microsoft.VisualBasic.FileIO; // Microsoft.VisualBasic.Core (incluso nell'SDK per desktop Windows)

using var parser = new TextFieldParser(path, System.Text.Encoding.UTF8)
{
    TextFieldType = FieldType.Delimited,
    HasFieldsEnclosedInQuotes = true, // gestisce correttamente i campi racchiusi tra virgolette
    TrimWhiteSpace = false, // il valore predefinito è true (gli spazi iniziali e finali vengono rimossi silenziosamente). Disattivarlo per dati in cui gli spazi hanno un significato
};
parser.SetDelimiters(",");

while (!parser.EndOfData)
{
    try
    {
        string[]? fields = parser.ReadFields();
        if (fields is null) break;
        // elaborare fields[0], fields[1], ...
    }
    catch (MalformedLineException ex)
    {
        // riga malformata: con ErrorLine / ErrorLineNumber si può registrare contenuto e numero di riga
        logger.LogWarning("La riga {Line} del CSV ha un formato non valido: {Content}",
            ex.LineNumber, parser.ErrorLine);
    }
}

Il vantaggio pratico di TextFieldParser, oltre alla gestione delle virgolette (HasFieldsEnclosedInQuotes), è che permette di rilevare le righe malformate come MalformedLineException, con tanto di numero di riga. Nell’importazione CSV in ambito aziendale, “se una riga è malformata, si rifiuta l’intero file o si salta solo quella riga segnalandola?” è spesso il punto in cui le specifiche si biforcano, e questa gestione delle eccezioni si può tradurre direttamente in specifica.

Se serve anche il mapping tra colonne e oggetti, la conversione dei tipi e prestazioni adeguate a volumi di milioni di righe, conviene valutare l’adozione di una libreria CSV consolidata (una di quelle ampiamente usate su NuGet). Qualunque libreria si scelga, i punti da verificare sono sempre gli stessi quattro: “gestione delle virgolette secondo l’RFC 4180”, “specifica della codifica dei caratteri”, “gestione delle righe malformate” e “possibilità di lettura in streaming”.

Per la scrittura, dato che le specifiche sono più semplici, è realistico anche farla in proprio, ma è fondamentale concentrare l’escaping in un’unica funzione.

// concentrare l'escaping in fase di scrittura in questa unica funzione
static string ToCsvField(string? value)
{
    value ??= string.Empty;
    bool needsQuoting = value.Contains(',') || value.Contains('"')
        || value.Contains('\r') || value.Contains('\n');
    return needsQuoting ? $"\"{value.Replace("\"", "\"\"")}\"" : value;
}

Se resta anche un solo punto in cui, ad esempio, “la colonna degli importi viene concatenata a mano con string.Join”, quel punto diventerà la scena di un futuro incidente.

4. Codifica dei caratteri ── il comportamento di Excel e le insidie di .NET

4.1 Per l’apertura in Excel, UTF-8 con BOM

La maggior parte della corruzione dei caratteri nei CSV avviene perché Excel interpreta erroneamente la codifica del file. Se si apre con un doppio clic un CSV in UTF-8 senza BOM (il marcatore di pochi byte posto all’inizio del file), a seconda dell’ambiente può essere interpretato come ANSI (Shift_JIS negli ambienti giapponesi), e i caratteri giapponesi risultano completamente illeggibili. Con UTF-8 dotato di BOM, invece, viene riconosciuto correttamente come UTF-8: per questo, per i CSV che le persone apriranno con doppio clic in Excel, la scelta prudente oggi è UTF-8 con BOM.

A questo si aggiunge un’insidia lato .NET. Se il BOM viene aggiunto o meno dipende da come viene passato l’Encoding.

// UTF-8 senza BOM: comportamento predefinito se si omette la codifica
File.WriteAllText(path, csv);

// UTF-8 con BOM: Encoding.UTF8 (proprietà statica) è configurato per emettere il BOM
File.WriteAllText(path, csv, Encoding.UTF8);

// per rendere esplicita l'intenzione, è meno equivoco specificarlo tramite il costruttore
File.WriteAllText(path, csv, new UTF8Encoding(encoderShouldEmitUTF8Identifier: true));

Il fatto che il file risultante cambi a seconda che si passi Encoding.UTF8 o lo si ometta è una particolarità che, senza saperlo, non si nota. Una volta deciso come specifica che “l’integrazione tra sistemi è senza BOM” e “per Excel è con BOM”, conviene rendere esplicita l’intenzione anche nel codice usando new UTF8Encoding(...).

4.2 Per usare lo Shift_JIS in .NET (Core) serve una registrazione

Nell’integrazione con sistemi legacy, il CSV in Shift_JIS (code page 932) è ancora oggi in uso. Ciò che conta qui è che .NET (Core) / .NET 5 e successivi supportano di default solo la famiglia Unicode, ASCII e pochissime altre codifiche. Encoding.GetEncoding("shift_jis") genera un’eccezione finché non si aggiunge il pacchetto System.Text.Encoding.CodePages e non si registra CodePagesEncodingProvider.

using System.Text;

// registrare una sola volta all'avvio dell'applicazione (Program.cs ecc.)
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

// da questo momento si può ottenere lo Shift_JIS (code page 932)
Encoding sjis = Encoding.GetEncoding("shift_jis");

Un’applicazione che gestiva il CSV ai tempi di .NET Framework e che è stata migrata a .NET, e che riceve per la prima volta in produzione un file in Shift_JIS generando un’eccezione──è un punto classico di incidente. I punti di verifica per la migrazione sono riassunti in “Checklist pre-migrazione da .NET Framework a .NET”.

Inoltre, usando lo Shift_JIS non si può evitare il tema dei caratteri dipendenti dal produttore (come ① o ㈱), il problema della tilde ondulata (nami dash) e la perdita di caratteri presenti solo in Unicode. Questi aspetti di base sulla codifica dei caratteri sono spiegati in dettaglio in “Codifica dei caratteri e corruzione dei caratteri in Windows” e in “La pratica della codifica dei caratteri e dei caratteri di fine riga in Windows”.

5. Dati che si corrompono aprendoli con Excel ── perdita degli zeri iniziali, conversione in data, notazione esponenziale

Anche correggendo la codifica dei caratteri, la visualizzazione in Excel presenta un altro gruppo di problemi. Excel, quando apre un CSV, “interpreta” i valori.

E l’aspetto importante è che questi problemi non si prevengono nemmeno racchiudendo il campo tra virgolette. Le virgolette indicano solo un delimitatore a livello sintattico del CSV: Excel reinterpreta comunque il contenuto.

Nella pratica, le soluzioni possibili sono queste tre.

1. Far aprire il file seguendo la procedura corretta in Excel. Non con un doppio clic, ma tramite la funzione di Excel “Importa dati (da testo/CSV)”, specificando il tipo di colonna come “testo”: in questo modo il file non si corrompe. Vale la pena inserirlo nel manuale operativo.
2. Se l’obiettivo principale è la visualizzazione, esportare in xlsx. Poiché la formattazione delle celle può essere controllata in fase di esportazione, questo gruppo di problemi scompare alla radice. Per come costruire l’esportazione in Excel, fate riferimento a “Come costruire l’esportazione di report Excel”. Va inoltre ricordato che l’automazione COM di Excel su server o servizi è sconsigliata, poiché, come descritto in “Il problema dei processi EXCEL.EXE che restano attivi”, costituisce un terreno fertile per processi residui: scegliete quindi un’esportazione basata su libreria.
3. Il formato ="007" è una soluzione estrema, da usare come ultima risorsa. È un trucco per cui, aprendo il file in Excel, il valore viene mostrato come testo, ma dal punto di vista del CSV diventa “un file non standard contenente formule”, che rompe qualsiasi destinazione di importazione diversa da Excel. Non usatelo per file destinati a un uso condiviso con altri sistemi.

6. CSV injection ── non trasformare l’input dell’utente in una formula

Le applicazioni che esportano in CSV valori inseriti dall’utente (nome, note, indirizzo, ecc.) per poi farli aprire con Excel sono esposte a un vettore di attacco chiamato CSV injection. Poiché Excel interpreta come formule i campi che iniziano con =, +, -, @ e simili, un input malevolo (per esempio una formula pensata per lanciare un processo esterno, come =cmd|'/C calc'!A0) può essere eseguito nell’ambiente di un altro utente che apre il CSV.

La contromisura di base consiste nel neutralizzare in fase di esportazione i caratteri iniziali pericolosi.

// aggiunge un apice singolo davanti ai campi che potrebbero essere interpretati come formule.
// negli ambienti giapponesi vanno inclusi anche i caratteri a larghezza intera ＝＋－＠,
// poiché possono essere interpretati anch'essi come inizio di una formula
static string SanitizeForExcel(string value)
{
    if (value.Length > 0 && value[0]
        is '=' or '+' or '-' or '@' or '\t' or '\r' or '\n'
        or '＝' or '＋' or '－' or '＠')
    {
        return "'" + value;
    }
    return value;
}

L’apice singolo iniziale è il segnale con cui Excel “tratta il valore come testo”. Va notato che l’elenco dei caratteri iniziali pericolosi può variare a seconda dell’implementazione e della versione del foglio di calcolo, quindi progettare questa neutralizzazione nella direzione opposta (“far passare il valore così com’è solo se il carattere iniziale corrisponde a una lista di caratteri consentiti, ad esempio alfanumerici”) è più robusto rispetto a possibili casi non previsti. Tuttavia, se un altro sistema deve importare quel CSV, occorre tener presente che l’apice singolo resterebbe come parte del dato: è quindi legittimo anche decidere di separare i file in “per l’apertura in Excel” e “per l’importazione nei sistemi”. Per capire se combinare tutto questo anche con la validazione dell’input (ad esempio non permettere affatto un = iniziale), e più in generale per la progettazione della sicurezza dell’intera applicazione, fate riferimento a “Checklist minima di sicurezza per applicazioni Windows”.

7. Insidie operative ── dove si generano incidenti al di là del formato

Per finire, riassumiamo i punti in cui, al di là della sintassi del CSV in sé, si generano incidenti nella pratica.

• Non far dipendere il formato di numeri e date dalla cultura del sistema operativo. value.ToString() risente delle impostazioni regionali del sistema operativo. In un’impostazione regionale in cui il separatore decimale è la virgola, il valore verrebbe scritto come 1,5, in conflitto con il separatore del CSV. Per le conversioni destinate all’integrazione tra file, specificate esplicitamente CultureInfo.InvariantCulture e usate per le date un formato fisso come yyyy-MM-dd. La progettazione delle date è trattata in dettaglio in “Progettazione di data/ora e fuso orario nelle applicazioni aziendali”.
• Elaborare grandi volumi di dati in streaming ── ma se sia lecito farlo “riga per riga” dipende dalle specifiche. File.ReadAllLines carica in memoria tutte le righe come un array, quindi non è adatto a file di grandi dimensioni. Sostituirlo con File.ReadLines (enumerazione differita) o con la lettura riga per riga di StreamReader è lecito solo per i file per cui le specifiche dichiarano esplicitamente che non sono ammessi ritorni a capo all’interno di un campo. In un CSV conforme all’RFC 4180, che ammette ritorni a capo dentro le virgolette, la suddivisione per riga tronca un record a metà. In quel caso, usate TextFieldParser leggendo direttamente dal percorso del file (che può elaborare senza caricare tutto in memoria), oppure la lettura in streaming offerta dalla libreria CSV.
• Non far leggere, e non leggere, un “file ancora in fase di scrittura”. Il lato che scrive deve scrivere con un nome di file temporaneo e poi rinominarlo; il lato che importa deve verificare l’esclusione reciproca prima di leggere──questo schema di base per l’integrazione dei file è riassunto in “Nozioni di base sul controllo di esclusione reciproca nell’integrazione dei file”, mentre le attenzioni per l’importazione tramite monitoraggio di cartelle sono raccolte in “Guida pratica a FileSystemWatcher”.
• Prepararsi all’aumento o alla diminuzione delle colonne. Specificate come parte delle specifiche se “l’associazione avviene tramite i nomi delle colonne nella riga di intestazione” oppure “l’ordine delle colonne è fisso e, in caso di numero di colonne non corrispondente, il file viene rifiutato dopo un controllo”. Un riferimento implicito con un numero magico come fields[7] si romperà silenziosamente al minimo aggiunta di colonne da parte della controparte.
• Decidere in anticipo la gestione del ritorno a capo finale e delle righe vuote. Se ci sia o meno un ritorno a capo dopo l’ultima riga, e se le righe vuote vengano saltate o rifiutate, sono aspetti il cui comportamento varia a seconda dell’implementazione del parser. TextFieldParser salta le righe vuote.

Riepilogo

Il CSV ha l’aspetto di un formato che “si limita a separare con la virgola”, ma in realtà è un formato di integrazione pieno di dialetti. I punti essenziali nella pratica sono quattro──per la lettura, usare un componente in grado di gestire le virgolette (non scriverlo in proprio con Split), decidere la codifica dei caratteri ricavandola a ritroso da chi aprirà il file (in particolare Excel) e specificare nel documento anche la presenza o assenza del BOM, sapere che l’interpretazione dei valori da parte di Excel (perdita degli zeri, conversione in data) non si può prevenire dal lato CSV, e inserire contromisure contro la injection se si esporta input dell’utente──basta questo per eliminare, già in fase di progettazione, la maggior parte degli incidenti legati all’integrazione CSV.

L’indagine su corruzione dei caratteri o dei dati in un’integrazione CSV esistente, la messa a punto delle specifiche di integrazione con sistemi legacy, e l’implementazione ex novo di funzionalità di importazione ed esportazione CSV richiedono spesso valutazioni da fare osservando i file reali e le specifiche della controparte: in caso di dubbio, non esitate a contattarci.

Articoli correlati

• Codifica dei caratteri e corruzione dei caratteri in Windows
• La pratica della codifica dei caratteri e dei caratteri di fine riga in Windows
• Come costruire l’esportazione di report Excel
• Il problema dei processi EXCEL.EXE che restano attivi con l’interoperabilità COM di Excel
• Nozioni di base sul controllo di esclusione reciproca nell’integrazione dei file
• Guida pratica a FileSystemWatcher
• Progettazione di data/ora e fuso orario nelle applicazioni aziendali
• Checklist pre-migrazione da .NET Framework a .NET
• Checklist minima di sicurezza per applicazioni Windows

Aree di consulenza correlate

Komura Soft LLC si occupa di consulenza tecnica riguardante lo sviluppo di applicazioni aziendali che includono CSV e integrazione di file, l’indagine sulle cause di corruzione dei caratteri o dei dati in integrazioni esistenti, e la messa a punto delle specifiche di integrazione con sistemi legacy.

• Sviluppo di applicazioni Windows
• Consulenza tecnica e revisione della progettazione
• Contatti

Riferimenti

Articoli correlati

Articoli recenti con gli stessi tag per approfondire argomenti vicini.

Argomenti correlati

Queste pagine collocano l’argomento in un contesto più ampio di servizi e decisioni.

Servizi collegati all’argomento

L’articolo è direttamente collegato ai servizi seguenti.

Domande frequenti

Domande che ricorrono nelle consulenze sull’argomento dell’articolo.

Quale codifica dei caratteri dovrei usare per un file CSV?

Il principio generale è adattarsi alle specifiche di chi riceve il file, se già definite. Se invece si può decidere da zero, un buon punto di partenza è specificare nel documento delle specifiche UTF-8 con BOM per i file che le persone apriranno con Excel, e UTF-8 senza BOM per l'integrazione tra sistemi. Se un'integrazione con un sistema legacy richiede lo Shift_JIS, è necessario definire in anticipo la gestione dei caratteri dipendenti dal produttore e dei caratteri esterni (gaiji), altrimenti in seguito la corruzione dei caratteri diventerà una questione di responsabilità.

Conviene adottare una libreria CSV o è sufficiente scriverne una in proprio?

Per quanto riguarda la lettura, esistono casi (virgole, ritorni a capo e virgolette all'interno di un campo) che un String.Split fatto in casa non può gestire correttamente secondo le specifiche, quindi è opportuno affidarsi a un componente dedicato. Restando nell'ambito standard di .NET, TextFieldParser gestisce l'elaborazione delle virgolette equivalente all'RFC 4180. Se servono anche il mapping tra colonne e oggetti, la conversione dei tipi e prestazioni adeguate a grandi volumi di dati, conviene valutare l'adozione di una libreria CSV consolidata. Per la scrittura, dato che le specifiche sono più semplici, è realistico anche scriverla in proprio, ma è bene predisporre un'unica funzione comune per l'escaping delle virgolette e farvi passare tutto il codice.

Conviene usare il tab come separatore (TSV) invece della virgola?

Se i dati contengono frequentemente virgole (indirizzi, nomi, importi in valuta, ecc.), passare al TSV riduce la frequenza delle situazioni che richiedono le virgolette e rende anche più semplice la verifica visiva. Tuttavia, tab e ritorni a capo possono comunque comparire nei dati, quindi ciò non elimina la necessità di gestire le virgolette. Attenzione a non pensare che "essendo TSV non serva considerare il carattere separatore". Se è possibile raggiungere un accordo con la controparte, più che il carattere separatore, ciò che previene davvero gli incidenti è specificare chiaramente nel documento delle specifiche la codifica dei caratteri, le virgolette, il carattere di fine riga e la presenza o meno dell'intestazione.

Se l'obiettivo è l'apertura in Excel, conviene produrre un file Excel invece di un CSV?

Se l'obiettivo principale è che una persona visualizzi o stampi il file con Excel, vale la pena considerare l'esportazione in formato xlsx. Il CSV è un formato in cui, nel momento stesso in cui viene aperto con Excel, si verificano la perdita degli zeri iniziali o la conversione in data, e non esiste un modo per prevenire completamente questi fenomeni dal lato del CSV. Con xlsx, invece, è possibile controllare la formattazione delle celle direttamente in fase di esportazione. Se invece l'obiettivo principale è l'importazione in un altro sistema e la visualizzazione in Excel è solo un'aggiunta, è più realistico mantenere il CSV e indicare come procedura operativa "la procedura di importazione (usando la funzione di importazione dati)".

Profilo dell’autore

Pagina di presentazione dell’autore dell’articolo.

Go Komura

Rappresentante di KomuraSoft LLC

Specializzato nello sviluppo di software Windows, nella consulenza tecnica e nell’analisi dei malfunzionamenti, soprattutto nei progetti con sistemi esistenti e guasti difficili da riprodurre.