NetSparkle
NetSparkleUpdater 2.3.0
Kerangka Pembaruan Perangkat Lunak yang mudah disesuaikan untuk proyek C# .NET dengan UI bawaan untuk WinForms, WPF, dan Avalonia
Netsparkle adalah kerangka pembaruan perangkat lunak yang sangat dapat dikonfigurasi untuk C# yang kompatibel dengan .NET 6+ dan .NET Framework 4.6.2+, memiliki UI pra-buatan untuk .NET Framework (WinForms, WPF) dan .NET 6+ (WinForms, WPF, Avaloneia), menggunakan ED2 or or-oD. Sama sekali! Anda menyediakan, di suatu tempat di Internet, aplikasi yang dilemparkan dengan informasi pembaruan dan versi, bersama dengan catatan rilis dalam format Markdown atau HTML. Perpustakaan ini kemudian membantu Anda memeriksa pembaruan, menunjukkan kepada pengguna catatan rilis, dan menawarkan untuk mengunduh/menginstal versi baru perangkat lunak.
Tipe Unduh Pembaruan yang Didukung Built-in:
Silakan lihat upgrading.md untuk informasi tentang perubahan versi utama, pembaruan, dll.
Netsparkle tersedia melalui Nuget. Untuk memilih paket nuget untuk digunakan:
NetSparkleUpdater.SparkleUpdater package Jika Anda tidak peduli memiliki UI bawaan dan dapat mengelola sendiri| Kemasan | Gunakan kasing | Melepaskan | Pratinjau | Unduhan |
|---|---|---|---|---|
| Netsparkleupdater.sparkleupdater | Paket inti; Gunakan 100% UI khusus atau tidak ada UI (tidak ada yang bawaan) | |||
| WinForms UI (.NET Framework) | Netsparkle dengan winforms built-in UI | |||
| WinForms UI (.net 6+) | Netsparkle dengan winforms built-in UI | |||
| WPF UI (.NET Framework dan .net 6+) | Netsparkle dengan WPF UI bawaan | |||
| Avalonia UI | Netsparkle dengan Avalonia UI bawaan | |||
| Alat generator cast aplikasi | netsparkle-generate-appcast CLI Tool (termasuk ED25519 Helters) | |||
| Alat Pembantu DSA | netsparkle-dsa CLI Tool (DSA Helters) |
Info singkat untuk instalasi alat:
dotnet tool install --global NetSparkleUpdater.Tools.AppCastGenerator ; Tersedia sebagai netsparkle-generate-appcastdotnet tool install --global NetSparkleUpdater.Tools.DSAHelper ; Tersedia sebagai netsparkle-dsa di baris perintah Anda setelah instalasi Jalur pembaruan perangkat lunak yang khas untuk perangkat lunak stereotip mungkin terlihat seperti ini:
dotnet publish )Saat ini, Netsparkleupdater tidak membantu Anda dengan 1., 2., atau 4. "Mengapa tidak?", Anda mungkin bertanya:
sudo untuk alasan apa pun, ada contoh melakukan itu dalam sampel MacOS Avalonia .Untuk membuat file cast aplikasi Anda, lihat bagian Cast App dari dokumen ini.
Kami terbuka untuk kontribusi yang mungkin membuat proses instalasi/pembaruan secara keseluruhan lebih mudah bagi pengguna. Silakan ajukan masalah terlebih dahulu dengan ide Anda sebelum memulai pekerjaan sehingga kami dapat membicarakannya.
Silakan lihat contoh proyek di repositori ini untuk sampel penggunaan dasar dan dapat dijalankan !! Ada sampel untuk menggunakan masing-masing UI built-in serta sampel "lakukan sendiri di UI Anda sendiri"!
dotnet tool install --global NetSparkleUpdater.Tools.AppCastGeneratornetsparkle-generate-appcast --generate-keys
# By default, your Ed25519 signatures are stored on disk in your local
# application data folder in a subdirectory called `netsparkle`.
# If you want to export your keys to the console, you can do:
netsparkle-generate-appcast --exportMainWindow atau Formulir Utama Anda atau serupa: private SparkleUpdater _sparkle ;
// on your main thread...
_sparkle = new SparkleUpdater (
"https://mywebsite.com/appcast.xml" , // link to your app cast file - change extension to .json if using json
new Ed25519Checker ( SecurityMode . Strict , // security mode -- use .Unsafe to ignore all signature checking (NOT recommended!!)
"base_64_public_key_from_generate_app_cast_tool" ) // your base 64 public key
) {
UIFactory = new NetSparkleUpdater . UI . WPF . UIFactory ( icon ) , // or null, or choose some other UI factory, or build your own IUIFactory implementation!
RelaunchAfterUpdate = false , // set to true if needed
} ;
_sparkle . StartLoop ( true ) ; // will auto-check for updatesInnoSetup (Windows), file DMG (Linux), file .tar.gz (Linux), atau serupa. Informasi lebih lanjut di bagian Kerja Pembaruan.netsparkle-generate-appcast --help untuk opsi): netsparkle-generate-appcast -b binary/folder -p change/log/folder -u https://example.com/downloads -l https://example.com/downloads/changelogs.signature atau file serupa) ke lokasi yang sesuai di server AndaSparkleUpdater.LogWriter untuk melihat apakah ada informasi debug yang bermanfaat yang muncul di konsol! Dalam file proyek Anda, pastikan Anda mengatur beberapa hal sehingga perpustakaan dapat membaca dalam detail yang relevan nanti. Catatan: Anda dapat menggunakan IAssemblyAccessor Anda sendiri untuk memuat informasi versi dari tempat lain. Namun, menyiapkan semuanya dalam file proyek Anda mudah, dan Netsparkleupdater dapat membacanya secara asli!
< PropertyGroup >
< Version >1.0.2-beta1</ Version > <!-- accepts semver -->
< AssemblyVersion >1.0.2</ AssemblyVersion > <!-- only accepts Major.Minor.Patch.Revision -->
< AssemblyTitle >My Best App</ AssemblyTitle >
<!-- When using AssemblyDiagnosticsAccessor, accessor.AssemblyTitle is actually the
<Product> information due to limitations with the way the diagnostics access works -->
< Description >My app is cool (not required)</ Description >
< Company >My Company Name (required unless you set the IAssemblyAccessor save path yourself)</ Company >
< Product >My Product (required unless you set the IAssemblyAccessor save path yourself; set to product name e.g. MyBestApp)</ Product >
< Copyright >2024 MyCompanyName</ Copyright >
</ PropertyGroup > Catatan Penting: Dalam .NET 8+, perubahan dilakukan pada inti .NET yang menyebabkan kode git/sumber Anda melakukan hash untuk dimasukkan dalam nomor <Version> aplikasi Anda. Perilaku ini tidak dapat dihindari oleh NetSparkleupdater pada saat ini karena kami mengandalkan AssemblyInformationalVersionAttribute , dan perilaku atribut ini diubah. Pengguna Anda mungkin diberitahu bahwa mereka saat ini menjalankan 1.0.0+commitHashHere oleh Netsparkleupdater (dan aplikasi asli Anda sendiri!). Kami juga merekomendasikan untuk menambahkan baris berikut ke file proyek Anda (dalam <PropertyGroup> baru atau yang sudah ada):
< IncludeSourceRevisionInInformationalVersion >false</ IncludeSourceRevisionInInformationalVersion > // NOTE: Under most, if not all, circumstances, SparkleUpdater should be initialized on your app's main UI thread.
// This way, if you're using a built-in UI with no custom adjustments, all calls to UI objects will automatically go to the UI thread for you.
// Basically, SparkleUpdater's background loop will make calls to the thread that the SparkleUpdater was created on via SyncronizationContext.
// So, if you start SparkleUpdater on the UI thread, the background loop events will auto-call to the UI thread for you.
_sparkle = new SparkleUpdater (
"http://example.com/appcast.xml" , // link to your app cast file
new Ed25519Checker ( SecurityMode . Strict , // security mode -- use .Unsafe to ignore all signature checking (NOT recommended!!)
"base_64_public_key" ) // your base 64 public key -- generate this with the NetSparkleUpdater.Tools.AppCastGenerator .NET CLI tool on any OS
) {
UIFactory = new NetSparkleUpdater . UI . WPF . UIFactory ( icon ) , // or null, or choose some other UI factory, or build your own IUIFactory implementation!
RelaunchAfterUpdate = false , // default is false; set to true if you want your app to restart after updating (keep as false if your installer will start your app for you)
CustomInstallerArguments = "" , // set if you want your installer to get some command-line args
} ;
_sparkle . StartLoop ( true ) ; // `true` to run an initial check online -- only call StartLoop **once** for a given SparkleUpdater instance!Pada acara Application.Idle pertama, file aplikasi XML Anda akan diunduh, dibaca, dan dibandingkan dengan versi yang sedang berjalan. Jika memiliki pembaruan perangkat lunak di dalam, pengguna akan diberitahu dengan sedikit pemberitahuan bersulang (jika didukung oleh UI dan diaktifkan) atau dengan dialog pembaruan yang berisi catatan rilis Anda. Pengguna kemudian dapat mengabaikan pembaruan, meminta untuk diingatkan nanti, atau mengunduh/menginstalnya sekarang.
Jika Anda ingin memeriksa pembaruan di latar belakang tanpa pengguna melihat apa pun, gunakan
var updateInfo = _sparkle . CheckForUpdatesQuietly ( ) ;Jika Anda ingin memiliki item menu untuk pengguna untuk memeriksa pembaruan sehingga pengguna dapat melihat UI sementara Netsparkle mencari pembaruan, gunakan
_sparkle . CheckForUpdatesAtUserRequest ( ) ;Jika Anda memiliki file yang perlu disimpan, berlangganan acara persiapan yang dipersiapkan:
_sparkle . PreparingToExit += ( ( x , cancellable ) =>
{
// ask the user to save, whatever else is needed to close down gracefully
} ) ; Perhatikan bahwa jika Anda tidak menggunakan UIFactory , Anda harus menggunakan CloseApplication atau CloseApplicationAsync untuk menutup aplikasi Anda; Kalau tidak, file pembaruan Anda yang diunduh tidak akan pernah dieksekusi/dibaca! Satu -satunya pengecualian untuk ini adalah jika Anda ingin menangani semua aspek menginstal paket pembaruan sendiri.
File yang meluncurkan pembaruan yang Anda unduh hanya dapat menunggu selama 90 detik sebelum menyerah! Pastikan perangkat lunak Anda ditutup dalam waktu 90 detik setelah aplikasi closeApplication/closeApplicationAnnc dipanggil jika Anda menerapkan acara tersebut! Jika Anda memerlukan acara yang dapat dibatalkan, seperti ketika pengguna perlu ditanya apakah boleh ditutup (misalnya untuk menyimpan pekerjaan mereka), gunakan PreparingForExit atau PreparingToExitAsync .
IUIFactory ; Atur SparkleUpdater.UIFactory untuk memanfaatkan instance objek Anda.ICheckingForUpdates untuk UI Anda yang memberi tahu pengguna bahwa SparkleUpdater sedang memeriksa pembaruanIDownloadProgress untuk UI Anda yang menunjukkan kepada pengguna bahwa pembaruan sedang diunduhIUpdateAvailable untuk UI Anda yang menunjukkan kepada pengguna bahwa pembaruan tersedia bersama dengan catatan rilisIAppCastDataDownloader untuk mengatur metode Anda sendiri untuk mengunduh data cast aplikasi; Setel SparkleUpdater.AppCastDataDownloader untuk memanfaatkan instance objek Anda .. Netsparkle mencakup dua implementasi secara LocalFileAppCastDownloader : WebRequestAppCastDataDownloader untuk mengunduh informasi cast aplikasi dari Internet pada umumIAppCastFilter untuk melakukan penyaringan khusus pada objek AppCastItem di cast aplikasi yang diunduh, misalnya hanya mempertimbangkan subset item yang diberikan sebagai pembaruan yang valid untuk aplikasi Anda; Setel AppCastHelper.AppCastFilter ( SparkleUpdater.AppCastHelper.AppCastFilter ) untuk memanfaatkan instance objek Anda. NetSparkle mencakup kelas ChannelAppCastFilter , yang dapat Anda gunakan untuk menyaring item dengan saluran produk yang diberikan (misalnya alpha, beta) jika aplikasi Anda menggunakan fitur -fitur tersebut.IAppCastGenerator untuk mengontrol bagaimana gips aplikasi diserialisasi dan deserialized; Atur SparkleUpdater.AppCastGenerator untuk memanfaatkan instance objek Anda. NetSparkle mencakup dua implementasi: XMLAppCastGenerator , untuk serialisasi/deserialisasi XML; dan JsonAppCastGenerator , untuk serialisasi/deserialisasi JSON. Alat CLI Generator Cast APP juga dapat mengeluarkan cetakan aplikasi XML dan JSON.IAssemblyAccessor untuk mengontrol bagaimana versi, hak cipta, dan detail produk lainnya dimuat untuk aplikasi Anda; Atur Configuration.AssemblyAccessor ( SparkleUpdater.Configuration.AssemblyAccessor ) untuk memanfaatkan instance objek Anda. Netsparkle berisi implementasi default, AssemblyDiagnosticsAccessor , yang seharusnya bekerja dalam kasus umum memuat data dari perakitan yang diberikan.ILogger dan mengatur SparkleUpdater.LogWriter . Secara default, kelas LogWriter digunakan (yang memiliki properti LogWriterOutputMode untuk mengontrol apakah log ditulis untuk Console , Trace , dll.)ISignatureVerifier untuk mengubah bagaimana tanda tangan Anda untuk pemeran aplikasi, unduhan, dll. Ditangani; Atur SparkleUpdater.SignatureVerifier untuk memanfaatkan instance objek Anda.IUpdateDownloader untuk mengatur metode Anda sendiri untuk mengunduh dan mengirimkan kemajuan pada file pembaruan aplikasi (misalnya penginstal) untuk item cast aplikasi; Atur SparkleUpdater.UpdateDownloader untuk memanfaatkan instance objek Anda .. Netsparkle mencakup dua implementasi secara default: WebFileDownloader (default) untuk mengunduh file dari web/internet, dan LocalFileDownloader untuk menyalin/"mengunduh" file dari jalur yang diberikan. Configuration subkelas untuk mengubah bagaimana informasi NetSparkle tertentu disimpan dan dimuat - misalnya, informasi versi yang dilewati. Kelas ini adalah yang menggunakan instance IAssemblyAccessor untuk menyimpan dan memuat informasi versi, nama produk, dll. Netsparkle berisi tiga implementasi: RegistryConfiguration , yang menyimpan dan memuat info ke Windows Registry (default pada Windows); JSONConfiguration , yang menyimpan dan memuat info ke file JSON (default pada macOS/linux); dan DefaultConfiguration , yang tidak melakukan apa pun dan berfungsi sebagai fallback jika JSONConfiguration tidak dapat menemukan lokasi file yang valid untuk menyimpan dan memuat data. Untuk menggunakan contoh kelas Anda, atur SparkleUpdater.Configuration .RegistryConfiguration Subklassing memungkinkan Anda dengan cepat mengubah jalur registri di mana item disimpan melalui BuildRegistryPathJSONConfiguration memungkinkan Anda dengan cepat mengubah jalur file di mana data disimpan melalui GetSavePathAppCastHelper Jika Anda ingin kontrol penuh atas proses pengunduhan dan penguraian aplikasi. Perhatikan bahwa Anda mungkin dapat melakukan semua yang perlu Anda lakukan melalui Properti AppCastHelper (termasuk IAppCastFilter AppCastFilter ), tetapi subklassing akan memberi Anda kontrol penuh dan mutlak atas seluruh proses. Untuk menggunakan contoh kelas Anda, atur SparkleUpdater.AppCastHelper .ReleaseNotesGrabber untuk mengontrol proses rilis yang mengunduh (dan karenanya tampilan) proses. Untuk menggunakan instance dari kelas Anda, atur UIFactory.ReleaseNotesGrabberOverride .WebFileDownloader Jika Anda tidak ingin mengimplementasikan IUpdateDownloader sendiri dan hanya ingin mengganti satu atau dua fungsi seperti CreateHttpClient atau RetreiveDestinationFileNameAsync . Untuk menggunakan instance dari kelas Anda, atur SparkleUpdater.UpdateDownloader .WebRequestAppCastDataDownloader Jika Anda tidak ingin mengimplementasikan IAppCastDataDownloader dan hanya ingin mengganti satu atau dua fungsi seperti CreateHttpClient . Untuk menggunakan instance dari kelas Anda, atur SparkleUpdater.AppCastDataDownloader .LogWriter untuk mengimplementasikan fungsi PrintMessage ; Karena ILogger adalah antarmuka yang cukup sederhana, Anda mungkin dapat menerapkan antarmuka itu sendiri jika kebutuhan Anda rumit. Untuk menggunakan instance dari kelas Anda, atur SparkleUpdater.LogWriter .SparkleUpdater untuk mengimplementasikan beberapa fungsi terkait instalasi yang berbeda, termasuk:GetWindowsInstallerCommandGetInstallerCommandRunDownloadedInstallerGetDownloadPathForAppCastItemUIFactory jika Anda tidak ingin menerapkan keseluruhan antarmuka IUIFactory sendiri dan hanya ingin mengkonfigurasi satu atau dua fungsi. Untuk menggunakan instance dari kelas Anda, atur SparkleUpdater.UIFactory . IAppCastFilter Anda dapat mengubah cara item cast aplikasi Anda difilter melalui properti AppCastHelper.AppCastFilter (melalui antarmuka IAppCastFilter ). Ini memungkinkan Anda untuk mengubah item apa yang tersedia untuk pengguna akhir Anda.
Netsparkle berisi implementasi IAppCastFilter bawaan untuk pemfilteran berbasis saluran yang disebut ChannelAppCastFilter . Untuk beberapa contoh tentang cara menggunakan kelas itu, lihat tes unit di sini. Pada dasarnya, atur Properti List<string> ChannelSearchNames ke saluran yang ingin Anda filter. Jika Anda ingin KeepItemsWithNoChannelInfo item tanpa info saluran ( 1.2.3 true
Untuk benar-benar mengatur saluran pada item cast aplikasi Anda / di cast aplikasi Anda, gunakan properti --channel dari alat CLI Cast App, atau atur properti <Version> dari file proyek Anda ke versi yang berlaku SEMVER-Compatible (misalnya <Version>1.0.2-beta1</Version> ), dan App Cast Tool CLI akan mengambil ini secara otomatis. Atau, jika Anda membangun cast aplikasi Anda secara manual, atur properti <sparkle:channel>YourChannelHere</sparkle:channel> di <item> Anda (atau, jika menggunakan json, properti channel ).
Netsparkleupdater tidak harus digunakan dengan UI sama sekali. Anda dapat melakukan semuanya sendiri atau bahkan meminta Perpustakaan menjalankan pembaruan yang diunduh secara otomatis dengan mengatur SparkleUpdater.UserInteractionMode = UserInteractionMode.DownloadAndInstall daninstall. Repo ini memiliki sampel untuk melakukan sesuatu sendiri tanpa ada UI yang sudah dibangun di SRC/NetSparkle.samples.handleeventsyour sendiri.
Jika Anda menginginkan UI, kami menawarkan UI pra-built dalam paket Nuget yang berbeda dengan sejumlah kecil opsi yang dapat disesuaikan untuk WinForms, WPF, dan Avalonia. UI dipicu melalui implementasi IUIFactory , yang disebut UIFactory di masing-masing opsi bawaan. Sebagian besar metode dalam UIFactory dapat diganti jika Anda ingin mengubah perilaku, dan ProcessWindowAfterInit memungkinkan Anda menyesuaikan setiap jendela setelah dibuat.
Jika Anda ingin menggulung UI Anda sendiri sepenuhnya, cukup terapkan antarmuka IUIFactory dengan perpustakaan UI apa pun yang ingin Anda gunakan. Anda dapat menyalin atau menggunakan kembali model, kode, dll. Dari opsi prebuilt Netsparkleupdater, dan menyalin+kode pasting dari repo ini ke Anda sendiri mungkin merupakan cara yang baik dan cepat untuk memulai. Jangan lupa untuk mengatur properti SparkleUpdater.UIFactory dengan contoh implementasi IUIFactory Anda!
Harap dicatat: Netsparkle pada dasarnya tidak melakukan upaya untuk khawatir tentang threading (misalnya panggilan ke utas utama) kecuali untuk latar belakang panggilan ke utas utama yang memulai instance SparkleUpdater . Dengan kata lain, secara umum, Netsparkle akan melakukan segalanya di utas yang awalnya menciptakan instance SparkleUpdater . Untuk sebagian besar aplikasi, ini akan baik -baik saja karena mereka hanya menggunakan utas UI utama mereka. Jika ragu, untuk kebutuhan UI Anda sendiri, pastikan untuk memeriksa InvokeRequired pada WinForms, dan pada WPF/Avalonia, hal -hal marshal ke utas UI (kecuali jika Anda menggunakan pengikatan data dalam hal ini ditangani untuk Anda!).
Melewati implementasi IUIFactory Anda sendiri yang memulai Windows/Hal -hal di utas baru ke SparkleUpdater bukanlah konfigurasi yang didukung. Jika Anda ingin menjalankan UI Anda sendiri di beberapa utas (misalnya WinForms untuk tidak memiliki jendela Netsparkleupdater tutup ketika formulir utama ditutup), lakukanlah menggunakan acara SparkleUpdater dan bukan UIFactory ; Silakan juga lihat sampel SRC/NetSparkle.samples.Forms.multithread untuk contoh praktis tentang bagaimana melakukan ini.
Pemeran aplikasi hanyalah file XML atau JSON. Ini berisi bidang -bidang seperti judul dan deskripsi produk Anda serta definisi per rilis perangkat lunak Anda.
Kami sangat menyarankan Anda memanfaatkan alat Netsparkle-Generate-Appcast untuk membuat (dan kemudian, menciptakan kembali/memperbarui) file tersebut karena dapat membantu mengurus semua persyaratan penandatanganan untuk Anda.
dotnet tool install --global NetSparkleUpdater.Tools.AppCastGeneratornetsparkle-generate-appcast . Anda dapat menggunakan netsparkle-generate-appcast --help untuk melihat daftar lengkap opsi untuk alat ini. Secara default, Netsparkle menggunakan gips aplikasi XML yang kompatibel dengan kilauan untuk sebagian besar . Netsparkle menggunakan sparkle:signature Than sparkle:edSignature sehingga Anda dapat memilih cara menandatangani file/aplikasi aplikasi Anda. sparkle:edSignature --use-ed25519-signature-attribute ISignatureVerifier
Berikut adalah contoh aplikasi XML App:
<? xml version = " 1.0 " encoding = " UTF-8 " ?>
< rss xmlns : dc = " http://purl.org/dc/elements/1.1/ " xmlns : sparkle = " http://www.andymatuschak.org/xml-namespaces/sparkle " version = " 2.0 " >
< channel >
< title >NetSparkle Test App</ title >
< link >https://netsparkleupdater.github.io/NetSparkle/files/sample-app/appcast.xml</ link >
< description >Most recent changes with links to updates.</ description >
< language >en</ language >
< item >
< title >Version 2.0 (2 bugs fixed; 3 new features)</ title >
< sparkle : releaseNotesLink >
https://netsparkleupdater.github.io/NetSparkle/files/sample-app/2.0-release-notes.md
</ sparkle : releaseNotesLink >
< pubDate >Thu, 27 Oct 2016 10:30:00 +0000</ pubDate >
< enclosure url = " https://netsparkleupdater.github.io/NetSparkle/files/sample-app/NetSparkleUpdate.exe "
sparkle : version = " 2.0 "
sparkle : os = " windows "
length = " 12288 "
type = " application/octet-stream "
sparkle : signature = " NSG/eKz9BaTJrRDvKSwYEaOumYpPMtMYRq+vjsNlHqRGku/Ual3EoQ== " />
</ item >
</ channel >
</ rss > Netsparkle membaca tag <item> untuk menentukan apakah pembaruan tersedia.
Tag penting di setiap <item> adalah:
<description><sparkle:releaseNotesLink> .<sparkle:releaseNotesLink><description> , itu akan digunakan sebagai gantinya.sparkle:signature , Opsional: DSA/ED25519 tanda tangan dokumen; Netsparkle tidak memeriksa tanda tangan ini untuk Anda kecuali Anda mengatur ReleaseNotesGrabber.ChecksReleaseNotesSignature ke true , tetapi Anda dapat secara manual memverifikasi tanda tangan Changelog jika Anda suka atau mengatur ReleaseNotesGrabber.ChecksReleaseNotesSignature = true di UI Anda.<pubDate>sparkle:channel : Saluran untuk Item Cast Aplikasi ini, misalnya beta (tidak diperlukan) - hanya menerima 1 saluran<enclosure>url : URL dari file pembaruansparkle:version : Nomor versi yang dapat dibaca mesin dari pembaruan inilength , opsional: (tidak divalidasi) Ukuran file pembaruan dalam bytetype : Diabaikansparkle:signature : DSA/ED25519 Tanda Tangan dari File Pembaruansparkle:criticalUpdate , Opsional: Jika sama dengan true atau 1 , UI akan menunjukkan bahwa ini adalah pembaruan kritissparkle:os : Sistem operasi untuk item cast aplikasi. Default ke windows jika tidak disediakan. Untuk Windows, gunakan "Win" atau "Windows"; Untuk MacOS, gunakan "MacOS" atau "OSX"; Untuk Linux, gunakan "Linux". Secara default, Anda memerlukan 2 tanda tangan ( SecurityMode.Strict ):
sparkle:signature="..." )Catatan: Alat Generator Cast App membuat kedua tanda tangan ini untuk Anda saat menciptakan file Appcast.xml.
Anda dapat menghasilkan tanda tangan ED25519 menggunakan alat AppCastGenerator (dari paket Nuget ini atau dalam kode sumber di sini). Alat ini membutuhkan runtime desktop .NET 6, 7, 8, atau 9 untuk diinstal. Silakan lihat bagian di bawah ini untuk opsi dan contoh tentang menghasilkan kunci ED25519 dan untuk menggunakannya saat membuat aplikasi.
AppCastGenerator (dari paket Nuget ini atau di kode sumber di sini) untuk dengan mudah membuat file cast aplikasi Anda. Opsi yang tersedia dijelaskan di bawah ini. Anda dapat menginstalnya di CLI Anda melalui dotnet tool install --global NetSparkleUpdater.Tools.AppCastGenerator .string.Format atau yang serupa adalah hal yang luar biasa).Jika Anda ingin menggunakan pemeran aplikasi JSON daripada XML:
--output-type json saat menghasilkan file cast aplikasi Anda melalui generator cast aplikasiSparkleUpdater.AppCastGenerator ke new JsonAppCastGenerator(mySparkleUpdater.LogWriter) .JsonAppCastGenerator.HumanReadableOutput ke false .Melewatkan beberapa opsi yang ingin Anda lihat? Ajukan masalah pada repo ini atau tambahkan sendiri dan kirimkan permintaan tarik kepada kami!
--show-examples : Cetak contoh penggunaan ke konsol.--help : Tampilkan semua opsi dan deskripsinya. -a / --appcast-output-directory : direktori untuk menulis file output appcast.xml . Contoh Gunakan: -a ./MyAppCastOutput-e / --ext : Saat mencari file untuk ditambahkan ke cast aplikasi, gunakan ekstensi yang diberikan saat mencari file. Default ke exe . Contoh Gunakan: -e exe,msi-b / --binaries : Jalur file ke direktori yang harus dicari saat mencari file untuk ditambahkan ke cast aplikasi. Default ke . . Contoh Penggunaan: -b my/build/directory-r / --search-binary-subdirectories : benar untuk mencari direktori biner secara rekursif untuk binari; Salah hanya mencari direktori teratas. Default ke false . Contoh Gunakan: -r .--single-file : File tunggal untuk ditambahkan ke cast aplikasi-jika diatur, --binaries , --ext , dll. Semuanya diabaikan. Bermanfaat untuk digunakan jika file output Anda tidak memiliki ekstensi (misalnya adalah UNIX yang dapat dieksekusi). Contoh Gunakan: --single-file path/to/my/file-f / --file-extract-version : Apakah untuk mengekstrak versi file atau tidak dari nama file daripada file (mis. Dll) itu sendiri. Default ke false . Gunakan ketika file Anda yang akan diunduh oleh NetSparkleupdater akan memiliki nomor versi dalam nama file, misalnya "Aplikasi saya 1.3.2-alpha1.exe". Perhatikan bahwa ini hanya mencari empat item/folder direktori terakhir. Contoh Penggunaan: -f true--file-version : Gunakan untuk mengatur versi untuk biner yang masuk ke pemeran aplikasi. Perhatikan bahwa versi ini hanya dapat diatur sekali, jadi saat menghasilkan pemeran aplikasi, pastikan Anda juga: a) hanya memiliki satu biner dalam pemeran aplikasi Anda | B) Memanfaatkan parameter --reparse-existing sehingga item lama diambil. Jika generator menemukan 2 binari tanpa versi yang diketahui dan --file-version diatur, maka kesalahan akan dipancarkan. Contoh Penggunaan: --file-version 1.3.2-o / --os : Sistem operasi yang dimiliki oleh item cast aplikasi. String harus menyertakan salah satu dari yang berikut: windows , mac , linux . Default ke windows . Contoh Penggunaan: -o macos-arm64 ; -o windows-x64--description-tag : Teks untuk dimasukkan ke dalam aplikasi deskripsi cast/informasi. Default ke "perubahan terbaru dengan tautan ke pembaruan". Contoh Penggunaan: --description-tag "Hello I am a Cool App"--link-tag : Teks untuk dimasukkan ke dalam tag/informasi link cast aplikasi. Harus menjadi url unduhan cast aplikasi Anda jika Anda menggunakan ini. Contoh Gunakan: --link-tag https://mysite.com/coolapp/appcast.xml-u / --base-url : Bagian awal dari URL yang akan digunakan untuk diunduh. Nama file yang akan diunduh akan diletakkan setelah porsi URL ini. Contoh Gunakan: -u https://myawesomecompany.com/downloads-l / --change-log-url : Bagian awal URL yang akan digunakan untuk file log perubahan Anda. File log perubahan yang akan diunduh akan diletakkan setelah bagian URL ini. Jika opsi ini tidak ditentukan, maka Data Log Ubah akan dimasukkan ke dalam aplikasi yang dilemparkan sendiri. Contoh Gunakan: -l https://myawesomecompany.com/changes-p / --change-log-path : jalur ke file log ubah untuk perangkat lunak Anda. Ini diharapkan berada dalam format penurunan harga dengan perpanjangan .md . Nama file dari file log perubahan harus berisi versi perangkat lunak, misalnya 1.3.2.md Contoh Gunakan: -p path/to/change/logs . (Catatan: Generator juga akan mencoba menemukan log perubahan yang nama file yang diformat seperti itu: MyApp 1.3.2.md )--change-log-name-prefix : awalan untuk perubahan nama file log. Secara default, generator mencari nama file dengan format "[versi] .md". Jika Anda mengatur parameter ini ke (misalnya) "Log Ubah Aplikasi Saya", itu akan mencari nama file dengan format "aplikasi saya mengubah log [versi] .md" serta "[versi] .md".-n / --product-name : Nama produk untuk perangkat lunak Anda. Digunakan saat mengatur judul untuk pemeran aplikasi Anda dan item -itemnya. Default ke Application . Contoh Gunakan: -n "My Awesome App"-x / --url-prefix-version : Tambahkan nomor versi sebagai awalan nama file untuk URL unduhan. Default ke false. Misalnya, jika --base-url adalah www.example.com/downloads , versi Anda adalah 1.4.2 , dan nama aplikasi Anda adalah MyApp.exe , URL unduhan Anda akan menjadi www.example.com/downloads/1.4.2/MyApp.exe . Contoh Gunakan: -x true .--key-path : Path to NetSparkle_Ed25519.priv dan NetSparkle_Ed25519.pub file, yang masing-masing adalah kunci ed25519 pribadi dan publik Anda untuk pembaruan perangkat lunak Anda. Contoh Penggunaan: --key-path my/path/to/keysSPARKLE_PRIVATE_KEY dan SPARKLE_PUBLIC_KEY sebelum menjalankan generate_appcast . Alat ini memprioritaskan kunci lingkungan daripada kunci yang duduk di disk!--signature-file-extension : Extension (tanpa . ) Untuk digunakan untuk file tanda tangan cast aplikasi. Default ke signature . Contoh Gunakan: --signature-file-extension txt .--output-file-name : nama file output untuk cast aplikasi dengan . atau ekstensi. Ekstensi dikendalikan oleh apakah itu output XML atau JSON dan tidak dapat dikonfigurasi. Default ke 'appcast'. Tentu saja, Anda selalu dapat mengubah ini nanti setelah pemeran aplikasi dihasilkan; Opsi ini hanya untuk kenyamanan. Contoh Gunakan: --output-file-name super_app_download_info .--use-ed25519-signature-attribute : Jika benar dan melakukan output XML, atribut tanda tangan output dalam XML akan menjadi edSignature daripada signature untuk mencocokkan perpustakaan Sparkle asli. Tidak ada efek pada gips aplikasi JSON.--file-version : Gunakan untuk mengatur versi untuk biner yang masuk ke pemeran aplikasi. Perhatikan bahwa versi ini hanya dapat diatur sekali, jadi saat menghasilkan pemeran aplikasi, pastikan Anda juga: a) hanya memiliki satu biner dalam pemeran aplikasi Anda | B) Memanfaatkan parameter --reparse-existing sehingga item lama diambil. Jika generator menemukan 2 binari tanpa versi yang diketahui dan --file-version diatur, maka kesalahan akan dipancarkan.--critical-versions : Daftar versi yang dipisahkan koma untuk menandai sebagai kritis dalam pemeran aplikasi. Harus mencocokkan teks versi dengan tepat. Misalnya, "1.0.2.1.2.3.1".--reparse-existing : Parse ulang aplikasi yang ada daripada mengesampingkannya dan membuatnya lagi. Lewati versi yang sudah ada di pemeran aplikasi, jadi jika Anda menggunakan biner baru dengan versi yang sama, Anda perlu mengedit secara manual cast aplikasi Anda untuk menghapus daftar lama untuk versi yang Anda gunakan kembali. Contoh Penggunaan: --reparse-existing true--overwrite-old-items : Penyebab Item Cast App ditulis ulang di Aplikasi Cast jika Binary On Disk dengan nomor versi yang sama ditemukan. Dengan kata lain, jika 1.0.1 sudah ada di aplikasi yang sudah ada (baik dari reparsing atau dari biner lain), dan 1.0.1 lainnya ditemukan pada disk, maka data 1.0.1 dalam pemeran aplikasi akan ditulis ulang berdasarkan biner yang ditemukan. Perhatikan bahwa ini berarti bahwa jika Anda memiliki beberapa versi 1.0.1 pada disk (yang tidak boleh Anda lakukan ...), yang terakhir ditemukan akan menjadi yang ada di pemeran aplikasi Anda! Contoh Penggunaan: --overwrite-old-items--human-readable : Jika benar, membuat aplikasi output file cast yang dapat dibaca manusia (newslines, indents). Contoh Penggunaan: --human-readable true--channel : Nama saluran rilis untuk item apa pun yang ditambahkan ke cast aplikasi. Should be a single channel; does not support multiple channels at once, eg beta,gamma . Do not set if you want to use your release channel - if you set this to release or stable , those names/words will be treated as special channels and not as the stable channel. (Unless you want all your items to be in a specific channel, of course.) Example use: --channel beta--output-type : Output type for the app cast file ( xml or json ). Defaults to xml . Example use: --output-type json --public-key-override : Public key override (ignores whatever is in the public key file) for signing binaries. This overrides ALL other public keys set when verifying binaries, INCLUDING public key set via environment variables! If not set, uses --key-path (if set) or the default SignatureManager location. Not used in --generate-keys or --export . Example use: --public-key-override asoj341ljsdflj--private-key-override : Private key override (ignores whatever is in the private key file) for signing binaries. This overrides ALL other public keys set when verifying binaries, INCLUDING private key set via environment variables! If not set, uses --key-path (if set) or the default SignatureManager location. Not used in --generate-keys or --export . Example use: --private-key-override asoj341ljsdflj --generate-keys : If set, will attempt to generate NEW Ed25519 keys for you. Can be used in conjunction with --key-path . Once keys are successfully (or unsuccessfully) generated, the program ends without generating an app cast. By default, existing keys are not overwritten. This option defaults to false .--force : If set to true , will overwrite existing keys on disk. WARNING: THIS COULD RESULT IN A LOSS OF YOUR PUBLIC AND PRIVATE KEYS. USE WITH CAUTION. DO NOT USE IF YOU DO NOT KNOW WHAT YOU ARE DOING! THIS WILL MAKE NO ATTEMPT TO BACK UP YOUR DATA. This option defaults to false . Example use: --generate-keys --force true .--export : Export keys as base 64 strings to the console. Defaults to false . Example use: --export true . Output format: Private Key:
2o34usledjfs0
Public Key:
sdljflase;ru2u3
--generate-signature : Generate a signature for a file and output it to the console. Example use: --generate-signature path/to/app/MyApp.exe . Outputs in format: Signature: seljr13412zpdfj . Note that these options are only for verifying Ed25519 signatures. For DSA signatures, please use the DSAHelper tool. Both of the following options must be used together. You must have keys already generated in order to verify file signatures.
--verify : Path to the file that has a signature you want to verify.--signature : Base 64 signature of the file. Example use: --verify my/path/MyApp.exe --signature 123l4ijsdfzderu23 .
This will return either Signature valid (signature is good!) or Signature invalid (signature does not match file).
# ### Key Generation
# Generate Ed25519 keys for the first time
netsparkle-generate-appcast --generate-keys
# Store keys in a custom location
netsparkle-generate-appcast --key-path path/to/store/keys
# Pass in public key via command line
netsparkle-generate-appcast --public-key-override [YourPublicKeyHere]
# Pass in private key via command line
netsparkle-generate-appcast --private-key-override [YourPrivateKeyHere]
# By default, your Ed25519 signatures are stored on disk in your local
# application data folder in a subdirectory called `netsparkle`.
# If you want to export your keys to the console, you can do:
netsparkle-generate-appcast --export
# You can also store your keys in the following environment variables:
# set public key: SPARKLE_PUBLIC_KEY
# set private key: SPARKLE_PRIVATE_KEY
# ### Generate a signature for a binary without creating an app cast:
netsparkle-generate-appcast --generate-signature path/to/binary.exe
# ### Verifying Binaries
netsparkle-generate-appcast --verify path/to/binary.exe --signature base_64_signature
# ### Using a custom key location:
# If your keys are sitting on disk somewhere
# (`NetSparkle_Ed25519.priv` and `NetSparkle_Ed25519.pub` -- both
# in base 64 and both on disk in the same folder!), you can pass in
# the path to these keys like this:
netsparkle-generate-appcast --key-path path/to/keys/
# ### Generating an app cast
# Generate an app cast for Windows executables that are sitting in a
# specific directory
netsparkle-generate-appcast -a directory/for/appcast/output/ -e exe -b directory/with/binaries/ -o windows
# Add change log info to your app cast
netsparkle-generate-appcast -b binary/folder -p change/log/folder
# Customize download URL for binaries and change logs
netsparkle-generate-appcast -b binary/folder -p change/log/folder -u https://example.com/downloads -l https://example.com/downloads/changelogs
# Set your application name for the app cast
netsparkle-generate-appcast -n " My Awesome App " -b binary/folder
# Use file versions in file names, e.g. for apps like "My App 1.2.1.dmg"
netsparkle-generate-appcast -n " macOS version " -o macos -f true -b binary_folder -e dmg
# Don't overwrite the entire app cast file
netsparkle-generate-appcast --reparse-existing
# Don't overwrite the entire app cast file, but do overwrite items that are still on disk
netsparkle-generate-appcast --reparse-existing --overwrite-old-itemsPlease see the UPGRADING.md file for information on breaking changes and fixes between major versions.
Tidak. You can just reference the core library and handle everything yourself, including any custom UI. Check out the code samples for an example of doing that!
This isn't a built-in feature, as NetSparkleUpdater assumes that it can safely make calls/events to the UI on the thread that started the SparkleUpdater instance. However, if you'd like to do this, we have a sample on how to do this: NetSparkle.Samples.Forms.Multithread . Basically, instead of passing in a UIFactory to SparkleUpdater , you handle SparkleUpdater 's events yourself and show the UI however you want to show it - and yes, you can still use the built-in UI objects for this!
(Note that on Avalonia, the answer is always "No" since they only support one UI thread at this time.)
Ya. You need to start the NetSparkleUpdater forms on a new thread(s). See the NetSparkle.Samples.Forms.Multithread sample for how to do this by handling events yourself and still using the built-in WinForms UIFactory .
See #238 and this documentation for the fix for making this work on the sample application. Basically, you need to use an app config file and manifest file to let Windows know that your application is DPI-aware. If that doesn't work for you, try some of the tips at this SO post.
Ya!
--os command line parameter.macos-arm64 or windows-x64 rather than just macos or windows Trimming is a great way to reduce the file size of your application when it is self-published and/or built as a self-contained application. In short, trimming removes unused code from your applications, including external libraries, so you can ship your application with a reduced file size. To trim your application on publish, add <PublishTrimmed>true</PublishTrimmed> to your csproj file. If you want to trim all assemblies (including those that may not have specified they are compatible with trimming), add <TrimMode>full</TrimMode> to your csproj file; to only trim those that have opted-in, use <TrimMode>partial</TrimMode> . To enable warnings for trimming, add <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings> .
There are other options to use, which you can learn more about on Microsoft's documentation here. For those applications that may not work with the built-in trimming options, please try Zack.DotNetTrimmer or other solutions you may find.
We recommend that you trim your application before publishing it and distributing it to your users. Some of NetSparkle's default dependencies are rather large, but the file size can be drastically reduced by the trim process. If you choose to trim your application, don't forget to test it after trimming and make sure you fix any warnings that come up!
You can also read more about trimming libraries here.
Ya.
Ya.
Ya. In the app cast generator, you can do things like, -u ../ to make NetSparkle check the directory above the server's appcast.xml file for download files.
NetSparkleUpdater.SparkleUpdater is the right package if you want the library with no built-in UI. Otherwise, use NetSparkleUpdater.UI.{YourChoiceOfUI} , which will give you a built-in UI and the core library. Previous to 2.0, the UI libraries reference NetSparkle.New , which is now deprecated.
Here is the full list of deprecated packages:
com.pikleproductions.netsparkle -- replaced by NetSparkleUpdater.SparkleUpdatercom.pikleproductions.netsparkle.tools -- replaced by NetSparkleUpdater.Tools.AppCastGenerator and NetSparkleUpdater.Tools.DSAHelperNetSparkle.New -- replaced by NetSparkleUpdater.SparkleUpdaterNetSparkle.New.Tools -- replaced by NetSparkleUpdater.Tools.AppCastGenerator and NetSparkleUpdater.Tools.DSAHelperNetSparkleUpdater.Tools -- replaced by NetSparkleUpdater.Tools.AppCastGenerator and NetSparkleUpdater.Tools.DSAHelperNo. If your app is just using NetSparkle to work out if there is a later release - and you are not using the app cast as a way to refer to historical versions of your app in any way - then you don't need to add all the released versions into the app cast file.
Having just the latest version of your software in the app cast has the added side effect that you won't need all the binaries & changelogs of all the versions to be available to the app cast generator tool. For example, this might make an automated release build easier via GitHub Actions - because the only data required is the generated .exe and changelogs from your git repository.
SecurityMode.Unsafe or the following IAppCastHandler override: public override bool DownloadAndParse ( )
{
try
{
_logWriter . PrintMessage ( "Downloading app cast data..." ) ;
var appCast = _dataDownloader . DownloadAndGetAppCastData ( _castUrl ) ;
if ( ! string . IsNullOrWhiteSpace ( appCast ) )
{
Items . Clear ( ) ;
Items . AddRange ( ParseAppCast ( appcast ) ) ;
return true ;
}
}
catch ( Exception e )
{
_logWriter . PrintMessage ( "Error reading app cast {0}: {1} " , _castUrl , e . Message ) ;
}
return false ;
}The answer is both yes and no. No, because that is not the default behavior. Yes, because if you use installers for each of your versions, you can use your app cast to see which previous versions are available and download those versions. If your installers are standalone, they should install an old version just fine. Just keep in mind that if you install an old version and then there is a newer version in your app cast, after opening the older software, it will ask them if they want to update to the newer version!
Here's a summary of what you can do:
SparkleUpdater object_updateInfo = await _sparkle.CheckForUpdatesQuietly(); (no UI shown) or _sparkle.CheckForUpdatesAtUserRequest() (shows UI). I would recommend checking quietly because the UI method will always show the latest version. You can always show your own UI._updateInfo.Updates for the available versions in your app cast. You can compare it with your currently installed version to see which ones are new and which ones are old.await _sparkle.InitAndBeginDownload(update); with the update you want to download. The download path is provided in the DownloadFinished event._sparkle.InstallUpdate(update, _downloadPath);The Handle Events Yourself sample and the Rollback sample will be very helpful to you in learning how to do these sort of things.
Ya. Implement IAppCastGenerator and set the SparkleUpdater.AppCastGenerator property to an instance of your class. You will have to implement the following methods:
AppCast DeserializeAppCast ( string appCastString ) ;
Task < AppCast > DeserializeAppCastAsync ( string appCastString ) ;
AppCast DeserializeAppCastFromFile ( string filePath ) ;
Task < AppCast > DeserializeAppCastFromFileAsync ( string filePath ) ;
string SerializeAppCast ( AppCast appCast ) ;
Task < string > SerializeAppCastAsync ( AppCast appCast ) ;
void SerializeAppCastToFile ( AppCast appCast , string outputPath ) ;
Task SerializeAppCastToFileAsync ( AppCast appCast , string outputPath ) ; As you can see, many of those functions are small variants of the core serialization and deserialization processes that you want to accomplish. You can look at the implementation of JsonAppCastGenerator and XMLAppCastGenerator for implementation examples.
Ya. Implement IAppCastGenerator and set the SparkleUpdater.AppCastGenerator property to an instance of your class. You'll have to make the actual app cast file yourself, though, since the app cast generator is only currently compatible with XML and JSON.
Right now, we are compatible with version 11. If you need to make changes, you can use your own IUIFactory implementation to fix any issues that come up.
DSA signatures are not recommended when using NetSparkleUpdater 2.0+. They are considered insecure!
You can still generate/use these signatures, however, using the DSAHelper tool (from this NuGet package or in the source code here). Key generation only works on Windows because .NET Core 3 does not have the proper implementation to generate DSA keys on macOS/Linux; however, you can get DSA signatures for a file on any platform. If you need to generate a DSA public/private key, please use the DSAHelper tool on Windows like this:
netsparkle-dsa /genkey_pair
You can use the DSAHelper to get a signature like this:
netsparkle-dsa /sign_update {YourInstallerPackage.msi} {NetSparkle_PrivateKey_DSA.priv}
dotnet tool install --global NetSparkleUpdater.Tools.DSAHelpernetsparkle-dsa command Pass a DSAChecker into your SparkleUpdater constructor rather than an Ed25519Checker .
If your app has DSA signatures, the app cast generator uses Ed25519 signatures by default starting with preview 2.0.0-20200607001 . To transition to Ed25519 signatures, create an update where the software has your new Ed25519 public key and a NEW url for a NEW app cast that uses Ed25519 signatures. Upload this update with an app cast that has DSA signatures so your old DSA-enabled/containing app can download the Ed25519-enabled update. Then, future updates and app casts should all use Ed25519.
Here are some things you can do to figure out how to get your app running:
SparkleUpdater.LogWriter = new LogWriter(LogWriterOutputMode.Console) and then watch your console output while debugging.Ya! Please help us make this library awesome!
NetSparkle is available under the MIT License.
Contributions are ALWAYS welcome! If you see a new feature you'd like to add, please open an issue to talk about it first, then open a PR for that implementation. If there's a bug you find, please open a PR with the fix or file an issue! Terima kasih!! :) You can also join us in our Gitter chat room!
An incomplete list of other projects related to software updating that you might want to look at if NetSparkleUpdater doesn't work for you:
