NetSparkle
NetSparkleUpdater 2.3.0
Легко настраиваемая структура обновления программного обеспечения для проектов C# .NET со встроенным интерфейсом UIS для Winforms, WPF и Avalonia
Netsparkle-это высококонфигурируемая структура обновления программного обеспечения для C#, которая совместима с Framework .net 6+ и .net 4.6.2+, имеет предварительно построенные UI для .NET Framework (Winforms, WPF) и .NET 6+ (Winforms, WPF, Avalonia), использует ED25519 или другие криптографические сигналы, и даже не разрешают UII), не допускают встроенные или встроенные или встроенные UII). Вы предоставляете где -то в Интернете, приложение с информацией об обновлении и версии, а также заметки о выпуске в формате Markdown или HTML. Эта библиотека поможет вам проверить обновление, показать пользователю заметки о выпуске и предложить загрузить/установить новую версию программного обеспечения.
Встроенные поддерживаемые типы загрузки обновлений:
Пожалуйста, смотрите об nupgrading.md для получения информации о основных изменениях версий, обновлениях и т. Д.
Netsparkle доступен через Nuget. Чтобы выбрать пакет Nuget для использования:
NetSparkleUpdater.SparkleUpdater package если вам не волнует встроенный пользовательский интерфейс и вы можете самостоятельно управлять вещами| Упаковка | Вариант использования | Выпускать | Предварительный просмотр | Загрузки |
|---|---|---|---|---|
| Netsparkleupdater.sparkleupdater | Основной пакет; Используйте 100% пользовательский интерфейс или нет пользовательского интерфейса (ничего встроенного) | |||
| Winforms UI (.NET Framework) | NetSparkle со встроенным пользовательским интерфейсом Winforms | |||
| Winforms UI (.net 6+) | NetSparkle со встроенным пользовательским интерфейсом Winforms | |||
| WPF UI (.net Framework и .net 6+) | NetSparkle со встроенным интерфейсом WPF | |||
| Avalonia UI | Netsparkle со встроенным пользовательским интерфейсом avalonia | |||
| Инструмент генератора приложений | netsparkle-generate-appcast CLI инструмент (в том числе ED25519 помощников) | |||
| DSA Helper Tool | Инструмент 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 .Чтобы создать свой файл приложения, см. В разделе «Приложение» этого документа.
Мы открыты для вкладов, которые могут упростить общий процесс установки/обновления для пользователя. Пожалуйста, подайте проблему сначала с вашей идеей перед началом работы, чтобы мы могли поговорить об этом.
Пожалуйста, посмотрите на образцы проектов в этом репозитории для основных, запущенных образцов использования !! Существуют образцы при использовании каждого из встроенных интерфейсов, а также образца «Сделай это в своем собственном пользовательском интерфейсе»!
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 или основная форма или аналогичный: 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/исходного кода включается в номер вашего приложения <Version> . Такого поведения нельзя избежать Netsparkleupdater в это время, поскольку мы полагаемся на AssemblyInformationalVersionAttribute , и поведение этого атрибута было изменено. Вашим пользователям может быть сказано, что в настоящее время они работают 1.0.0+commitHashHere от Netsparkleupdater (и вашего собственного приложения!). Мы также рекомендуем добавить следующие строки в файл вашего проекта (в новой <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 ваше приложение Cast XML -файл будет загружена, читать и сравнивается с в настоящее время запущенной версией. Если у него есть обновление программного обеспечения внутри, пользователь будет уведомлен с небольшим уведомлением о тосте (если поддерживается пользовательским интерфейсом и включен) или с диалогом обновлений, содержащим ваши заметки о выпуске. Пользователь может затем игнорировать обновление, попросить напомнить позже или загрузить/установить его сейчас.
Если вы хотите проверить обновление в фоновом режиме, если пользователь ничего не увидит, используйте
var updateInfo = _sparkle . CheckForUpdatesQuietly ( ) ;Если вы хотите иметь пункт меню для пользователя, чтобы проверить обновления, чтобы пользователь мог видеть пользовательский интерфейс, пока NetSparkle ищет обновления, используйте
_sparkle . CheckForUpdatesAtUserRequest ( ) ;Если у вас есть файлы, которые нуждаются в сохранении, подпишитесь на событие PreparingToExit:
_sparkle . PreparingToExit += ( ( x , cancellable ) =>
{
// ask the user to save, whatever else is needed to close down gracefully
} ) ; Обратите внимание, что если вы не используете UIFactory , вы должны использовать события CloseApplication или CloseApplicationAsync для закрытия вашего приложения; В противном случае ваш загруженный файл обновления никогда не будет выполнен/прочитана! Единственное исключение из этого - если вы хотите обработать все аспекты установки пакета обновлений самостоятельно.
Файл, который запускает ваш загруженный обновленный исполняемый файл, ждет только 90 секунд, прежде чем сдаться! Убедитесь, что ваше программное обеспечение закрывается в течение 90 секунд после закрытия/близкого уровня, вызываемого, если вы реализуете эти события! Если вам нужно событие, которое можно отменить, например, когда пользователю нужно спросить, можно ли закрыть (например, для сохранения их работы), используйте PreparingForExit или PreparingToExitAsync .
IUIFactory ; Установите SparkleUpdater.UIFactory , чтобы использовать экземпляр вашего объекта.ICheckingForUpdates для вашего пользовательского интерфейса, который сообщает пользователю, что SparkleUpdater проверяет обновленияIDownloadProgress для вашего пользовательского интерфейса, который показывает пользователю, что обновление загружаетсяIUpdateAvailable для вашего пользовательского интерфейса, который показывает пользователю, что обновление доступно вместе с заметками.IAppCastDataDownloader для настройки собственных методов загрузки приложений; Установите SparkleUpdater.AppCastDataDownloader , чтобы использовать экземпляр вашего объекта. NetSparkle включает в себя две реализации по умолчанию: WebRequestAppCastDataDownloader для загрузки информации о приложении из Интернета и LocalFileAppCastDAder для копирования/«загрузка» приложения с данного пути и LocalFileAppCastDownloader для копирования/IAppCastFilter для выполнения пользовательской фильтрации на объектах AppCastItem в вашем загруженном приложении, например, для рассмотрения только данного подмножества элементов в качестве действительных обновлений для вашего приложения; Установите AppCastHelper.AppCastFilter ( SparkleUpdater.AppCastHelper.AppCastFilter ), чтобы использовать экземпляр вашего объекта. Netsparkle включает в себя класс ChannelAppCastFilter , который вы можете использовать для фильтрации элементов по данным каналу продукта (например, Alpha, бета), если ваше приложение использует эти функции.IAppCastGenerator для контроля того, как приложения сериализованы и десериализованы; Установите SparkleUpdater.AppCastGenerator , чтобы использовать экземпляр вашего объекта. Netsparkle включает в себя две реализации: XMLAppCastGenerator , для сериализации/десериализации XML; и JsonAppCastGenerator , для сериализации/десериализации JSON. Инструмент CLI CLI CAST приложения также может выводить приложения XML и JSON.IAssemblyAccessor , чтобы контролировать, как загружаются версии, авторские права и другие данные о продукте для вашего приложения; Установить Configuration.AssemblyAccessor SparkleUpdater.Configuration.AssemblyAccessor Netsparkle содержит реализацию по умолчанию AssemblyDiagnosticsAccessor , которая должна работать в общем случае загрузки данных из данной сборки.ILogger и установите SparkleUpdater.LogWriter . По умолчанию используется класс LogWriter (который имеет свойство LogWriterOutputMode , чтобы управлять, записываются ли журналы в Console , Trace и т. Д.)ISignatureVerifier , чтобы изменить то, как обрабатываются ваши подписи для приложения, загрузки и т. Д.; Установите SparkleUpdater.SignatureVerifier , чтобы использовать экземпляр вашего объекта.IUpdateDownloader для настройки собственных методов загрузки и отправки прогресса в файлах обновления приложений (например, установщиков) для данного приложения; Установите SparkleUpdater.UpdateDownloader , чтобы использовать экземпляр вашего объекта. NetSparkle включает в себя две реализации по умолчанию: WebFileDownloader (по умолчанию) для загрузки файлов из Интернета/Интернета и LocalFileDownloader для копирования/«загрузки» файла из данного пути. Configuration подкласса, чтобы изменить определенную информацию и загрузку определенной информации NetSparkle - например, пропущенная информация о версии. Этот класс - тот, который использует экземпляр IAssemblyAccessor для сохранения и загрузки информации версии, названия продукта и т. Д. NetSparkle содержит три реализации: RegistryConfiguration , которая сохраняет и загружает информацию в реестр Windows (по умолчанию в Windows); JSONConfiguration , который сохраняет и загружает информацию в файл JSON (по умолчанию на MacOS/Linux); и DefaultConfiguration , который ничего не делает и служит запасением в случае, если JSONConfiguration не может найти действительное местоположение файла для сохранения и загрузки данных. Чтобы использовать экземпляр вашего класса, установите SparkleUpdater.Configuration .RegistryConfiguration позволяет быстро изменить путь реестра, в котором элементы сохраняются через BuildRegistryPathJSONConfiguration позволяет быстро изменить путь файла, где данные сохраняются через GetSavePathAppCastHelper если вы хотите полного управления процессом загрузки и анализа приложений. Обратите внимание, что вы, вероятно, можете сделать все, что вам нужно сделать, через свойства 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 для реализации некоторых различных функций, связанных с установкой, включая:GetWindowsInstallerCommandGetInstallerCommandRunDownloadedInstallerGetDownloadPathForAppCastItemUIFactory если вы не хотите реализовать весь интерфейс IUIFactory самостоятельно и просто хотите настроить функцию или две. Чтобы использовать экземпляр вашего класса, установите SparkleUpdater.UIFactory . IAppCastFilter Вы можете изменить то, как ваши приложения отфильтрованы через свойство AppCastHelper.AppCastFilter (через интерфейс IAppCastFilter ). Это позволяет вам изменить то, какие элементы доступны для ваших конечных пользователей.
Netsparkle содержит встроенную реализацию IAppCastFilter для фильтрации на основе каналов под названием ChannelAppCastFilter . Для некоторых примеров того, как использовать этот класс, см. В модульных тестах здесь. По сути, установите свойство List<string> ChannelSearchNames на каналы, которые вы хотите отфильтровать. Если вы хотите сохранить элементы без информации о канале (например, 1.2.3 ), установите KeepItemsWithNoChannelInfo на true .
Чтобы фактически установить каналы в ваших приложениях, брошенных в виде приложения, используйте свойство --channel инструмента CLI CAST или установите свойство файла Project в соответствующей <Version> -совместимой версии (например, <Version>1.0.2-beta1</Version> ), и инструмент приложения CLI CLI поднимется на это автоматически. Или, если вы создаете свое приложение вручную, установите свой свойство <sparkle:channel>YourChannelHere</sparkle:channel> на вашем <item> (или, если использование JSON, свойство channel ).
Netsparkleupdater вообще не должен использоваться с пользовательским интерфейсом. Вы можете сделать все самостоятельно или даже попросить библиотеку автоматически запустить загруженное обновление, установив SparkleUpdater.UserInteractionMode = UserInteractionMode.DownloadAndInstall . У этого репо есть образец по делам дела самостоятельно без какого-либо предварительно построенного пользовательского интерфейса в src/netsparkle.samples.handleeventsyourself.
Если вы хотите пользовательский интерфейс, мы предлагаем предварительно построенные интерфейсы в разных пакетах Nuget с небольшим количеством настраиваемых вариантов для Winforms, WPF и Avalonia. Последние интерфейсы запускаются с помощью реализации IUIFactory , называемой UIFactory в каждом из встроенных вариантов. Большинство методов в UIFactory могут быть переопределены, если вы хотите настроить поведение, и ProcessWindowAfterInit позволяет настроить каждое окно после его изготовления.
Если вы хотите полностью сбросить свой собственный пользовательский интерфейс, просто реализуйте интерфейс IUIFactory с любой библиотекой пользовательского интерфейса, которую вы хотите использовать. Вы можете скопировать или повторно использовать модели, код и т. Д. Из предварительно построенных параметров Netsparkleupdater, а копировать+вставка из этого репо в свой собственный, вероятно, хороший, быстрый способ начать. Не забудьте установить собственность SparkleUpdater.UIFactory с помощью экземпляра вашей реализации IUIFactory !
Обратите внимание: Netsparkle в основном не предпринимает никаких попыток беспокоиться о потоке (например, призыв к основному потоку), за исключением фонового цикла, вызывая в основной потоке, который запустил экземпляр SparkleUpdater . Другими словами, вообще говоря, Netsparkle сделает все в потоке, которое изначально создало экземпляр SparkleUpdater . Для большинства приложений это будет хорошо, так как они просто используют свой основной поток пользовательского интерфейса. В случае сомнений, для ваших собственных потребностей пользовательского интерфейса обязательно проверьте InvokeRequired на Winforms и на WPF/Avalonia, маршал вещей в потоку пользовательского интерфейса (если вы не используете привязку к данным, в этом случае это обрабатывается для вас!).
Передача вашей собственной реализации IUIFactory , которая запускает Windows/вещи в новых потоках в SparkleUpdater , не является поддерживаемой конфигурацией. Если вы хотите запустить свой собственный пользовательский интерфейс в нескольких потоках (например, для 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 , Pass --use-ed25519-signature-attribute к генератору актеров приложений.) Обратите внимание, что NetSparkle совместим с подписями ED25519 по умолчанию, но фреймворк может обрабатывать различную реализацию класса ISignatureVerifier , чтобы проверять различные виды подписей без основной версии.
Вот пример приложения 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 , но вы можете вручную проверить подписи Changelog, если вам нравится или установить ReleaseNotesGrabber.ChecksReleaseNotesSignature = true в вашем пользовательском интерфейсе.<pubDate>sparkle:channel : канал для этого приложения, например, beta (не требуется) - принимает только 1 канал<enclosure>url : URL -адрес файла обновленияsparkle:version : машино читаемый номер версии этого обновленияlength , необязательно: (не проверено) Размер файла обновления в байтахtype : игнорируетсяsparkle:signature : DSA/ED25519 Подпись файла обновленияsparkle:criticalUpdate , необязательно: если равный true или 1 , пользовательский интерфейс укажет, что это критическое обновлениеsparkle:os : Операционная система для приложения. По умолчанию в окна, если не поставляются. Для Windows используйте «Win» или «Windows»; Для macOS используйте «macOS» или «OSX»; Для Linux используйте "Linux". По умолчанию вам нужно 2 подписи ( SecurityMode.Strict ):
sparkle:signature="..." )ПРИМЕЧАНИЕ. Инструмент генератора приложений создает обе эти подписи для вас, когда он воссоздает файл appcast.xml.
Вы можете генерировать подписи ED25519 с помощью инструмента AppCastGenerator (из этого пакета Nuget или в исходном коде здесь). Этот инструмент требует установки .NET 6, 7, 8 или 9 или 9. Пожалуйста, см. В разделе ниже для вариантов и примеров генерации ключей ED25519 и для их использования при создании приложения.
AppCastGenerator (из этого пакета Nuget или в исходном коде здесь), чтобы легко создать файл приложения. Доступные варианты описаны ниже. Вы можете установить его в свой CLI через dotnet tool install --global NetSparkleUpdater.Tools.AppCastGenerator .string.Format или аналогичная вещь - замечательная вещь).Если вы хотите использовать приложение JSON, а не XML:
--output-type jsonSparkleUpdater.AppCastGenerator для new JsonAppCastGenerator(mySparkleUpdater.LogWriter) .JsonAppCastGenerator.HumanReadableOutput на false .Учате какой -то вариант, который вы хотели бы увидеть? Подайте проблему в этот репо или добавьте его самостоятельно и отправьте нам запрос на вытяжку!
--show-examples : печатные примеры использования в консоли.--help : покажите все варианты и их описания. -a / --appcast-output-directory : каталог, в котором можно написать файл output appcast.xml . Пример Использование: -a ./MyAppCastOutput-e / --ext : При поиске файлов для добавления в приложение используйте заданное расширение (ы) при поиске файлов. По умолчанию к exe . Пример использования: -e exe,msi-b / --binaries : Путь файла к каталогу, который следует искать при поиске файлов для добавления в приложение. По умолчанию . Полем Пример использования: -b my/build/directory-r / --search-binary-subdirectories : верно для повторного поиска бинарного каталога для двоичных файлов; Неверно искать только верхний каталог. По умолчанию false . Пример использования: -r .--single-file : ОДИН ФАЙЛ для добавления в приложение-если установлено, --binaries , --ext и т. Д. Все игнорируются. Полезно использовать, если ваш выходной файл не имеет расширения (например, исполняемый файл UNIX). Пример Использование: --single-file path/to/my/file-f / --file-extract-version : извлечь ли извлечение версии файла из имени файла, а не из самого файла (например, DLL). По умолчанию false . Используйте, когда ваши файлы, которые будут загружены Netsparkleupdater, будут иметь номер версии в имени файла, например, «Мое приложение 1.3.2-alpha1.exe». Обратите внимание, что это ищет только последние четыре элемента/папки каталогов. Пример использования: -f true--file-version : Используйте для установки версии для бинарного входа в актерский состав. Обратите внимание, что эта версия может быть установлен только один раз, поэтому при создании актеров приложения убедитесь, что вы также: A) иметь только один бинар в вашем приложении | Б) Используйте --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 : текст, чтобы поместить в приложении теги 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 : префикс для изменения имен файлов журнала изменения. По умолчанию генератор ищет имена файлов с помощью формата «[версия] .md». Если вы установите этот параметр в (например) «журнал изменения моего приложения», он будет искать имена файлов в формате «My Apploy Log [версия] .md», а также «[версия] .md».-n / --product-name : Название продукта для вашего программного обеспечения. Используется при настройке заголовка для вашего приложения и его предметов. По умолчанию Application . Пример использования: -n "My Awesome App"-x / --url-prefix-version : добавьте номер версии в качестве префикса в имя файла для URL загрузки. По умолчанию ложно. Например, если --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 : PATH TO NetSparkle_Ed25519.priv и NetSparkle_Ed25519.pub , которые являются вашим личным и публичным ключи ED25519 для обновлений программного обеспечения соответственно. Пример Использование: --key-path my/path/to/keysSPARKLE_PRIVATE_KEY и SPARKLE_PUBLIC_KEY прежде чем запустить generate_appcast . Инструмент приоритет ключам окружающей среды над ключами, сидя на диске!--signature-file-extension : расширение (без . ) Использование для файла подписи приложения. По умолчанию signature . Пример Использование: --signature-file-extension txt .--output-file-name выходного файла для приложения, отлитого . или расширение. Расширение контролируется будь то вывод XML или JSON и не настраивается. По умолчанию «приложение». Конечно, вы всегда можете изменить это позже самостоятельно после создания приложения; Этот вариант предназначен только для удобства. Пример Использование: --output-file-name super_app_download_info .--use-ed25519-signature-attribute : Если True и выполнение вывода XML, атрибутом выходной сигнатуры в XML будет edSignature , а не signature для соответствия исходной библиотеке Sparkle. Не влияет на приложение JSON.--file-version : Используйте для установки версии для бинарного входа в актерский состав. Обратите внимание, что эта версия может быть установлен только один раз, поэтому при создании актеров приложения убедитесь, что вы также: A) иметь только один бинар в вашем приложении | Б) Используйте --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 уже находится в приложении, отличном (либо из переживания, либо из другого двоичного), а на диске обнаружено еще 1,0.1, то данные 1.0.1 в приложении будут переписаны на основе обнаруженного бинарника. Обратите внимание, что это означает, что если у вас есть несколько версий 1.0.1 на диске (что вы не должны делать ...), последний найденный будет той в вашем приложении! Пример Использование: --overwrite-old-items--human-readable : если это правда, делает файл приложения для вывода, четко читаемый (новости, отступы). Пример Использование: --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:
