Artikel ini membahas cara menulis pustaka untuk .NET menggunakan .NET CLI. CLI memberikan pengalaman efisien dan tingkat rendah yang berfungsi di semua OS yang didukung. Anda masih dapat membuat pustaka dengan Visual Studio, dan jika itu adalah pengalaman pilihan Anda, lihat panduan Visual Studio.
Prasyarat
Anda memerlukan .NET SDK yang terinstal di komputer Anda.
Untuk bagian dokumen ini yang berurusan dengan versi .NET Framework, Anda memerlukan .NET Framework yang diinstal pada komputer Windows.
Selain itu, jika Anda ingin mendukung target .NET Framework yang lebih lama, Anda perlu menginstal paket penargetan atau paket pengembang dari halaman unduhan .NET Framework. Lihat tabel ini:
Versi .NET Framework
Apa yang harus diunduh
4.6.1
Paket Penargetan .NET Framework 4.6.1
4.6
Paket Penargetan .NET Framework 4.6
4.5.2
Paket Pengembang .NET Framework 4.5.2
4.5.1
Paket Pengembang .NET Framework 4.5.1
4.5
Kit Pengembangan Perangkat Lunak Windows untuk Windows 8
4,0
Windows SDK untuk Windows 7 dan .NET Framework 4
2.0, 3.0, dan 3.5
Runtime .NET Framework 3.5 SP1 (atau versi Windows 8+)
Cara menargetkan .NET 5+ atau .NET Standard
Anda mengontrol kerangka kerja target proyek dengan menambahkannya ke file proyek Anda (.csproj atau .fsproj). Untuk panduan tentang cara memilih antara penargetan .NET 5+ atau .NET Standard, lihat .NET 5+ dan .NET Standard.
Jika Anda ingin menargetkan .NET Framework versi 4.0 atau di bawahnya, atau Anda ingin menggunakan API yang tersedia di .NET Framework tetapi tidak di .NET Standard (misalnya, System.Drawing), baca bagian berikut dan pelajari cara melakukan multitarget.
Cara menargetkan .NET Framework
Catatan
Instruksi ini mengasumsikan Anda memiliki .NET Framework yang terinstal di komputer Anda. Lihat Prasyarat untuk menginstal dependensi.
Perlu diingat bahwa beberapa versi .NET Framework yang digunakan di sini tidak lagi didukung. Lihat FAQ Kebijakan Siklus Hidup Dukungan .NET Framework tentang versi yang tidak didukung.
Jika Anda ingin mencapai jumlah maksimum pengembang dan proyek, gunakan .NET Framework 4.0 sebagai target dasar Anda. Untuk menargetkan .NET Framework, mulailah dengan menggunakan Moniker Kerangka Kerja Target (TFM) yang benar yang sesuai dengan versi .NET Framework yang ingin Anda dukung.
Versi .NET Framework
TFM
.NET Framework 2.0
net20
.NET Framework 3.0
net30
.NET Framework 3.5
net35
.NET Framework 4.0
net40
.NET Framework 4.5
net45
.NET Framework 4.5.1
net451
.NET Framework 4.5.2
net452
.NET Framework 4.6
net46
.NET Framework 4.6.1
net461
.NET Framework 4.6.2
net462
.NET Framework 4.7
net47
.NET Framework 4.8
net48
Anda kemudian menyisipkan TFM ini ke bagian TargetFramework file proyek Anda. Misalnya, berikut adalah cara Anda menulis pustaka yang menargetkan .NET Framework 4.0:
Dan itu saja! Meskipun ini dikompilasi hanya untuk .NET Framework 4, Anda dapat menggunakan pustaka pada versi .NET Framework yang lebih baru.
Cara multitarget
Catatan
Instruksi berikut mengasumsikan Bahwa Anda memiliki .NET Framework yang terinstal di komputer Anda. Lihat bagian Prasyarat untuk mempelajari dependensi mana yang perlu Anda instal dan tempat mengunduhnya.
Anda mungkin perlu menargetkan versi .NET Framework yang lebih lama saat proyek Anda mendukung .NET Framework dan .NET. Dalam skenario ini, jika Anda ingin menggunakan API dan konstruksi bahasa yang lebih baru untuk target yang lebih baru, gunakan #if arahan dalam kode Anda. Anda mungkin juga perlu menambahkan paket dan dependensi yang berbeda untuk setiap platform yang Anda targetkan untuk menyertakan BERBAGAI API yang diperlukan untuk setiap kasus.
Misalnya, Anda memiliki pustaka yang melakukan operasi jaringan melalui HTTP. Untuk .NET Standard dan .NET Framework versi 4.5 atau yang lebih tinggi, Anda dapat menggunakan HttpClient kelas dari System.Net.Http namespace. Namun, versi .NET Framework yang lebih lama tidak memiliki HttpClient kelas , sehingga Anda dapat menggunakan WebClient kelas dari System.Net namespace layanan untuk itu sebagai gantinya.
File proyek Anda bisa terlihat seperti ini:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>netstandard2.0;net40;net45</TargetFrameworks>
</PropertyGroup>
<!-- Need to conditionally bring in references for the .NET Framework 4.0 target -->
<ItemGroup Condition="'$(TargetFramework)' == 'net40'">
<Reference Include="System.Net" />
</ItemGroup>
<!-- Need to conditionally bring in references for the .NET Framework 4.5 target -->
<ItemGroup Condition="'$(TargetFramework)' == 'net45'">
<Reference Include="System.Net.Http" />
<Reference Include="System.Threading.Tasks" />
</ItemGroup>
</Project>
Anda akan melihat tiga perubahan besar di sini:
Simpul TargetFramework telah digantikan oleh TargetFrameworks, dan tiga TFM dinyatakan di dalamnya.
Ada simpul <ItemGroup> untuk target yang net40 menarik dalam satu referensi .NET Framework.
Ada simpul <ItemGroup> untuk target yang net45 menarik dalam dua referensi .NET Framework.
Simbol Praprosesor
Sistem build mengetahui simbol praprosesor berikut yang digunakan dalam #if arahan:
Kerangka Kerja Target
Simbol
Simbol tambahan (tersedia dalam .NET 5+ SDK)
Simbol platform (hanya tersedia saat Anda menentukan TFM khusus OS)
Simbol tanpa versi ditentukan terlepas dari versi yang Anda targetkan.
Simbol khusus versi hanya ditentukan untuk versi yang Anda targetkan.
Simbol <framework>_OR_GREATER ditentukan untuk versi yang Anda targetkan dan semua versi sebelumnya. Misalnya, jika Anda menargetkan .NET Framework 2.0, simbol berikut ditentukan: NET20, NET20_OR_GREATER, NET11_OR_GREATER, dan NET10_OR_GREATER.
Simbol NETSTANDARD<x>_<y>_OR_GREATER hanya didefinisikan untuk target .NET Standard, dan bukan untuk target yang mengimplementasikan .NET Standard, seperti .NET Core dan .NET Framework.
Ini berbeda dari moniker kerangka kerja target (TFM) yang digunakan oleh properti MSBuild TargetFramework dan NuGet.
Berikut adalah contoh penggunaan kompilasi bersyarah per target:
using System;
using System.Text.RegularExpressions;
#if NET40
// This only compiles for the .NET Framework 4 targets
using System.Net;
#else
// This compiles for all other targets
using System.Net.Http;
using System.Threading.Tasks;
#endif
namespace MultitargetLib
{
public class Library
{
#if NET40
private readonly WebClient _client = new WebClient();
private readonly object _locker = new object();
#else
private readonly HttpClient _client = new HttpClient();
#endif
#if NET40
// .NET Framework 4.0 does not have async/await
public string GetDotNetCount()
{
string url = "https://www.dotnetfoundation.org/";
var uri = new Uri(url);
string result = "";
// Lock here to provide thread-safety.
lock(_locker)
{
result = _client.DownloadString(uri);
}
int dotNetCount = Regex.Matches(result, ".NET").Count;
return $"Dotnet Foundation mentions .NET {dotNetCount} times!";
}
#else
// .NET Framework 4.5+ can use async/await!
public async Task<string> GetDotNetCountAsync()
{
string url = "https://www.dotnetfoundation.org/";
// HttpClient is thread-safe, so no need to explicitly lock here
var result = await _client.GetStringAsync(url);
int dotNetCount = Regex.Matches(result, ".NET").Count;
return $"dotnetfoundation.org mentions .NET {dotNetCount} times in its HTML!";
}
#endif
}
}
Jika Anda membangun proyek ini dengan dotnet build, Anda akan melihat tiga direktori di bin/ bawah folder:
net40/
net45/
netstandard2.0/
Masing-masing berisi .dll file untuk setiap target.
Cara menguji pustaka di .NET
Penting untuk dapat menguji di seluruh platform. Anda dapat menggunakan xUnit atau MSTest di luar kotak. Keduanya sangat cocok untuk unit yang menguji pustaka Anda di .NET. Cara Anda menyiapkan solusi dengan proyek pengujian akan bergantung pada struktur solusi Anda. Contoh berikut mengasumsikan bahwa direktori pengujian dan sumber berada di direktori tingkat atas yang sama.
Navigasi ke direktori proyek pengujian dan tambahkan referensi ke MyProject.Test dari MyProject.
cd MyProject.Test
dotnet add reference ../MyProject/MyProject.csproj
Pulihkan paket dan bangun proyek:
dotnet restore
dotnet build
Verifikasi bahwa xUnit berjalan dengan menjalankan dotnet test perintah . Jika Anda memilih untuk menggunakan MSTest, maka runner konsol MSTest harus berjalan sebagai gantinya.
Dan itu saja! Anda sekarang dapat menguji pustaka Anda di semua platform menggunakan alat baris perintah. Untuk melanjutkan pengujian sekarang setelah Anda menyiapkan semuanya, menguji pustaka Anda sangat sederhana:
Buat perubahan pada pustaka Anda.
Jalankan pengujian dari baris perintah, di direktori pengujian Anda, dengan dotnet test perintah.
Kode Anda akan dibangun kembali secara otomatis saat Anda memanggil dotnet test perintah.
Cara menggunakan beberapa proyek
Kebutuhan umum untuk pustaka yang lebih besar adalah menempatkan fungsionalitas dalam proyek yang berbeda.
Bayangkan Anda ingin membangun pustaka yang dapat dikonsumsi dalam C# idiomatik dan F#. Itu berarti bahwa konsumen pustaka Anda menggunakannya dengan cara yang alami untuk C# atau F#. Misalnya, di C# Anda mungkin menggunakan pustaka seperti ini:
using AwesomeLibrary.CSharp;
public Task DoThings(Data data)
{
var convertResult = await AwesomeLibrary.ConvertAsync(data);
var result = AwesomeLibrary.Process(convertResult);
// do something with result
}
Di F#, mungkin terlihat seperti ini:
open AwesomeLibrary.FSharp
let doWork data = async {
let! result = AwesomeLibrary.AsyncConvert data // Uses an F# async function rather than C# async method
// do something with result
}
Skenario konsumsi seperti ini berarti bahwa API yang diakses harus memiliki struktur yang berbeda untuk C# dan F#. Pendekatan umum untuk mencapai hal ini adalah dengan memperhitungkan semua logika pustaka ke dalam proyek inti, dengan proyek C# dan F# yang menentukan lapisan API yang memanggil ke proyek inti tersebut. Bagian lainnya akan menggunakan nama berikut:
AwesomeLibrary.Core - Proyek inti yang berisi semua logika untuk pustaka
AwesomeLibrary.CSharp - Proyek dengan API publik yang ditujukan untuk konsumsi di C#
AwesomeLibrary.FSharp - Proyek dengan API publik yang ditujukan untuk konsumsi di F#
Anda dapat menjalankan perintah berikut di terminal Anda untuk menghasilkan struktur yang sama dengan panduan ini:
mkdir AwesomeLibrary && cd AwesomeLibrary
dotnet new sln
mkdir AwesomeLibrary.Core && cd AwesomeLibrary.Core && dotnet new classlib
cd ..
mkdir AwesomeLibrary.CSharp && cd AwesomeLibrary.CSharp && dotnet new classlib
cd ..
mkdir AwesomeLibrary.FSharp && cd AwesomeLibrary.FSharp && dotnet new classlib -lang "F#"
cd ..
dotnet sln add AwesomeLibrary.Core/AwesomeLibrary.Core.csproj
dotnet sln add AwesomeLibrary.CSharp/AwesomeLibrary.CSharp.csproj
dotnet sln add AwesomeLibrary.FSharp/AwesomeLibrary.FSharp.fsproj
Ini akan menambahkan tiga proyek di atas dan file solusi yang menautkannya bersama-sama. Membuat file solusi dan menautkan proyek akan memungkinkan Anda memulihkan dan membangun proyek dari tingkat atas.
Referensi proyek-ke-proyek
Cara terbaik untuk mereferensikan proyek adalah dengan menggunakan .NET CLI untuk menambahkan referensi proyek. Dari direktori proyek AwesomeLibrary.CSharp dan AwesomeLibrary.FSharp, Anda dapat menjalankan perintah berikut:
File proyek untuk AwesomeLibrary.CSharp dan AwesomeLibrary.FSharp sekarang akan mereferensikan AwesomeLibrary.Core sebagai ProjectReference target. Anda dapat memverifikasi ini dengan memeriksa file proyek dan melihat yang berikut ini di dalamnya:
Anda dapat menambahkan bagian ini ke setiap file proyek secara manual jika Anda lebih suka tidak menggunakan .NET CLI.
Menyusun solusi
Aspek penting lainnya dari solusi multi-proyek adalah membangun struktur proyek keseluruhan yang baik. Anda dapat mengatur kode sesuka Anda, dan selama Anda menautkan setiap proyek ke file solusi Anda dengan dotnet sln add, Anda akan dapat menjalankan dotnet restore dan dotnet build pada tingkat solusi.
Berkolaborasi dengan kami di GitHub
Sumber untuk konten ini dapat ditemukan di GitHub, yang juga dapat Anda gunakan untuk membuat dan meninjau masalah dan menarik permintaan. Untuk informasi selengkapnya, lihat panduan kontributor kami.
Umpan balik .NET
.NET adalah proyek sumber terbuka. Pilih tautan untuk memberikan umpan balik:
Membuat proyek .NET dan mempelajari cara menambahkan paket serta mengelola dependensi paket di proyek Anda. Gunakan registri .NET Core CLI dan NuGet untuk menambahkan pustaka dan alat ke aplikasi C# Anda melalui Visual Studio Code.