Come eseguire il bootstrap e creare progetti .NET

Crea progetto .NET

Creare un progetto .NET da zero è semplice come usare la procedura guidata di Visual Studio. Vai a File => New Project o Add New Project a una soluzione esistente. Una volta creato un nuovo progetto, puoi iniziare subito a programmare. Tuttavia, le impostazioni predefinite del progetto prodotte dai maghi sono difficilmente accettabili per i team professionistici, perché stabiliscono un livello di qualità troppo basso. Inoltre, nessun mago può conoscere altri passaggi di configurazione che devi eseguire nel tuo particolare ambiente di sviluppo.

In questo articolo, ti guiderò attraverso diverse impostazioni importanti che dovresti abilitare non appena crei un nuovo progetto, che è importante per ridurre al minimo un futuro debito tecnico. Inoltre, esamineremo alcune pratiche comuni applicate da molti sviluppatori .NET durante la strutturazione di soluzioni e nuovi progetti. Anche se non stai applicando alcune di queste idee, è bello imparare e avere una panoramica di ciò che fa la maggior parte dei team.

Struttura

Avere una struttura ben definita è vitale per progetti complessi. Ciò migliora l'esperienza di inserimento quando i nuovi arrivati ​​si uniscono a un team e ti semplifica la vita quando sostieni vecchi progetti. Ci sono due indicatori chiave di una buona struttura:

• Utilizzo di cartelle di soluzioni e progetti
• Denominazione coerente

Cartelle

Le cartelle delle soluzioni, a volte denominate cartelle virtuali , sono uno strumento molto utile per raggruppare i tuoi progetti. Nella vista Esplora soluzioni , fai semplicemente clic con il pulsante destro del mouse e seleziona Add => New Solution Folder , quindi trascina e rilascia qualsiasi progetto esistente in questa nuova cartella. Queste cartelle non sono rispecchiate nel file system, consentendoti di mantenere invariata la struttura fisica, quindi lo spostamento dei progetti da una cartella della soluzione a un'altra non li sposta fisicamente.

Non è necessario disporre di prefissi numerati, ma fa apparire le cartelle ordinate direttamente nella finestra Esplora soluzioni .

Visual Studio può lavorare con più soluzioni contemporaneamente sfruttando i modelli a soluzione singola partizionata oa più soluzioni . Sono usati raramente, quindi non li tratterò in questo articolo.

A differenza delle cartelle della soluzione, le cartelle del progetto corrispondono alla struttura delle cartelle fisiche e quindi persistono come cartelle reali sul disco. Inoltre, le cartelle di progetto contenenti un codice C# devono corrispondere allo spazio dei nomi del progetto. Questo rende la navigazione abbastanza naturale. Puoi anche abilitare una regola ReSharper per avvertire di tali disallineamenti.

Denominazione

Ci sono alcune regole consigliate da applicare in relazione alla denominazione:

• Usa CamelCase.
• Il nome di un progetto deve corrispondere al nome dell'assembly di output.
• Un progetto contenente test automatizzati dovrebbe avere il suffisso .Tests .
• Tutti i nomi dei progetti devono avere un prefisso comune, ad esempio Company.Product .

Ci sono anche poche regole ragionevoli. Dovresti decidere da solo quando applicarli in base al buon senso (e alla grammatica inglese, ovviamente):

• Utilizzare soggetti in forma plurale quando un contenitore (progetto o cartella) contiene più istanze dello stesso tipo (ad esempio Tests o System.Collections ).
• Utilizzare la forma singolare quando l'intero contenitore contiene codice tutto su una singola entità (ad esempio System.Collections.ObjectModel`).
• Per le abbreviazioni brevi, usa le maiuscole come fa System.IO .
• Per abbreviazioni lunghe, usa CamelCase come Modules.Forex. .

Una regola pratica: una breve abbreviazione non dovrebbe essere più lunga di tre caratteri.

Configurazione della soluzione

Configurare una soluzione è semplice come fornire tutti i file di infrastruttura necessari per il tuo ambiente. Sebbene alcuni di essi possano essere aggiunti in un secondo momento (come i file di integrazione CI), è meglio avere pochi file all'inizio.

Impostazioni di ReSharper

Se sei uno sviluppatore .NET professionista, molto probabilmente usi ReSharper. ReSharper è molto flessibile nella gestione delle sue impostazioni. In qualità di leader del team, puoi creare e distribuire le impostazioni del team condiviso che verranno utilizzate da altri sviluppatori. Le impostazioni di Team Shared sono archiviate in un file con estensione .DotSettings . ReSharper sceglierà queste impostazioni automaticamente se il nome del file corrisponde al nome della soluzione di Visual Studio:

 MyCompany.MyProduct.sln MyCompany.MyProduct.sln.DotSettings

Pertanto, dovresti creare questo file all'inizio se alla fine desideri applicare alcune impostazioni all'intero team. Un buon esempio potrebbe essere la regola di usare (o non usare) la parola chiave var . Il file delle impostazioni di Team Shared può avere solo questa regola, mentre le altre sono le preferenze degli sviluppatori. Vale la pena ricordare che allo stesso modo le impostazioni di ReSharper possono essere impostate a livello di progetto, perché potresti avere del codice legacy che non puoi modificare (es. cambia per usare la parola chiave var ).

Se hai denominato correttamente questo file, come mostrato nell'esempio, qualsiasi nuova istanza di Visual Studio con una nuova configurazione di ReSharper selezionerà questo file automaticamente e applicherà le regole. Non dimenticare di eseguire il commit di questo file nel controllo del codice sorgente.

Regole di StyleCop

Come per le impostazioni di ReSharper, puoi condividere le impostazioni di StyleCop. Se usi ReSharper, probabilmente hai installato un plug-in di integrazione che sfrutterà StyleCop di ReSharper. Tuttavia, StyleCop memorizza le sue impostazioni in modo indipendente in file denominati Settings.StyleCop . Allo stesso modo, puoi avere questo file insieme al file della soluzione e ai file di progetto.

Se stai utilizzando StyleCop, non dimenticare di eseguire lo strumento di configurazione StyleCop e disabilitare i controlli che non desideri eseguire. Per impostazione predefinita, tutti i controlli sono abilitati. Salva le nuove impostazioni in questo file e esegui il commit nel controllo del codice sorgente.

File di testo

Se stai creando un prodotto pubblico e hai intenzione di pubblicare il codice sorgente, non dimenticare di creare e salvare anche questi file:

 README.md LICENSE

Consiglio di utilizzare il formato markdown per il file README.md , perché è diventato uno standard industriale e supportato da servizi pubblici di controllo del codice sorgente come GitHub, nonché da server interni come BitBucket (ex Stash).

Specifiche NuGet

Se stai creando una libreria che deve essere distribuita su NuGet Gallery, molto probabilmente dovrai creare file di specifiche del pacchetto, come MyProject.nuspec . Preferisco creare questi file manualmente e inviarli al controllo del codice sorgente. I pacchetti vengono solitamente rilasciati da uno dei tuoi processi di integrazione continua (CI in breve), ma puoi anche creare e pubblicare un pacchetto in qualsiasi momento manualmente dalla console come segue:

 nuget.exe pack MyLibrary.nuspec

Non dimenticare di incrementare la versione del pacchetto prima di eseguire questo comando.

File specifici della CI

Utilizziamo tutti server CI diversi e tutti hanno script e impostazioni di configurazione diversi. Vorrei solo citare alcune delle aggiunte comuni che potresti considerare di aggiungere:

• Impostazioni NUnit , che specificano quali assembly contengono i test da eseguire sul server CI per lavori particolari. Tutti i test sono praticamente suddivisi in alcune categorie. Esistono unit test che dovrebbero essere eseguiti su ogni build, test delle prestazioni che vengono eseguiti ogni notte e test di integrazione vengono eseguiti in base alla versione.
• Impostazioni NCover , che specificano quali gruppi di test devono essere analizzati per la copertura del test.
• Verranno raccolte le impostazioni di SonarQube , che determinano le metriche del software.
• Script di lavoro , come NAnt, PowerShell o semplicemente file batch di Windows.

Configurazione dei progetti

I file di progetto, ovvero .csproj o .vbpro , contengono tutte le impostazioni usate da Visual Studio e MSBuild. Tuttavia, non tutti sono disponibili dalla finestra delle proprietà del progetto. Per modificare manualmente questi file in Visual Studio, è necessario effettuare le seguenti operazioni:

• Fare clic con il pulsante destro del mouse su un progetto nella vista Esplora soluzioni.
• Seleziona Scarica progetto .
• Fare nuovamente clic con il pulsante destro del mouse per scegliere l'azione Modifica xyz.csproj .
• Modifica completa.
• Fai nuovamente clic con il pulsante destro del mouse sul progetto e scegli Ricarica progetto .

In alternativa, puoi aprire un file di progetto nel tuo editor di testo preferito, modificarlo e salvarlo. Quando si torna alla finestra di Visual Studio, verrà richiesto di ricaricare il progetto modificato.

Controllo degli avvisi

La creazione di un software di alta qualità richiede di non ignorare mai gli avvisi di build. Pertanto, è necessario abilitare il livello massimo di avvisi e considerare tutti gli avvisi come errori. Nota che dovresti farlo per tutte le configurazioni di build che hai, come Debug e Release. Il modo migliore per farlo è scrivere le seguenti impostazioni nel gruppo di proprietà comuni:

 <WarningLevel>4</WarningLevel> <TreatWarningsAsErrors>true</TreatWarningsAsErrors>

E assicurati di non avere le stesse impostazioni in altri gruppi di proprietà. In caso contrario, sovrascriveranno le proprietà corrispondenti dal gruppo comune.

FxCop

L'esecuzione di FxCop è semplicemente pratica da eseguire su ogni build. La maggior parte dei team preferisce eseguire FxCop di tanto in tanto (di solito prima di un rilascio) per assicurarsi che non siano stati introdotti errori gravi. Tuttavia, se desideri eseguire il controllo definitivo su ogni build, aggiungi questa opzione:

 <RunCodeAnalysis>true</RunCodeAnalysis>

Si noti che FxCop, come StyleCop, ha le proprie impostazioni che possono essere inserite nella cartella principale e aggiunte al controllo del codice sorgente. È probabile che queste impostazioni vengano utilizzate durante l'esecuzione di FxCop sui server CI.

Documentazione

Questa parte riguarda XmlDoc. Se stai creando un'API pubblica, devi creare e mantenere la documentazione dell'API. La maggior parte degli sviluppatori inizia con lo sviluppo dell'API (codifica effettiva) e appena prima di un rilascio abilita l'impostazione del progetto Build / XML documentation file . Naturalmente, dopo un'altra ricostruzione vengono visualizzati un sacco di errori, perché ogni XmlDoc mancante provoca un errore di compilazione. Per evitare ciò, dovresti abilitare l'opzione menzionata all'inizio.

Se sei troppo pigro per scrivere una documentazione adeguata, o non ti piace digitare troppo testo, prova strumenti che automatizzano questo processo come GhostDoc.

Codice Contratti

Code Contracts è un framework eccellente di Microsoft Research, che consente di esprimere precondizioni, postcondizioni e invarianti degli oggetti nel codice per il controllo di runtime, l'analisi statica e la documentazione. L'ho usato in molti progetti critici e ha aiutato molto, quindi ti incoraggio a provarlo.

Se decidi di utilizzare i contratti di codice, è importante abilitare i contratti all'inizio, quando hai appena creato un nuovo progetto. L'aggiunta di contratti nel mezzo dello sviluppo è possibile, ma richiederà modifiche attraverso molte classi, per far corrispondere i Contatti tra loro. Quindi, non dimenticare di abilitare tutte le impostazioni richieste (almeno CodeContractsEnableRuntimeChecking ) e assicurati che queste impostazioni appaiano nel gruppo di proprietà comune.

Applicazione StyleCop

In precedenza abbiamo parlato della configurazione di StyleCop per il tempo di sviluppo. Tuttavia, quando il tuo progetto è basato su un server CI, ReSharper non ha alcun effetto lì e quindi dovremmo abilitare la convalida di StyleCop per l'esecuzione con MSBuild.

Questo di solito viene fatto modificando manualmente il file di progetto. È necessario scaricare il progetto in Visual Studio, modificare il file di progetto e quindi caricare nuovamente il progetto:

 <PropertyGroup> <!— add this to the common property group (common to Debug/Release/etc) —> <StyleCopTreatErrorsAsWarnings>false</StyleCopTreatErrorsAsWarnings> </PropertyGroup> <!— add this Import in the very bottom —> <Import Project="$(ProgramFiles)\MSBuild\Microsoft\StyleCop\v4.3\Microsoft.StyleCop.targets">

L'impostazione StyleCopTreatErrorsAsWarnings farà quello che dice: interromperà la tua build su qualsiasi violazione della regola StyleCop. L'elemento import è necessario affinché MSBuild aggiunga l'attività StyleCop alla catena di compilazione.

Potresti aver notato il percorso di Program Files . Poiché gli sviluppatori possono avere diverse versioni di StyleCop installate, alcuni team preferiscono mantenere una copia privata della stessa installazione di StyleCop sotto il controllo del codice sorgente. In questo caso, il percorso sarà relativo. Ciò semplifica anche la configurazione delle macchine CI, poiché non è necessario installare StyleCop localmente.

Informazioni sull'assemblaggio

Ogni progetto .NET creato dalla procedura guidata di Visual Studio avrà il file AssemblyInfo.cs popolato automaticamente (vedi sottocartella Proprietà ) che contiene alcuni degli attributi Assembly , ma nessuna procedura guidata può riempire tutti gli attributi Assembly per te. Assicurati di aver compilato almeno questi attributi:

• AssemblyTitle
• AssemblyDescription
• AssemblyCompany
• AssemblyProduct
• AssemblyCopyright
• AssemblyVersion

Questo minimo indispensabile è richiesto per tutti gli assembly che intendi distribuire. Un motivo pratico alla base di ciò è NuGet: se si usa la creazione automatica delle specifiche NuGet dal file di assieme selezionato, questo strumento trarrà le informazioni necessarie da queste proprietà.

Puoi anche popolare un'altra proprietà all'inizio:

 InternalsVisibleTo

Questa proprietà rende le classi e le interfacce interne visibili all'assembly specificato. Questo è generalmente utilizzato per i test automatizzati che creerai per il tuo progetto.

Stringhe di connessione

Come gestire le stringhe di connessione è una domanda molto popolare in Stack Overflow. Il problema è come rendere le stringhe di connessione univoche per ogni sviluppatore o un processo CI e non esporre i dettagli della connessione durante la pubblicazione del codice sorgente.

In App.config (per applicazioni desktop) o Web.config (per applicazioni Web), effettuare la seguente impostazione che caricherà il file user.config in runtime. Tieni questo sotto il tuo controllo del codice sorgente:

 <?xml version="1.0" encoding="utf-8" ?> <configuration> <connectionStrings configSource="user.config"></connectionStrings> </configuration>

Apparentemente, il file user.config dovrebbe essere escluso dal controllo del codice sorgente e ogni sviluppatore dovrebbe avere una copia locale di questo file, preservando la privacy della stringa di connessione:

 <connectionStrings> <add name="test" connectionString="Server=.;Database=...;"/> </connectionStrings>

.gitignore

Per coloro che utilizzano Git come controllo del codice sorgente, è importante aggiungere alcuni modelli di file al file .gitignore . Tuttavia, la nostra community intelligente ha già creato un file generalizzato, che può essere trovato qui: github.com/github/gitignore/blob/master/VisualStudio.gitignore.

Dovresti prenderlo come file .gitignore di riferimento e aggiungere semplicemente le esclusioni personalizzate di cui potresti aver bisogno.

Distintivi GitHub

Potresti aver visto dei badge di bell'aspetto apparire sulla pagina del progetto README . Se stai pubblicando il tuo progetto su GitHub, considera di collegare il tuo progetto ai servizi pubblici per:

• Building: per mostrare che una build sta fallendo o sta passando.
• Test: per mostrare la copertura del test e lo stato di esecuzione del test.
• Pubblicazione: per mostrare l'ultima versione del pacchetto NuGet.

Un elenco completo di badge e servizi correlati è disponibile su shields.io. Potresti trovare molti badge interessanti che vanno bene per i progetti Open Source.

Dopo aver registrato il tuo progetto con un servizio selezionato, ti verrà fornito un collegamento all'immagine e un collegamento completo di sintassi di markdown, che puoi aggiungere al tuo file README.md . A proposito, questo è uno dei motivi per cui dovresti preferire il markdown per i file Readme .

Esempi di badge di riduzione, dal progetto Roslyn:

[![Build Status]([http://dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/badge/icon)](http://dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/)](http://dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/badge/icon)](http://dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/)) [![Join the chat at [https://gitter.im/dotnet/roslyn](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dotnet/roslyn?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)](https://gitter.im/dotnet/roslyn](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dotnet/roslyn?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge))

Convalida automatica della struttura della soluzione

Anche se hai impostato tutte le impostazioni di cui abbiamo discusso in questo articolo, prima o poi uno dei tuoi sviluppatori potrebbe modificarle e applicare le modifiche al controllo del codice sorgente. A volte ciò accade per errore e spesso queste modifiche non vengono rilevate durante la revisione del codice. Oltre a questi incidenti, dovremmo prestare attenzione ai seguenti errori comuni:

• Riferimenti errati : quando qualcuno fa riferimento a un assembly locale che altri forse non hanno, o quando qualcuno ha eliminato un file dal disco, mentre il collegamento a quel file rimane nel file .csproj . Questo interromperà sicuramente la build, ma potrebbe accadere troppo tardi una volta che la modifica viene spinta e altri l'hanno ritirata. Ciò è particolarmente cruciale per i file Web statici, che non è possibile verificare durante la compilazione.
• Coerenza dei nomi : gli strumenti come StyleCop possono controllare il codice sorgente C#, ma nessuno strumento può applicare regole per i file di progetto o le proprietà dell'assieme. Un buon esempio è questo: vogliamo assegnare un nome ai progetti in modo che corrisponda al nome dell'assembly di output e vogliamo che i nomi dei progetti abbiano un prefisso comune come MyCompany.MyProduct .

Ho scoperto che la ricerca di questi errori in Code Reviews è soggetta a errori e dovrebbe essere automatizzata. Quindi ho scritto un semplice strumento che esegue questi e molti altri controlli per verificare la coerenza della soluzione. Incontra SolutionInspector. Questo è Open Source e distribuito sotto licenza MIT. Puoi compilarlo dal codice sorgente o installarlo da NuGet:

 Install-Package SolutionInspector

Lo strumento esamina l'intera struttura della soluzione e applica molte regole di convalida. Le regole sono configurate da file XML, inseriti insieme ad altri file di soluzione. Per controllare le impostazioni in base al progetto, aggiungi semplicemente lo stesso file con impostazioni diverse alla cartella del progetto corrispondente.

Nessun file di configurazione è richiesto per impostazione predefinita. In questo caso, lo strumento applicherà tutte le regole disponibili e trasmetterà tutti i problemi alla console.

Ecco l'esempio del file di configurazione:

 <?xml version="1.0" encoding="utf-8"?> <Settings xmlns:xsi="[http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">](http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">) <SolutionSettings> <MinSolutionFormatVersion>12.00</MinSolutionFormatVersion> <MaxSolutionFormatVersion>12.00</MaxSolutionFormatVersion> <DetectMissingFiles>true</DetectMissingFiles> <ProjectNamePrefix>MyCompany.MyProduct.</ProjectNamePrefix> <ProjectNameIsFileName>true</ProjectNameIsFileName> <IgnoredProjects> AVerySpecialProject1; AVerySpecialProject2; </IgnoredProjects> </SolutionSettings> <ProjectSettings> <DetectMissingFiles>true</DetectMissingFiles> <AllowBuildEvents>true</AllowBuildEvents> <AssemblyNameIsProjectName>true</AssemblyNameIsProjectName> <RootNamespaceIsAssemblyName>true</RootNamespaceIsAssemblyName> <RequiredImports>StyleCop.MSBuild.Targets</RequiredImports> <Properties> <TreatWarningsAsErrors>true</TreatWarningsAsErrors> <StyleCopTreatErrorsAsWarnings>false</StyleCopTreatErrorsAsWarnings> </Properties> </ProjectSettings> </Settings>

Sebbene le impostazioni siano piuttosto descrittive, ne spiegherò alcune:

• MinSolutionFormatVersion / MaxSolutionFormatVersion impedirà agli sviluppatori di cambiare versione di Visual Studio.
• DetectMissingFiles è molto utile per il contenuto Web statico o altri file non di codice aggiunti alla soluzione o a un progetto.
• AllowBuildEvents può impedire l'aggiunta di eventi di compilazione personalizzati, che potrebbero eseguire operazioni non necessarie.
• Properties è l'elemento più flessibile: puoi confrontare qualsiasi proprietà rispetto ai valori desiderati, siano essi proprietà note o personalizzate.

Conclusione

Abbiamo esaminato diverse pratiche standard, file di configurazione e impostazioni di progetto che puoi applicare quando inizi un nuovo progetto. Fare questo fin dall'inizio ridurrebbe il debito tecnico futuro e renderebbe il codice sorgente del tuo prodotto bello e professionale. Per i progetti Open Source questo è di particolare importanza, perché qualsiasi collaboratore conoscerà le tue aspettative esaminando le configurazioni delle soluzioni e i file di progetto.