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.谨慎使用。 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:
