NetSparkle
NetSparkleUpdater 2.3.0
C＃.NET項目的一個易於自定義的軟件更新框架，該框架具有內置UIS，用於Winforms，WPF和Avalonia
NetSparkle是C＃的高度配置軟件更新框架，與.NET 6+和.NET框架4.6.2+兼容，已預先為.NET框架（Winforms，wpf）和.NET 6+（Winforms，Winforms，Winforms，WPF，Avalonia）使用ED255519或其他Cryiposem for uis for uis for for for uis of uis of uis for for uis for for uis of uis of uis for for uis！您可以在Internet上的某個地方提供帶有更新和版本信息的應用程序，以及Markdown或HTML格式的發行說明。然後，該庫可幫助您檢查更新，向用戶顯示發行說明，並提供下載/安裝軟件的新版本。
內置支持的更新下載類型：
有關主要版本更改，更新等的信息，請參見upgrading.md。
NetSparkle可通過Nuget獲得。選擇用於使用的nuget軟件包：
NetSparkleUpdater.SparkleUpdater package如果您不關心內置UI並可以自己管理內容| 包裹 | 用例 | 發布 | 預覽 | 下載 |
|---|---|---|---|---|
| NetSparkleupDater.sparkleupdater | 核心包；使用100％自定義UI或沒有UI（沒有內置） | |||
| Winforms UI（.NET框架） | NetSparkle帶有內置Winforms UI | |||
| Winforms UI（.net 6+） | NetSparkle帶有內置Winforms UI | |||
| WPF UI（.NET框架和.NET 6+） | 內置WPF UI的NetSparkle | |||
| Avalonia UI | 內置Avalonia UI的NetSparkle | |||
| 應用程序鑄造機工具 | netsparkle-generate-appcast CLI工具（包括ED25519助手） | |||
| DSA輔助工具 | netsparkle-dsa CLI工具（DSA幫助者） |
工具安裝的快速信息：
dotnet tool install --global NetSparkleUpdater.Tools.AppCastGenerator ;安裝後，在您的命令行上可作為netsparkle-generate-appcast提供dotnet tool install --global NetSparkleUpdater.Tools.DSAHelper ;安裝後您的命令行上的netsparkle-dsa可用定型軟件的典型軟件更新路徑可能看起來像這樣：
dotnet publish ）現在，NetSparkleupDater對1.，2.或4的幫助沒有幫助。 “為什麼不？”，您可能會問：
sudo一起運行，則在MacOS Avalonia樣本中有一個例子。要創建您的應用程序文件，請參見本文檔的應用程序鑄件部分。
我們開放的貢獻可能會使用戶更容易整體安裝/更新過程。請先在開始工作之前先對您的想法提出問題，以便我們談論它。
請查看此存儲庫中的示例項目，以獲取基本可運行的用法樣本！ ！使用每個內置UI以及“在您自己的UI中自己做”樣本時，都有一些樣本！
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或Main表單或類似形式： 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），DMG文件（Linux），.tar.gz文件（Linux）或類似工具為您的項目創建安裝程序。更新工作部分中的更多信息。netsparkle-generate-appcast --help ）： netsparkle-generate-appcast -b binary/folder -p change/log/folder -u https://example.com/downloads -l https://example.com/downloads/changelogs.signature或類似文件）上傳到服務器上的適當位置SparkleUpdater.LogWriter ，看看是否有任何有用的調試信息顯示在控制台上！在您的項目文件中，請確保您設置了一些內容，以便庫可以在以後的相關詳細信息中閱讀。注意：您可以使用自己的IAssemblyAccessor從其他地方加載版本信息。但是，設置項目文件中的內容很容易，並且NetSparkleupDater可以在本地閱讀！
< 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 >重要說明：在.NET 8+中，在.NET的核心中進行了更改，該核心會導致您的git/source代碼提交哈希（Hash）包含在您的應用程序的<Version>編號中。由於我們依靠AssemblyInformationalVersionAttribute ，因此無法通過NetSparkleupDater避免這種行為，並且此屬性的行為已更改。可能會告訴您的用戶目前由NetSparkleupDater（以及您的本機應用程序本身！）運行1.0.0+commitHashHere 。我們還建議將以下幾行添加到您的項目文件中（在新的<PropertyGroup>中或現有一個中）：
< 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!在第一個application.idle事件中，將下載，讀取並將其與當前正在運行的版本進行比較。如果內部有軟件更新，則將通過一些敬酒通知（如果由UI並啟用）通知用戶，或使用包含您發行說明的更新對話框。然後，用戶可以忽略更新，要求稍後提醒，或立即下載/安裝。
如果您想在背景中檢查更新而沒有用戶看到任何東西，請使用
var updateInfo = _sparkle . CheckForUpdatesQuietly ( ) ;如果您想擁有菜單項供用戶檢查更新，以便用戶可以在NetSparkle尋找更新時查看UI，請使用
_sparkle . CheckForUpdatesAtUserRequest ( ) ;如果您有需要保存的文件，請訂閱準備事件：
_sparkle . PreparingToExit += ( ( x , cancellable ) =>
{
// ask the user to save, whatever else is needed to close down gracefully
} ) ;請注意，如果您不使用UIFactory ，則必須使用CloseApplication或CloseApplicationAsync事件來關閉應用程序；否則，您的下載更新文件將永遠不會執行/讀取！唯一的例外是，如果您想自己處理安裝更新程序包的所有方面。
啟動您下載的更新可執行文件的文件僅等待90秒，然後放棄！如果您實施這些事件，請確保您的軟件在閉合/閉合封閉式封閉式/閉合封閉式封閉式中關閉！如果您需要一個可以取消的事件，例如需要詢問用戶是否可以關閉（例如保存他們的工作），請使用PreparingForExit或PreparingToExitAsync 。
IUIFactory ；設置SparkleUpdater.UIFactory以利用對象的實例。ICheckingForUpdates ，該UI告訴用戶SparkleUpdater正在檢查更新IDownloadProgress向用戶顯示正在下載更新IUpdateAvailable該UI向用戶顯示更新以及發行說明IAppCastDataDownloader來設置自己的方法以下載應用程序鑄造數據；將SparkleUpdater.AppCastDataDownloader設置為使用對象的實例。 NetSparkle默認包含兩個實現： WebRequestAppCastDataDownloader ，用於從Internet上下載cast Informate的cast信息，以及LocalFileAppCastDownloader ，用於復制/“從給定路徑下載”的應用程序，IAppCastFilter在下載的應用程序中對AppCastItem對象進行自定義過濾，例如，僅將給定的項目子集作為應用程序的有效更新；設置AppCastHelper.AppCastFilter （ SparkleUpdater.AppCastHelper.AppCastFilter ）以利用對象的實例。 NetSparkle包括ChannelAppCastFilter類，如果您的應用程序使用這些功能，則可以用給定的產品頻道（例如Alpha，beta）過濾項目。IAppCastGenerator以控制應用程序如何序列化和應對序列化；將SparkleUpdater.AppCastGenerator設置為使用對象的實例。 NetSparkle包括兩個實現： XMLAppCastGenerator ，用於XML序列化/避難所化；和JsonAppCastGenerator ，用於JSON序列化/避難所。應用程序Cast Generator CLI工具還可以輸出XML和JSON App Casts。IAssemblyAccessor ，以控製版本，版權和其他產品詳細信息如何為您的應用程序加載；設置Configuration.AssemblyAccessor （ SparkleUpdater.Configuration.AssemblyAccessor ）以利用對象的實例。 NetSparkle包含一個默認實現，即AssemblyDiagnosticsAccessor ，該實現應在加載給定彙編的數據的一般情況下起作用。ILogger並設置SparkleUpdater.LogWriter 。默認情況下，使用LogWriter類（其中具有LogWriterOutputMode屬性來控制日誌是否寫入Console ， Trace等）ISignatureVerifier ，以更改應用程序，下載等的簽名如何處理；設置SparkleUpdater.SignatureVerifier以利用對象的實例。IUpdateDownloader ，以設置自己的方法，用於下載和發送給定應用程序鑄件的應用程序更新文件（例如安裝程序）上的進度；設置SparkleUpdater.UpdateDownloader以利用您的對象的實例。 NetSparkle默認包含兩個實現： WebFileDownloader （默認）從Web/Internet下載文件，以及從給定路徑複製/“下載”文件的LocalFileDownloader 。 Configuration ，以更改某些NetSparkle信息的保存和加載方式 - 例如，跳過版本信息。此類是利用IAssemblyAccessor實例保存和加載版本信息，產品名稱等的一類。 NetSparkle包含三個實現： RegistryConfiguration ，它將信息保存和加載到Windows註冊表（default in Windows上）； JSONConfiguration ，將信息保存並加載到JSON文件（MacOS/Linux上的默認值）；和DefaultConfiguration ，它無能為力並用作後備，以防JSONConfiguration找不到有效的文件位置來保存和加載數據。要使用類的實例，請設置SparkleUpdater.Configuration 。RegistryConfiguration可讓您快速更改註冊表路徑，其中通過BuildRegistryPath保存項目JSONConfiguration允許您快速更改通過GetSavePath保存數據的文件路徑AppCastHelper如果您想完全控制應用程序下載和解析過程。請注意，您可能可以通過AppCastHelper屬性（包括IAppCastFilter AppCastFilter ）完成所有需要做的一切，但是子分類將為您提供對整個過程的完整，絕對的控制。要使用類的實例，請設置SparkleUpdater.AppCastHelper 。ReleaseNotesGrabber控制發行說明下載（以及因此顯示）過程。要使用類的實例，請設置UIFactory.ReleaseNotesGrabberOverride 。WebFileDownloader如果您不想自己實現IUpdateDownloader ，並且只想覆蓋一個或兩個功能，例如CreateHttpClient或RetreiveDestinationFileNameAsync 。要使用類的實例，請設置SparkleUpdater.UpdateDownloader 。WebRequestAppCastDataDownloader如果您不想實現IAppCastDataDownloader ，並且只想覆蓋一個或兩個函數，例如CreateHttpClient 。要使用類的實例，請設置SparkleUpdater.AppCastDataDownloader 。LogWriter以實現PrintMessage函數；因為ILogger是一個非常簡單的界面，因此，如果您的需求很複雜，您可能可以自己實現該界面。要使用類的實例，請設置SparkleUpdater.LogWriter 。SparkleUpdater以實現一些不同的安裝相關功能，包括：GetWindowsInstallerCommandGetInstallerCommandRunDownloadedInstallerGetDownloadPathForAppCastItemIUIFactory接口，則超越UIFactory ，只是想配置一個或兩個功能。要使用類的實例，請設置SparkleUpdater.UIFactory 。 IAppCastFilter您可以通過AppCastHelper.AppCastFilter屬性（通過IAppCastFilter接口）更改應用程序鑄件的過濾方式。這使您可以更改最終用戶可用的項目。
NetSparkle包含一個內置的IAppCastFilter實現，用於基於頻道的過濾，稱為ChannelAppCastFilter 。有關如何使用該類別的一些示例，請參見此處的單元測試。基本上，將List<string> ChannelSearchNames屬性設置為要過濾的頻道。如果您想在其中保留任何頻道信息（例如1.2.3 ），請將KeepItemsWithNoChannelInfo設置為true 。
要實際設置應用程序鑄件 /應用程序中的頻道，請使用應用程序CLI工具的--channel屬性，或將項目文件的<Version>設置為適用的SEMVER兼容版本（例如<Version>1.0.2-beta1</Version> ），以及應用程序Cast Cli工具將自動拾取。或者，如果您要手動構建應用程序鑄件，請設置<sparkle:channel>YourChannelHere</sparkle:channel> <item>上的屬性（或者，如果使用JSON，則為channel屬性）。
NetSparkLeupDater根本不必與UI一起使用。您可以自己完成所有操作，甚至可以通過設置SparkleUpdater.UserInteractionMode = UserInteractionMode.DownloadAndInstall來自動運行下載的更新。此存儲庫有一個示例，可以自己做事，而無需在src/netsparkle.smples.handleevents yours中使用任何預先構建的UI。
如果您想要UI，我們將在不同的Nuget軟件包中提供預先構建的UI，並提供少數可自定義選項的Winforms，WPF和Avalonia。 UI是通過IUIFactory實現觸發的，在每個內置選項中稱為UIFactory 。如果您想調整行為，則可以覆蓋UIFactory中的大多數方法，並且ProcessWindowAfterInit可以使您在製作每個窗口後自定義每個窗口。
如果您想完全滾動自己的UI，只需使用要使用的任何UI庫來實現IUIFactory接口。您可以從NetSparkleupDater的預構建選項中復製或重複使用視圖模型，代碼等，並將此存儲庫中的代碼複製到您自己的+粘貼代碼可能是一種很好，快速的啟動方式。不過，不要忘記將SparkleUpdater.UIFactory屬性設置為使用IUIFactory實現的實例！
請注意：NetSparkle基本上沒有嘗試擔心線程（例如致電主線程），除了呼叫啟動SparkleUpdater實例的主線程的背景循環。換句話說，一般而言，NetSparkle將在最初創建SparkleUpdater實例的線程上完成所有內容。對於大多數應用程序，這會很好，因為它們僅使用主UI線程。如有疑問，出於您自己的需求，請確保在Winforms和WPF/Avalonia上檢查InvokeRequired ，否則在UI線程中進行元帥的內容（除非您使用數據綁定在這種情況下為您處理！）。
將您自己的IUIFactory實現啟動到新線程中的Windows/Things進入SparkleUpdater並不是支持的配置。如果您想在多個線程上運行自己的UI（例如Winforms在關閉主形式時不會關閉NetSparkleupDater的窗口），請使用SparkleUpdater的事件而不是UIFactory進行操作；請參閱src/netSparkle.samples.forms.multithread示例，以獲取有關如何執行此操作的實例。
該應用程序只是XML或JSON文件。它包含諸如產品的標題和描述以及軟件的定義。
我們強烈建議您使用NetSparkle-Generate-Appcast工具來創建（然後重新創建/更新）文件，因為它可以幫助您滿足您的所有簽名要求。
dotnet tool install --global NetSparkleUpdater.Tools.AppCastGeneratornetsparkle-generate-appcast命令可用。您可以使用netsparkle-generate-appcast --help查看此工具的完整選項列表。默認情況下，NetSparkle在大多數情況下都使用與Sparkle兼容的XML應用程序鑄件。 NetSparkle使用sparkle:signature而不是sparkle:edSignature因此您可以選擇如何簽名文件/應用程序。 （如果您想使用sparkle:edSignature ，請通過--use-ed25519-signature-attribute到App Cast Generator。）請注意，NetSparkle與NetSparkle兼容並默認使用ED25519簽名，但是該框架可以處理ISignatureVerifier類的不同實現，以檢查Insignature Verlifier類的不同類型，而無需使用不同的簽名版本Bump bump bump。
這是一個示例XML應用程序：
<? 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讀取<item>標籤，以確定是否可用。
每個<item>中的重要標籤是：
<description><sparkle:releaseNotesLink>標籤。<sparkle:releaseNotesLink><description>標籤，則將使用它。sparkle:signature ，可選：DSA/ED25519文檔的簽名； NetSparkle不會為您檢查此簽名，除非您將ReleaseNotesGrabber.ChecksReleaseNotesSignature設置為true ，但是如果您喜歡或設置ReleaseNotesGrabber.ChecksReleaseNotesSignature = true則可以在UI中手動驗證ChangElog簽名。<pubDate>sparkle:channel ：此應用程序鑄件的頻道，例如beta （不需要） - 僅接受1個頻道<enclosure>url ：更新文件的URLsparkle:version ：此更新的機器可讀版本號length ，可選：（未驗證）字節中更新文件的大小type ：忽略sparkle:signature ：DSA/ED25519更新文件的簽名sparkle:criticalUpdate ，可選：如果等於true或1 ，則UI表示這是關鍵更新sparkle:os ：應用程序鑄件的操作系統。如果不提供，則默認為Windows。對於Windows，使用“ Win”或“ Windows”；對於MacOS，請使用“ MacOS”或“ OSX”；對於Linux，使用“ Linux”。默認情況下，您需要2個簽名（ SecurityMode.Strict ）：
sparkle:signature="..." ）注意：應用程序發電機工具在重新創建Appcast.xml文件時為您創建這兩個簽名。
您可以使用AppCastGenerator工具（來自此Nuget軟件包或在此處的源代碼中）生成ED25519簽名。此工具需要安裝.NET 6、7、8或9個桌面運行時。請參閱下面的部分，以獲取有關生成ED25519鍵以及創建應用程序時使用的選項和示例。
AppCastGenerator工具（此處的Nuget軟件包或源代碼中的AppcastGenerator工具）輕鬆創建您的應用程序鑄造文件。可用選項如下所述。您可以通過dotnet tool install --global NetSparkleUpdater.Tools.AppCastGenerator 。string.Format或clase是一件很棒的事情）為您生成應用程序的腳本。如果您想使用JSON應用程序而不是XML：
--output-type json通過應用程序發電機生成應用程序鑄造文件時SparkleUpdater.AppCastGenerator設置為new JsonAppCastGenerator(mySparkleUpdater.LogWriter) 。JsonAppCastGenerator.HumanReadableOutput READABLETPUT屬性設置為false 。缺少您想看到的一些選項？在此存儲庫上提出問題，或者自己添加並向我們發送拉請請求！
--show-examples ：打印對控制台的使用示例。--help ：顯示所有選項及其描述。 -a / --appcast-output-directory ：在其中編寫輸出appcast.xml文件的目錄。示例使用： -a ./MyAppCastOutput-e / --ext ：尋找要添加到應用程序鑄造的文件時，請在尋找文件時使用給定的擴展名。默認為exe 。示例使用： -e exe,msi-b / --binaries ：目錄的文件路徑，在尋找要添加到應用程序的文件時應搜索的目錄。默認為. 。示例使用： -b my/build/directory-r / --search-binary-subdirectories ：真實地遞歸搜索二進制目錄； false僅搜索頂級目錄。默認為false 。示例使用： -r 。--single-file ：要添加到應用程序鑄件的單個文件 - 如果設置，則--binaries ， --ext等都被忽略了。如果輸出文件沒有擴展名，則有助於使用（例如，UNIX可執行文件）。示例使用： --single-file path/to/my/file-f / --file-extract-version ：是否從文件的名稱而不是文件（例如dll）本身提取文件版本。默認為false 。使用NetSparkLeupDater下載的文件將在文件名中具有版本編號，例如“我的App 1.3.2-Alpha1.exe”。請注意，這僅搜索最後四個目錄項目/文件夾。示例使用： -f true--file-version ：用於將二進製版的版本設置為進入應用程序的二進製版。請注意，此版本只能設置一次，因此在生成應用程序時，請確保您要么：a）在您的應用程序中只有一個二進製文件| b）利用--reparse-existing參數，以便拾取舊項目。如果生成器找到2個沒有任何已知版本的二進製文件，並且設置了--file-version ，則會發出錯誤。示例使用： --file-version 1.3.2-o / --os ：應用程序歸屬的操作系統。字符串必須包括以下內容之一： windows ， mac ， linux 。默認為windows 。示例使用： -o macos-arm64 ; -o windows-x64--description-tag ：要放入應用程序鑄造描述標籤/信息的文本。默認為“最新更改，並具有更新的鏈接”。示例使用： --description-tag "Hello I am a Cool App"--link-tag ：要放入應用程序cast link標籤/信息的文本。如果您使用此功能，應該是您的應用程序下載URL。示例使用： --link-tag https://mysite.com/coolapp/appcast.xml-u / --base-url ：用於下載的URL的開始部分。將下載的文件名將在此部分URL之後放置。示例使用： -u https://myawesomecompany.com/downloads-l / --change-log-url ：用於更改日誌文件的URL的開始部分。將下載的更改日誌文件將在此部分URL之後放置。如果未指定此選項，則將更改日誌數據放入應用程序本身。示例使用： -l https://myawesomecompany.com/changes-p / --change-log-path 。這些預計將以.md的擴展為降級格式。更改日誌文件的文件名必須包含軟件的版本，例如1.3.2.md示例使用-p path/to/change/logs 。 （注意：發電機還將嘗試查找像這樣的文件名的更改日誌： MyApp 1.3.2.md ）--change-log-name-prefix ：更改日誌文件名稱的前綴。默認情況下，生成器以“ [version] .md”格式搜索文件名。如果將此參數設置為（例如）“我的應用更改日誌”，它將使用“我的應用程序更改log [version] .md”以及“ [version] .md”的格式搜索文件名。-n / --product-name ：軟件的產品名稱。在設置應用程序演員及其項目的標題時使用。默認為Application 。示例使用： -n "My Awesome App"-x / --url-prefix-version ：將版本編號添加為下載URL文件名的前綴。默認為false。例如，如果--base-url是www.example.com/downloads ，則您的版本為1.4.2 ，而您的應用程序名稱為MyApp.exe ，您的下載URL將成為www.example.com/downloads/1.4.2/MyApp.exe 。示例使用： -x true 。--key-path ： NetSparkle_Ed25519.priv和NetSparkle_Ed25519.pub文件的路徑，分別是您的私人和公共ED25519鍵，分別用於軟件更新。示例使用： --key-path my/path/to/keysgenerate_appcast之前設置SPARKLE_PRIVATE_KEY和SPARKLE_PUBLIC_KEY環境變量。該工具優先考慮坐在磁盤上的鍵上的環境鍵！--signature-file-extension ：用於應用程序簽名文件的擴展名（無. ）。默認為signature 。示例使用： --signature-file-extension txt 。--output-file-name ：使用該應用程序的輸出文件名.或擴展。擴展是由它是XML還是JSON輸出來控制的，並且不可配置。默認為“ Appcast”。當然，在生成應用程序鑄件後，您始終可以自行更改。此選項僅出於方便。示例使用： --output-file-name super_app_download_info 。--use-ed25519-signature-attribute ：如果true並執行XML輸出，則XML中的輸出簽名屬性將是符合原始閃光庫的edSignature ，而不是signature 。對JSON應用程序演員沒有影響。--file-version ：用於將二進製版的版本設置為進入應用程序的二進製版。請注意，此版本只能設置一次，因此在生成應用程序時，請確保您要么：a）在您的應用程序中只有一個二進製文件| b）利用--reparse-existing參數，以便拾取舊項目。如果生成器找到2個沒有任何已知版本的二進製文件，並且設置了--file-version ，則會發出錯誤。--critical-versions ：在應用程序演員中標記為關鍵的版本的逗號分隔列表。必須完全匹配版本文本。例如，“ 1.0.2,1.2.3.1”。--reparse-existing ：重新放置現有的應用程序，而不是覆蓋它並重新創建它。跳過應用程序中的版本，因此，如果您部署具有相同版本的新二進製文件，則需要手動編輯應用程序鑄件，以刪除重新部署版本的舊列表。示例使用： --reparse-existing true--overwrite-old-items文件，則應導致應用程序的應用程序在應用程序中重寫。換句話說，如果1.0.1已經在應用程序中（來自Reparsing或其他二進製文件），並且在磁盤上找到另外1.0.1，則將根據發現的二進製文件來重寫應用程序中的1.0.1數據。請注意，這意味著，如果您在磁盤上有多個1.0.1版本（您不應該這樣做...），則發現的最後一個將是應用程序中的一個版本！示例使用： --overwrite-old-items--human-readable ：如果為true，則使輸出應用程序鑄造文件可讀（新聞單，凹痕）。示例使用： --human-readable true--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.
沒有。 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.)
是的。 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.
是的！
--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.
是的。
是的。
是的。 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.
是的。 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.
是的。 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.是的！ 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!謝謝你！ ！ :) 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:
