Cara Bootstrap dan Membuat Proyek .NET

Buat proyek .NET

Untuk membuat proyek .NET dari awal semudah menggunakan wizard Visual Studio. Buka File => New Project , atau Add New Project ke solusi yang ada. Setelah proyek baru dibuat, Anda dapat segera memulai pengkodean. Namun, pengaturan proyek default yang dihasilkan oleh penyihir hampir tidak dapat diterima untuk tim profesional, karena mereka menetapkan standar kualitas yang terlalu rendah. Selain itu, tidak ada penyihir yang tahu tentang langkah penyiapan lain yang perlu Anda lakukan di lingkungan pengembangan khusus Anda.

Dalam artikel ini, saya akan memandu Anda melalui beberapa pengaturan penting yang harus Anda aktifkan segera setelah Anda membuat proyek baru, yang penting untuk meminimalkan utang teknis di masa mendatang. Selain itu, kami akan meninjau beberapa praktik umum yang diterapkan banyak pengembang .NET saat mereka menyusun solusi dan proyek baru. Bahkan jika Anda tidak menerapkan beberapa dari ide-ide ini, itu bagus untuk belajar dan mendapatkan gambaran tentang apa yang kebanyakan tim lakukan.

Struktur

Memiliki struktur yang terdefinisi dengan baik sangat penting untuk proyek yang kompleks. Ini meningkatkan pengalaman orientasi saat pendatang baru bergabung dengan tim, dan membuat hidup Anda lebih mudah saat Anda mendukung proyek lama. Ada dua indikator kunci dari struktur yang baik:

• Menggunakan solusi dan folder proyek
• Penamaan yang konsisten

Folder

Folder solusi, terkadang disebut sebagai folder virtual , adalah instrumen yang sangat berguna untuk mengelompokkan proyek Anda. Dalam tampilan Solution Explorer cukup klik kanan dan pilih Add => New Solution Folder , lalu seret dan lepas salah satu proyek yang ada ke folder baru ini. Folder-folder ini tidak dicerminkan dalam sistem file, memungkinkan Anda menjaga struktur fisik tidak berubah, jadi memindahkan proyek dari satu Folder Solusi ke Folder Solusi lainnya tidak memindahkannya secara fisik.

Memiliki awalan bernomor tidak diperlukan, tetapi itu membuat folder tampak berurutan di jendela Solution Explorer .

Visual Studio dapat bekerja dengan beberapa solusi pada saat yang sama dengan memanfaatkan solusi tunggal yang dipartisi atau model Multi-solusi . Mereka jarang digunakan, jadi saya tidak akan membahasnya di artikel ini.

Tidak seperti folder Solusi , folder Proyek cocok dengan struktur folder fisik dan oleh karena itu tetap sebagai folder nyata pada disk. Selain itu, folder Proyek yang berisi kode C# harus cocok dengan namespace proyek. Ini membuat navigasi cukup alami. Anda bahkan dapat mengaktifkan aturan ReSharper untuk memperingatkan ketidakcocokan tersebut.

Penamaan

Ada beberapa aturan yang disarankan untuk diterapkan terkait penamaan:

• Gunakan CamelCase.
• Nama proyek harus cocok dengan nama rakitan keluarannya.
• Sebuah proyek yang berisi pengujian otomatis harus memiliki akhiran .Tests .
• Semua nama proyek harus memiliki awalan yang sama, seperti Company.Product .

Ada beberapa aturan yang masuk akal juga. Anda harus memutuskan sendiri kapan menerapkannya berdasarkan akal sehat (dan tata bahasa Inggris, tentu saja):

• Gunakan subjek dalam bentuk jamak ketika wadah (proyek atau folder) berisi beberapa contoh dari jenis yang sama (misalnya Tests atau System.Collections ).
• Gunakan bentuk tunggal ketika seluruh wadah berisi kode semua tentang satu entitas (misalnya System.Collections.ObjectModel`).
• Untuk singkatan singkat, gunakan huruf besar seperti yang dilakukan System.IO .
• Untuk singkatan yang panjang, gunakan CamelCase seperti Modules.Forex. .

Aturan praktis: singkatan singkat tidak boleh lebih dari tiga karakter.

Mengonfigurasi Solusi

Mengonfigurasi solusi semudah menyediakan semua file infrastruktur yang Anda butuhkan untuk lingkungan Anda. Meskipun beberapa di antaranya dapat ditambahkan nanti (seperti file integrasi CI), beberapa file sebaiknya Anda miliki di awal.

Pengaturan ReSharper

Jika Anda adalah pengembang .NET profesional, kemungkinan besar Anda menggunakan ReSharper. ReSharper sangat fleksibel dalam mengatur pengaturannya. Sebagai pemimpin tim, Anda dapat membuat dan mendistribusikan pengaturan Team Shared yang akan digunakan oleh pengembang lain. Pengaturan Team Shared disimpan dalam file dengan ekstensi .DotSettings . ReSharper akan memilih pengaturan ini secara otomatis jika nama file cocok dengan nama solusi Visual Studio:

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

Oleh karena itu, Anda harus membuat file ini sejak awal jika pada akhirnya ingin menerapkan beberapa pengaturan ke seluruh tim. Contoh yang baik adalah aturan menggunakan (atau tidak menggunakan) kata kunci var . File pengaturan Bersama Tim Anda hanya dapat memiliki satu aturan ini, sementara yang lain adalah preferensi pengembang. Perlu disebutkan bahwa pengaturan ReSharper dengan cara yang sama dapat diatur pada tingkat per proyek, karena Anda mungkin memiliki beberapa kode lama yang tidak dapat Anda ubah (misalnya, ubah untuk menggunakan kata kunci var ).

Jika Anda menamai file ini dengan benar, seperti yang ditunjukkan dalam contoh, maka setiap instance baru Visual Studio dengan pengaturan ReSharper baru akan memilih file ini secara otomatis dan menerapkan aturan. Jangan lupa untuk mengkomit file ini ke kontrol sumber.

Aturan Polisi Gaya

Sama seperti pengaturan ReSharper, Anda dapat berbagi pengaturan StyleCop. Jika Anda menggunakan ReSharper, maka Anda mungkin menginstal plugin integrasi yang akan memanfaatkan StyleCop dari ReSharper. Namun, StyleCop menyimpan pengaturannya secara independen dalam file bernama Settings.StyleCop . Demikian pula, Anda dapat memiliki file ini bersama dengan file solusi dan file proyek.

Jika Anda menggunakan StyleCop, jangan lupa untuk menjalankan alat konfigurasi StyleCop dan nonaktifkan pemeriksaan yang tidak ingin Anda lakukan. Secara default, semua pemeriksaan diaktifkan. Simpan pengaturan baru ke file ini dan komit ke kontrol sumber.

File Teks

Jika Anda sedang membangun produk publik dan akan menerbitkan kode sumber, jangan lupa untuk membuat dan mengkomit file-file ini juga:

 README.md LICENSE

Saya merekomendasikan menggunakan format penurunan harga untuk file README.md , karena menjadi standar industri dan didukung oleh layanan kontrol sumber publik seperti GitHub, serta server internal seperti BitBucket (sebelumnya Stash).

Spesifikasi NuGet

Jika Anda sedang membangun perpustakaan yang akan didistribusikan di NuGet Gallery, maka kemungkinan besar Anda perlu membuat file spesifikasi paket, seperti MyProject.nuspec . Saya lebih suka membuat file-file ini secara manual dan memasukkannya ke kontrol sumber. Paket biasanya dirilis oleh salah satu pekerjaan Continuous Integration (disingkat CI), tetapi juga kapan saja Anda dapat membuat dan menerbitkan paket secara manual dari konsol sebagai berikut:

 nuget.exe pack MyLibrary.nuspec

Hanya saja, jangan lupa untuk meningkatkan versi paket sebelum menjalankan perintah ini.

file khusus CI

Kita semua menggunakan server CI yang berbeda, dan semuanya memiliki skrip dan pengaturan konfigurasi yang berbeda. Saya hanya akan menyebutkan beberapa tambahan umum yang mungkin Anda pertimbangkan untuk ditambahkan:

• Pengaturan NUnit , yang menentukan rakitan apa yang berisi tes yang akan dieksekusi di server CI untuk pekerjaan tertentu. Semua tes praktis dibagi menjadi beberapa kategori. Ada pengujian unit yang harus dijalankan pada setiap build, pengujian kinerja yang dijalankan setiap malam, dan pengujian integrasi dijalankan pada basis per-rilis.
• Pengaturan NCover , yang menentukan rakitan pengujian apa yang harus dianalisis untuk cakupan pengujian.
• Pengaturan SonarQube , yang menentukan metrik perangkat lunak akan dikumpulkan.
• Skrip pekerjaan , seperti NAnt, PowerShell atau hanya file batch Windows.

Mengonfigurasi Proyek

File proyek, yaitu .csproj atau .vbpro , berisi semua pengaturan yang digunakan oleh Visual Studio dan MSBuild. Namun, tidak semuanya tersedia dari jendela Project Properties. Untuk mengedit file ini di Visual Studio secara manual, Anda harus melakukan hal berikut:

• Klik kanan pada proyek dalam tampilan Solution Explorer.
• Pilih Bongkar Proyek .
• Klik kanan lagi untuk memilih tindakan Edit xyz.csproj .
• Pengeditan lengkap.
• Klik kanan pada proyek lagi, dan pilih Muat Ulang Proyek .

Atau, Anda dapat membuka file proyek di editor teks favorit Anda, mengeditnya, dan menyimpannya. Saat Anda beralih kembali ke jendela Visual Studio, Anda akan diminta untuk memuat ulang proyek yang diubah.

Kontrol Peringatan

Membangun perangkat lunak berkualitas tinggi mengharuskan Anda untuk tidak pernah mengabaikan peringatan build. Oleh karena itu, Anda harus mengaktifkan tingkat peringatan maksimum dan memperlakukan setiap peringatan sebagai kesalahan. Perhatikan bahwa Anda harus melakukan ini untuk semua konfigurasi build yang Anda miliki, seperti Debug dan Rilis. Cara terbaik untuk melakukannya adalah dengan menulis pengaturan berikut ke grup properti umum:

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

Dan pastikan Anda tidak memiliki setelan yang sama di grup properti lainnya. Jika tidak, mereka akan menimpa properti yang sesuai dari grup umum.

FxCop

Menjalankan FxCop hanya praktis untuk dilakukan di setiap build. Sebagian besar tim lebih suka menjalankan FxCop dari waktu ke waktu (biasanya sebelum rilis) untuk memastikan tidak ada kesalahan parah yang terjadi. Namun, jika Anda ingin melakukan pemeriksaan pamungkas pada setiap build, tambahkan opsi ini:

 <RunCodeAnalysis>true</RunCodeAnalysis>

Perhatikan bahwa FxCop, seperti StyleCop, memiliki pengaturannya sendiri yang dapat ditempatkan di folder root dan ditambahkan ke kontrol sumber. Pengaturan ini kemungkinan digunakan saat menjalankan FxCop di server CI.

Dokumentasi

Bagian ini adalah tentang XmlDoc. Jika Anda sedang membangun API publik, maka Anda harus membuat dan memelihara dokumentasi API. Sebagian besar pengembang memulai dengan pengembangan API (pengkodean sebenarnya), dan tepat sebelum rilis mereka mengaktifkan pengaturan proyek Build / XML documentation file . Secara alami, setelah membangun kembali banyak kesalahan muncul, karena setiap XmlDoc yang hilang menghasilkan kesalahan pembuatan. Untuk menghindari ini, Anda harus mengaktifkan opsi yang disebutkan di awal.

Jika Anda terlalu malas untuk menulis dokumentasi yang benar, atau Anda tidak suka mengetik terlalu banyak teks, cobalah instrumen yang mengotomatiskan proses ini seperti GhostDoc.

Kontrak Kode

Kontrak Kode adalah kerangka kerja yang sangat baik dari Microsoft Research, yang memungkinkan Anda untuk mengekspresikan prakondisi, pascakondisi, dan invarian objek dalam kode Anda untuk pemeriksaan runtime, analisis statis, dan dokumentasi. Saya menggunakan ini di banyak proyek penting, dan itu sangat membantu, jadi saya mendorong Anda untuk mencobanya.

Jika Anda memutuskan untuk menggunakan Kontrak Kode, maka penting untuk mengaktifkan Kontrak sejak awal, saat Anda baru saja membuat proyek baru. Menambahkan Kontrak di tengah pengembangan dimungkinkan, tetapi akan membutuhkan perubahan melalui banyak kelas, untuk membuat Kontak cocok satu sama lain. Jadi, jangan lupa untuk mengaktifkan semua pengaturan yang diperlukan (setidaknya CodeContractsEnableRuntimeChecking ) dan pastikan pengaturan ini muncul di grup properti umum.

Penegakan Polisi Gaya

Sebelumnya kita berbicara tentang konfigurasi StyleCop untuk waktu pengembangan. Namun, ketika proyek Anda dibangun di server CI, ReSharper tidak berpengaruh di sana dan oleh karena itu kita harus mengaktifkan validasi StyleCop untuk dijalankan dengan MSBuild.

Ini biasanya dilakukan dengan modifikasi manual dari file proyek. Anda perlu membongkar proyek di Visual Studio, mengedit file proyek dan kemudian memuat kembali proyek:

 <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">

Pengaturan StyleCopTreatErrorsAsWarnings akan melakukan apa yang dikatakannya: itu akan merusak build Anda pada pelanggaran aturan StyleCop apa pun. Elemen impor diperlukan untuk MSBuild untuk menambahkan tugas StyleCop ke rantai build.

Anda mungkin telah memperhatikan jalur ke Program Files . Karena pengembang mungkin menginstal versi StyleCop yang berbeda, beberapa tim lebih suka menyimpan salinan pribadi dari instalasi StyleCop yang sama di bawah kendali sumber. Dalam hal ini, jalurnya akan relatif. Ini juga membuat pengaturan mesin CI lebih mudah, karena Anda tidak perlu menginstal StyleCop secara lokal.

Informasi Perakitan

Setiap proyek .NET yang dibuat oleh wizard Visual Studio akan memiliki file AssemblyInfo.cs yang terisi secara otomatis (lihat subfolder Properties ) yang berisi beberapa atribut Assembly , tetapi tidak ada wizard yang dapat mengisi semua atribut Assembly untuk Anda. Pastikan Anda memiliki setidaknya atribut berikut yang terisi:

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

Minimum ini diperlukan untuk setiap rakitan yang akan Anda distribusikan. Alasan praktis di balik ini adalah NuGet: Jika Anda menggunakan pembuatan spesifikasi NuGet otomatis dari file perakitan yang dipilih, alat ini akan memperoleh informasi yang diperlukan dari properti ini.

Anda juga dapat mengisi satu properti lagi di awal:

 InternalsVisibleTo

Properti ini membuat kelas dan antarmuka internal terlihat oleh rakitan yang ditentukan. Ini biasanya digunakan untuk pengujian otomatis yang akan Anda buat untuk proyek Anda.

String koneksi

Bagaimana mengelola string koneksi adalah pertanyaan yang sangat populer di Stack Overflow. Masalahnya adalah bagaimana membuat string koneksi unik untuk setiap pengembang atau pekerjaan CI, dan tidak mengekspos detail koneksi saat memublikasikan kode sumber.

Di App.config (untuk aplikasi desktop) atau Web.config (untuk aplikasi web), buat pengaturan berikut yang akan memuat file user.config runtime. Simpan ini di bawah kendali sumber Anda:

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

Rupanya, file user.config harus dikecualikan dari kontrol sumber, dan setiap pengembang harus memiliki salinan lokal dari file ini, menjaga privasi string koneksi:

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

.gitignore

Bagi mereka yang menggunakan Git sebagai kontrol sumber, penting untuk menambahkan beberapa pola file ke file .gitignore . Namun, komunitas pintar kami telah membuat file umum, yang dapat ditemukan di sini: github.com/github/gitignore/blob/master/VisualStudio.gitignore.

Anda harus menganggapnya sebagai file .gitignore referensi dan cukup tambahkan pengecualian khusus yang mungkin Anda perlukan.

Lencana GitHub

Anda mungkin telah melihat lencana yang tampak bagus muncul di halaman proyek README . Jika Anda memublikasikan proyek Anda di GitHub, pertimbangkan untuk menghubungkan proyek Anda ke layanan publik untuk:

• Bangunan: untuk menunjukkan bangunan gagal atau lolos.
• Pengujian: untuk menunjukkan cakupan pengujian dan status eksekusi pengujian.
• Penerbitan: untuk menampilkan versi paket NuGet terbaru.

Daftar lengkap lencana dan layanan terkait dapat ditemukan di shields.io. Anda mungkin menemukan banyak lencana menarik yang bagus untuk proyek Sumber Terbuka.

Setelah Anda mendaftarkan proyek Anda dengan layanan yang dipilih, Anda akan diberikan tautan ke gambar dan tautan sintaks penurunan harga lengkap, yang dapat Anda tambahkan ke file README.md Anda. Omong-omong, ini adalah salah satu alasan mengapa Anda harus memilih penurunan harga untuk file Readme .

Contoh lencana penurunan harga, dari proyek 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))

Validasi Struktur Solusi Otomatis

Meskipun Anda telah mengatur semua pengaturan yang kita bahas dalam artikel ini, cepat atau lambat salah satu pengembang Anda dapat mengubahnya dan melakukan perubahan ke kontrol sumber. Terkadang ini terjadi secara tidak sengaja, dan seringkali perubahan ini tidak terdeteksi selama peninjauan kode. Selain kecelakaan ini, kita harus memperhatikan kesalahan umum berikut:

• Referensi buruk : ketika seseorang mereferensikan perakitan lokal yang mungkin tidak dimiliki orang lain, atau ketika seseorang telah menghapus file dari disk, sementara tautan ke file tersebut tetap berada di file .csproj . Ini pasti akan merusak build, tetapi mungkin terlambat setelah perubahan didorong, dan yang lain menariknya. Ini sangat penting untuk file web statis, yang tidak dapat Anda verifikasi selama pembuatan.
• Konsistensi penamaan : alat seperti StyleCop dapat mengontrol kode sumber C#, tetapi tidak ada alat yang dapat menerapkan aturan untuk file Proyek atau properti Majelis. Contoh yang baik adalah ini: Kami ingin memberi nama proyek agar sesuai dengan nama rakitan keluaran, dan kami ingin nama proyek memiliki awalan yang sama seperti MyCompany.MyProduct .

Saya menemukan bahwa mengawasi kesalahan ini di Ulasan Kode rawan kesalahan dan harus otomatis. Jadi saya menulis alat sederhana yang melakukan ini dan banyak pemeriksaan lainnya untuk memverifikasi konsistensi solusi. Temui SolutionInspector. Ini adalah Open Source dan didistribusikan di bawah lisensi MIT. Anda dapat membangunnya dari kode sumber atau menginstal dari NuGet:

 Install-Package SolutionInspector

Alat ini menelusuri seluruh struktur solusi dan menerapkan banyak aturan validasi. Aturan dikonfigurasi oleh file XML, ditempatkan bersama dengan file solusi lainnya. Untuk mengontrol pengaturan berdasarkan proyek, Anda cukup menambahkan file yang sama dengan pengaturan yang berbeda ke folder proyek yang sesuai.

Tidak ada file konfigurasi yang diperlukan secara default. Dalam hal ini, alat akan menerapkan semua aturan yang tersedia dan menghasilkan semua masalah ke konsol.

Berikut adalah contoh file konfigurasi:

 <?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>

Meskipun pengaturannya agak deskriptif, saya akan menjelaskan beberapa di antaranya:

• MinSolutionFormatVersion / MaxSolutionFormatVersion akan mencegah pengembang Anda beralih versi Visual Studio.
• DetectMissingFiles sangat berguna untuk konten web statis atau file non-kode lainnya yang ditambahkan ke solusi atau proyek.
• AllowBuildEvents dapat mencegah penambahan peristiwa build kustom, yang mungkin melakukan hal-hal yang tidak perlu.
• Properties adalah elemen yang paling fleksibel: Anda dapat memeriksa properti apa pun dengan nilai yang diinginkan, apakah itu properti yang diketahui atau kustom.

Kesimpulan

Kami telah meninjau beberapa praktik standar, file konfigurasi, dan pengaturan proyek yang dapat Anda terapkan saat memulai proyek baru. Melakukan hal ini sejak awal akan mengurangi utang teknis di masa mendatang dan akan membuat kode sumber produk Anda terlihat bagus dan profesional. Untuk proyek Open Source, ini sangat penting, karena kontributor mana pun akan mengetahui ekspektasi Anda dengan memeriksa konfigurasi solusi dan file proyek.