Repository files navigation

AutoUpdater.NET is a class library that allows .NET developers to easily add auto update functionality to their classicdesktop application projects.

PM>Install-Package Autoupdater.NET.Official

• .NET Framework 4.6.2 or above
• .NET Core 3.1
• .NET 5.0 or above

• Windows 8 or above
• Windows version lower than 8 requires .NET Framework 4.5 or above installed for ZipExtractor to work. You can useinstaller instead of zip file as an update file to avoid this issue.

This library only works for WinForms or WPF application projects.

AutoUpdater.NET downloads the XML file containing update information from your server. It uses this XML file to get theinformation about the latest version of the software. If the latest version of the software is greater than the currentversion of the software installed on User's PC then AutoUpdater.NET shows update dialog to the user. If user press theupdate button to update the software then It downloads the update file (Installer) from URL provided in XML file andexecutes the installer file it just downloaded. It is a job of installer after this point to carry out the update. Ifyou provide zip file URL instead of installer then AutoUpdater.NET will extract the contents of zip file to applicationdirectory.

AutoUpdater.NET uses XML file located on a server to get the release information about the latest version of thesoftware. You need to create XML file like below and then you need to upload it to your server.

<?xml version="1.0" encoding="UTF-8"?><item>  <version>2.0.0.0</version>  <url>https://rbsoft.org/downloads/AutoUpdaterTest.zip</url>  <changelog>https://github.com/ravibpatel/AutoUpdater.NET/releases</changelog>  <mandatory>false</mandatory></item>

There are two things you need to provide in XML file as you can see above.

• version (Required) : You need to provide latest version of the application between version tags. Version should be inX.X.X.X format.

• url (Required): You need to provide URL of the latest version installer file or zip file between url tags.AutoUpdater.NET downloads the file provided here and install it when user press the Update button.

• changelog (Optional): You need to provide URL of the change log of your application between changelog tags. If youdon't provide the URL of the changelog then update dialog won't show the change log.

• mandatory (Optional): You can set this to true if you don't want user to skip this version. This will ignore RemindLater and Skip options and hide both Skip and Remind Later button on update dialog.

  • mode (Attribute, Optional): You can provide mode attribute on mandatory element to change the behaviour of themandatory flag. If you provide "1" as the value of mode attribute then it will also hide the Close button onupdate dialog. If you provide "2" as the value of mode attribute then it will skip the update dialog and startdownloading and updating application automatically.

  <mandatorymode="2">true</mandatory>

  • minVersion (Attribute, Optional): You can also provide minVersion attribute on mandatory element. When you provideit, Mandatory option will be triggered only if the installed version of the app is less than the minimum versionyou specified here.

  <mandatoryminVersion="1.2.0.0">true</mandatory>

• executable (Optional): You can provide the path of the executable if it was changed in the update. It should berelative to the installation directory of the application. For example, if the new executable is located inside thebin folder of the installation directory, then you should provide it as shown below.

<executable>bin\AutoUpdaterTest.exe</executable>

• args (Optional): You can provide command line arguments for Installer between this tag. You can include %path% withyour command line arguments, it will be replaced by path of the directory where currently executing applicationresides.
• checksum (Optional): You can provide the checksum for the update file between this tag. If you do this AutoUpdater.NETwill compare the checksum of the downloaded file before executing the update process to check the integrity of thefile. You can provide algorithm attribute in the checksum tag to specify which algorithm should be used to generatethe checksum of the downloaded file. Currently, MD5, SHA1, SHA256, SHA384, and SHA512 are supported.

<checksumalgorithm="MD5">Update file Checksum</checksum>

You can also use the XML creator tool created by one of the user to create the XML file. You can download itfromhere.

After you done creating and uploading XML file, It is very easy to add a auto update functionality to your application.First you need to add following line at the top of your form.

usingAutoUpdaterDotNET;

Now you just need to add following line to your main form constructor or in Form_Load event. You can add this lineanywhere you like. If you don't like to check for update when application starts then you can create a Check for updatebutton and add this line to Button_Click event.

AutoUpdater.Start("https://rbsoft.org/updates/AutoUpdaterTest.xml");

Start method of AutoUpdater class takes URL of the XML file you uploaded to server as a parameter.

AutoUpdater.Start should be called from UI thread.

AutoUpdater.NET uses Assembly version to determine the current version of the application. You can update it by going toProperties of the project as shown in following screenshot.

Version specified in XML file should be higher than Assembly version to trigger the update.

If you want to provide your own Assembly then you can do it by providing second argument of Start method as shown below.

AutoUpdater.Start("https://rbsoft.org/updates/AutoUpdaterTest.xml",myAssembly);

If you don't want AutoUpdater.NET to determine the installed version from assembly then you can provide your own versionby assigning it to InstalledVersion field as shown below.

AutoUpdater.InstalledVersion=newVersion("1.2");

If you like to use ftp XML URL to check for updates or download the update file then you can provide you FTP credentialsin alternative Start method as shown below.

AutoUpdater.Start("ftp://rbsoft.org/updates/AutoUpdaterTest.xml",newNetworkCredential("FtpUserName","FtpPassword"));

If you are using FTP download URL in the XML file then credentials provided here will be used to authenticate therequest.

If you want to check for updates synchronously then set Synchronous to true before starting the update as shown below.

AutoUpdater.Synchronous=true;

If you don't want to show Skip button on Update form then just add following line with above code.

AutoUpdater.ShowSkipButton=false;

If you don't want to show Remind Later button on Update form then just add following line with above code.

AutoUpdater.ShowRemindLaterButton=false;

If you want to ignore previously set Remind Later and Skip settings then you can set Mandatory property to true. It willalso hide Skip and Remind Later button. If you set Mandatory to true in code then value of Mandatory in your XML filewill be ignored.

AutoUpdater.Mandatory=true;

You can enable forced updates by setting Mandatory property to true and setting UpdateMode to value ofMode.ForcedorMode.ForcedDownload.Mode.Forced option will hide Remind Later, Skip and Close buttons on the standard updatedialog.Mode.ForcedDownload option will skip the standard update dialog and start downloading and updating theapplication without user interaction.Mode.ForceDownload option will also ignore value of OpenDownloadPage flag.

AutoUpdater.Mandatory=true;AutoUpdater.UpdateMode=Mode.Forced;

You can provide Basic Authentication for XML, Update file and Change Log as shown in below code.

BasicAuthenticationbasicAuthentication=newBasicAuthentication("myUserName","myPassword");AutoUpdater.BasicAuthXML=AutoUpdater.BasicAuthDownload=AutoUpdater.BasicAuthChangeLog=basicAuthentication;

Set the User-Agent string to be used for HTTP web requests so you can differentiate them in your web server requestlogs.

AutoUpdater.HttpUserAgent="AutoUpdater";

You can turn on error reporting by adding below code. If you do this AutoUpdater.NET will show error message, if thereis no update available or if it can't get to the XML file from web server.

AutoUpdater.ReportErrors=true;

If your application doesn't need administrator privileges to replace old version then you can set RunUpdateAsAdmin tofalse.

AutoUpdater.RunUpdateAsAdmin=false;

If you don't want to download the latest version of the application and just want to open the URL between url tags ofyour XML file then you need to add following line with above code.

AutoUpdater.OpenDownloadPage=true;

This kind of scenario is useful if you want to show some information to users before they download the latest version ofan application.

If you don't want users to select Remind Later time when they press the Remind Later button of update dialog then youneed to add following lines with above code.

AutoUpdater.LetUserSelectRemindLater=false;AutoUpdater.RemindLaterTimeSpan=RemindLaterFormat.Days;AutoUpdater.RemindLaterAt=2;

In above example when user press Remind Later button of update dialog, It will remind user for update after 2 days.

If your XML and Update file can only be used from certain Proxy Server then you can use following settings to tellAutoUpdater.NET to use that proxy. Currently, if your Changelog URL is also restricted to Proxy server then you shouldomit changelog tag from XML file cause it is not supported using Proxy Server.

varproxy=newWebProxy("ProxyIP:ProxyPort",true){Credentials=newNetworkCredential("ProxyUserName","ProxyPassword")};AutoUpdater.Proxy=proxy;

You can specify where you want to download the update file by assigning DownloadPath field as shown below. It will beused for ZipExtractor too.

AutoUpdater.DownloadPath=Application.StartupPath;

If you are using a zip file as an update file then you can set the "InstallationPath" equal to the path where your appis installed. This is only necessary when your installation directory differs from your executable path.

varcurrentDirectory=newDirectoryInfo(Application.StartupPath);if(currentDirectory.Parent!=null){AutoUpdater.InstallationPath=currentDirectory.Parent.FullName;}

If you are using a zip file as an update file, then you can set "ExecutablePath" equal to a new executable path relativeto the installation directory. This is only necessary if your new executable path differs from current executable path.The "executable" value defined in XML takes precedence over this value.

AutoUpdater.ExecutablePath="bin/AutoUpdater.exe";

Sometimes it is necessary to clear previous version files before doing an update. In this case, you can specify whetherto clear the application directory before extracting the update file using the below code.

AutoUpdater.ClearAppDirectory=true;

You can specify the size of the update form by using below code.

AutoUpdater.UpdateFormSize=newSystem.Drawing.Size(800,600);

You can change the icon of the update form by using below code. It assumes that you have an image resource named Icon inyour project. Size of icon file should be 64x64.

AutoUpdater.Icon=Resources.Icon;

To ensure the dialogs showed by the auto updater are visible and always focussed correctly related to an applicationForm or Window, it may be necessary to set an owner. You can assign a Form or WPF Window as the owner by following theexample below.

AutoUpdater.SetOwner(yourMainFormOrWpfWindow);

To ensure that the dialogs displayed by the auto updater are always on top, you can set the "TopMost" to true, asdemonstrated in the code snippet below.

AutoUpdater.TopMost=true;

You can change how AutoUpdater.NET saves the Remind Later and Skip values by assigning the PersistenceProvider. If youdon't provide a PersistenceProvider then it will save the values in Windows registry.

If you are using .NET 4.0 or above then you can use JsonFilePersistenceProvider instead of defaultRegistryPersistenceProvider as shown below.

stringjsonPath=Path.Combine(Environment.CurrentDirectory,"settings.json");AutoUpdater.PersistenceProvider=newJsonFilePersistenceProvider(jsonPath);

You can create your own PersistenceProvider byimplementingIPersistenceProviderinterface.

You can call Start method inside Timer to check for updates frequently.

System.Timers.Timertimer=newSystem.Timers.Timer{Interval=2*60*1000,SynchronizingObject=this};timer.Elapsed+=delegate{AutoUpdater.Start("https://rbsoft.org/updates/AutoUpdaterTest.xml");};timer.Start();

DispatcherTimertimer=newDispatcherTimer{Interval=TimeSpan.FromMinutes(2)};timer.Tick+=delegate{AutoUpdater.Start("https://rbsoft.org/updates/AutoUpdaterTestWPF.xml");};timer.Start();

If you like to handle Application exit logic yourself then you can use ApplicationExitEvent like below. This is veryuseful if you like to do something before closing the application.

AutoUpdater.ApplicationExitEvent+=AutoUpdater_ApplicationExitEvent;privatevoidAutoUpdater_ApplicationExitEvent(){Text=@"Closing application...";Thread.Sleep(5000);Application.Exit();}

Sometimes as a developer you need to maintain look and feel for the entire application similarly or you just need to dosomething before update. In this type of scenarios you can handle the updates manually by subscribing to an event. Youcan do it by adding following line with above code.

AutoUpdater.CheckForUpdateEvent+=AutoUpdaterOnCheckForUpdateEvent;privatevoidAutoUpdaterOnCheckForUpdateEvent(UpdateInfoEventArgsargs){if(args.Error==null){if(args.IsUpdateAvailable){DialogResultdialogResult;if(args.Mandatory.Value){dialogResult=MessageBox.Show($@"There is new version{args.CurrentVersion} available. You are using version{args.InstalledVersion}. This is required update. Press Ok to begin updating the application.",@"Update Available",MessageBoxButtons.OK,MessageBoxIcon.Information);}else{dialogResult=MessageBox.Show($@"There is new version{args.CurrentVersion} available. You are using version{args.InstalledVersion                            }. Do you want to update the application now?",@"Update Available",MessageBoxButtons.YesNo,MessageBoxIcon.Information);}// Uncomment the following line if you want to show standard update dialog instead.// AutoUpdater.ShowUpdateForm(args);if(dialogResult.Equals(DialogResult.Yes)||dialogResult.Equals(DialogResult.OK)){try{if(AutoUpdater.DownloadUpdate(args)){Application.Exit();}}catch(Exceptionexception){MessageBox.Show(exception.Message,exception.GetType().ToString(),MessageBoxButtons.OK,MessageBoxIcon.Error);}}}else{MessageBox.Show(@"There is no update available please try again later.",@"No update available",MessageBoxButtons.OK,MessageBoxIcon.Information);}}else{if(args.ErrorisWebException){MessageBox.Show(@"There is a problem reaching update server. Please check your internet connection and try again later.",@"Update Check Failed",MessageBoxButtons.OK,MessageBoxIcon.Error);}else{MessageBox.Show(args.Error.Message,args.Error.GetType().ToString(),MessageBoxButtons.OK,MessageBoxIcon.Error);}}}

When you do this it will execute the code in above event when AutoUpdater.Start method is called instead of showing theupdate dialog.

• IsUpdateAvailable (bool) : If update is available then returns true otherwise false.
• DownloadURL (string) : Download URL of the update file..
• ChangelogURL (string) : URL of the webpage specifying changes in the new update.
• CurrentVersion (Version) : Newest version of the application available to download.
• InstalledVersion (Version) : Version of the application currently installed on the user's PC.
• Mandatory (Mandatory) : Shows if the update is required or optional.

If you want to use other format instead of XML as an AppCast file then you need to handle the parsing logic bysubscribing to ParseUpdateInfoEvent. You can do it as follows.

AutoUpdater.ParseUpdateInfoEvent+=AutoUpdaterOnParseUpdateInfoEvent;AutoUpdater.Start("https://rbsoft.org/updates/AutoUpdaterTest.json");privatevoidAutoUpdaterOnParseUpdateInfoEvent(ParseUpdateInfoEventArgsargs){dynamicjson=JsonConvert.DeserializeObject(args.RemoteData);args.UpdateInfo=newUpdateInfoEventArgs{CurrentVersion=json.version,ChangelogURL=json.changelog,DownloadURL=json.url,Mandatory=newMandatory{Value=json.mandatory.value,UpdateMode=json.mandatory.mode,MinimumVersion=json.mandatory.minVersion},CheckSum=newCheckSum{Value=json.checksum.value,HashingAlgorithm=json.checksum.hashingAlgorithm}};}

{"version":"2.0.0.0","url":"https://rbsoft.org/downloads/AutoUpdaterTest.zip","changelog":"https://github.com/ravibpatel/AutoUpdater.NET/releases","mandatory":{"value":true,"minVersion":"2.0.0.0","mode":1   },"checksum":{"value":"E5F59E50FC91A9E52634FFCB11F32BD37FE0E2F1","hashingAlgorithm":"SHA1"   }}

You can follow below steps to build the project on your local development environment.

• Disable signing from project properties of both AutoUpdater.NET and ZipExtractor.

• Edit both .csproj file of AutoUpdater.NET and ZipExtractor and change following line. Use .NET version you prefer.

  Before

  <TargetFrameworks>net462;netcoreapp3.1;net5.0-windows</TargetFrameworks>

  After

  <TargetFramework>net5.0-windows</TargetFramework>

• Build ZipExtractor project in "Release" configuration to create the executable in Resources folder. While compiling itfor .NET Core 3.1 or above, you have to use publish command instead of build asshownhereand copy the resulting executable to "AutoUpdater.NET/Resources" folder.

• Visual Studio 2022 doesn't allow building .NET Framework 4.5 by default, so if you are using Visual Studio 2022 thenyou can just change it to any supported .NET version, or you have to follow stepsfromhere to use .NET Framework 4.5.