Basic Setup

WinSparkle uses Appcast Feeds to get information about available updates.

Once you have a working appcast feed, follow the steps below to integrate WinSparkle in your app.

Native C/C++ applications

1. Add WinSparkle library

WinSparkle is distributed as single self-contained DLL, WinSparkle.dll, with no additional dependencies (even the C runtime is linked in statically). Its native API is written in pure C to achieve maximum compatibility with all Windows compilers. In order to use the library, you have to include its header:

#include <winsparkle.h>

If your compiler is Visual C++, then this is all you have to do, the compiler will pick WinSparkle.lib import library up automatically (assuming it's on linker search path). With other compilers, you'll have to create import library for the DLL and add it to linker's libraries list.

2. Set up application metadata

Similarly to its Mac counterpart, WinSparkle uses application metadata for information about app’s current version, name etc. In the Windows world, this information is stored in VERSIONINFO resources. In particular, following StringFileInfo fields are of interest and should be set to correct values:

• ProductName
• ProductVersion
• CompanyName

The psdk example included with WinSparkle has an example resource file.

Alternatively, you can provide all this information via explicit API calls.

3. Initialize WinSparkle

Your app must call win_sparkle_init() somewhere to initialize WinSparkle and perform the check. The best place to do it is as soon after startup as possible, but no sooner than the app's main window is shown. WinSparkle may show its UI soon after this call, so it’s important that the user can immediately associate its updates popup window with your app.

Before calling win_sparkle_init(), you must set the appcast URL with win_sparkle_set_appcast_url():

// Initialize WinSparkle as soon as the app itself is initialized, right
// before entering the event loop:
win_sparkle_set_appcast_url("https://winsparkle.org/example/appcast.xml");
win_sparkle_init();

Finally, you should shut WinSparkle down cleanly when the app exits:

win_sparkle_cleanup();

Managed code / .NET / C# applications

The mechanism for use with managed code applications is approximately the same:

1. Add a reference to WinSparkle

In your project, add a reference to the WinSparkle DLL. Don't forget that you might want to place it in your project's bin/debug and bin/release directories. Remember to include it as one of the copied files if you're building a setup/deployment project.

2. Create a wrapper for the WinSparkle methods you are going to call

// this is WinSparkle.cs, wrapper code for calling the native WinSparkle DLL
using System;

namespace WindowsFormsApplication1 // YOUR NAMESPACE CAN GO HERE
{
    using System;
    using System.Runtime.InteropServices;

    class WinSparkle
    {        
            // Note that some of these functions are not implemented by WinSparkle YET.
            [DllImport("WinSparkle.dll", CallingConvention=CallingConvention.Cdecl)]
            public static extern void win_sparkle_init();
            [DllImport("WinSparkle.dll", CallingConvention=CallingConvention.Cdecl)]
            public static extern void win_sparkle_cleanup();
            [DllImport("WinSparkle.dll", CharSet=CharSet.Ansi, CallingConvention=CallingConvention.Cdecl)]
            public static extern void win_sparkle_set_appcast_url(String url);
            [DllImport("WinSparkle.dll", CharSet=CharSet.Unicode, CallingConvention=CallingConvention.Cdecl)]
            public static extern void win_sparkle_set_app_details(String company_name,
                                                 String app_name,
                                                 String app_version);
            [DllImport("WinSparkle.dll", CharSet=CharSet.Ansi, CallingConvention=CallingConvention.Cdecl)]
            public static extern void win_sparkle_set_registry_path(String path);
            [DllImport("WinSparkle.dll", CallingConvention=CallingConvention.Cdecl)]
            public static extern void win_sparkle_check_update_with_ui();
    }
}

(Note that this code cannot be compiled with the /clr:pure flag, check Project Properties -> General -> Common Language Runtime Support.)

3. Add code to your .Net application to call WinSparkle functions

 // ... this is an EXCERPT from Form1.cs, showing !WinSparkle functions being called from our main form
    public Form1()
    {
        InitializeComponent();
        WinSparkle.win_sparkle_set_appcast_url("https://<your domain>/<your path to your>/appdescriptor.rss");
        //WinSparkle.win_sparkle_set_app_details("Company","App", "Version"); // THIS CALL NOT IMPLEMENTED YET
        //start automatic update checks.
        WinSparkle.win_sparkle_init();
    }

    // ... more code would go here like a click handler
    private void Form1_button1_click(object sender, EventArgs e)
    {
        //invoke manual update check from button or menu click.
        WinSparkle.win_sparkle_check_update_with_ui();
    }

    // ... somewhere as  you leave your app like the window closed handler
    private void Form1_Closed(object sender, EventArgs e)
    {
        //stop automatic update checks. Release native resources.
        WinSparkle.win_sparkle_cleanup();
    }
            

Setting VERSIONINFO resources

It seems like a semi-arduous process to add Win32-type resources to a C# .exe (A comprehensive example with VS08 and VS10 would be welcome), but you really don't have to: The AssemblyInfo.cs file in your project contains the FileVersion in this line:

[assembly: AssemblyFileVersion("1.0.7.0")]

Change that line to be whatever you'd like it to be, remembering that it's going to be used in the comparison by WinSparkle.

Note that when running your application under the debugger, the name of the application displayed in the WinSparkle dialog will be whatever version of your development environment you are using (this must be picked up from VSHosts.exe?). When run not-under-debugger, the name will be the name of your application.