Blogs

(Re-)Start Me Up ...

  • Comments 2
  • Likes
As I mentioned in a recent post, I'm currently working on a Windows Vista workshop. As part of that, I've created a simple application that demonstrates the basic interaction of the Windows Installer with Vista's new Restart Manager (RM). I thought I'd post some information on how easy this was to do, which you might find useful for your own applications and packages.

My sample application is a basic text editor that uses a multi-line edit control to allow the user to write short notes:

Screenshot 1: RMtestX - not Restart Manager aware

There are two version of the application, RMtestX (non Restart Manager aware, used for screenshots 1-3) and RMtestV (Restart Manager aware). If RMtestX were to crash, you'd see something like this:

Screenshot 2: RMtestX crashes

So, the user can close the application or debug it, which is not any better than Windows XP offers. Generally, the user doesn't want to do either. They just want to carry on with their work. Similarly, if a patch is applied when the application is running, they have two equally unappealing option:

Screenshot 3: RMtestX is being patched.

If they want to update to happen, then the user can either manually save data, close the application, complete the update, restart the application, then open the saved data, or opt for a full system reboot. Neither option is ideal.

So, how can we use Restart Manager to improve things?

Becoming Restart Manager Aware
Firstly, before the application can interact with the RM, it needs to register itself using the RegisterApplicationRestart API. Doing this is extremely simple:

// register with Restart Manager
RegisterApplicationRestart(L"-rm", 0);
For RMtestV, I call the API just after the main window is created and just before jumping into the message loop, though you could call it elsewhere - doing it early makes sense since your application can't know when it might be called upon to restart. The "-rm" switch is an arbitrary command line that the RM passes to the application if it's been restarted. You can make this more or less anything you like. The idea is that the application can tell from this that it was restarted and can respond appropriately. In the case of RMtestV, this check is performed when the WM_CREATE message is received:

case WM_CREATE:
   //
   // some initialisation stuff
   //

   // check to see if RM called us
   if(RMstart())
   {
      RestoreText(GetDlgItem(hWnd, IDC_EDIT1));
      MessageBox(hWnd, L"RMtestV was restarted by the Restart Manager", L"RMtestV: Restart Alert", MB_OK|MB_ICONEXCLAMATION);
   }

   return 0;
RMstart() uses the GetCommandLine and CommandLineToArgvW APIs to check if RMtestV was called with "-rm". If it was, then the RestoreText() call restores the contents of the EDIT control saved during shutdown (as mentioned below). Alerting the user to what just happened isn't mandatory, of course, but is probably a good idea. Restart Manger adds entries like this to the Application Event Log:

Event ID: 10002
Source: Restart Manager
Type: Information
Description: Shutting down application or service 'Restart Manager Example: RM Compliant'.


Event ID: 10003
Source: Restart Manager
Type: Information
Description: Restarting application or service 'Restart Manager Example: RM Compliant'.

To make this automated stopping and starting more useful, RMtestV needs to be able to save any text the user has entered before it shuts down. When the RM is wanting to restart an application, it sends two window messages in order, which the application needs to process, WM_QUERYENDSESSION and WM_ENDSESSION:

case WM_QUERYENDSESSION:
   // no need to do anything special here
   // but must return "1" if the application is ready to restart
   return 1;

You can perform some clean up work when handling WM_QUERYENDSESSION, but the application has to respond quickly at this point, so it is better to delay this work until handling WM_ENDSESSION. In particular, it is a bad idea to prompt for user input in response to WM_QUERYENDSESSION.  If your application can't restart, say because it is doing work that can't be interrupted, return "0". 

Next comes the notification that the session is ending:

case WM_ENDSESSION:
   if(ENDSESSION_CLOSEAPP & lParam)
   {
      SaveText(GetDlgItem(hWnd, IDC_EDIT1));
   }
   return 0;
If the application is being asked to restart due to file replacement during patching, the ENDSESSION_CLOSEAPP flag is passed to the application. RMtestV responds to this flag by saving the current contents of the EDIT control in a temp file using the user-defined SaveText() function.

So, now the application is ready to respond to the Restart Manager. For example, if RMtestV crashes now, the user sees this:

Screenshot 4: Restart Manager Prompt

To make things a lot smoother, RMtestV should regularly save the user's data to a temporary location, so that if the user selects "Restart the program", RMtestV will close and re-open with the data restored with minimum interruption. As I was mainly interested in the Windows Installer interaction, I didn't implement this, but it would be a simple matter to use the SetTimer API to trigger a call to SaveText() or similar on a regular basis.

Before looking at how Windows Installer makes use of this, two important points to note about the above are:
  • Adding Restart Manager functionality to your application is not hugely complicated
  • You need to do all of the important work of saving/restoring any data, configuration settings, etc.

 

Interacting With the Windows Installer
As mentioned above, prior to Windows Vista, any attempt to patch files held open by an application would fail. The best you could get was to prompt the user to manually close the application (and re-open it themselves later), or to require a system reboot. Once an application is RM aware, we need to author the MSI package correctly to take advantage of it. The outline of what needs done is as follows:

Dialog Table
You need to define the MsiRMFilesInUse dialog. This is very similar to the existing FilesInUse dialog, but it allows the user to select an automatic restart of the application using Restart Manager.

Dialog HCentering VCentering Width Height Attributes Title Control_First Control_Default Control_Cancel
MsiRMFilesInUse 50 50 374 266 19 [ProductName] PushButton1 PushButton1 PushButton2


Control Table
The controls used on the MsiRMFilesInUse dialog are defined as follows:

Dialog_ Control Type X Y Width Height Attributes Property Text Control_Next Help
MsiRMFilesInUse DlgLine Line 0 234 375 0 1        
MsiRMFilesInUse Banner Bitmap 0 0 374 44 1   [BannerBitmap]    
MsiRMFilesInUse DlgDesc Text 21 23 292 25 65539   Some files that need to be updated are currently in use.    
MsiRMFilesInUse DlgTitle Text 13 6 292 25 65539   {&MSSansBold8}Files in Use    
MsiRMFilesInUse DlgText Text 21 49 348 17 3   The following applications are using files that need to be updated by this setup.    
MsiRMFilesInUse BannerLine Line 0 44 374 0 1        
MsiRMFilesInUse RadioButtonGroup1 RadioButtonGroup 19 187 343 40 16777219 ShutdownOption   List  
MsiRMFilesInUse List ListBox 21 66 331 118 7 FileInUseProcess   PushButton1  
MsiRMFilesInUse PushButton1 PushButton 228 244 66 17 3   OK PushButton2  
MsiRMFilesInUse PushButton2 PushButton 299 244 66 17 3   Cancel RadioButtonGroup1  


ControlEvent Table
Once the controls are defined, we need to define what actions they trigger when used:

Dialog_ Control_ Event Argument Condition Ordering
MsiRMFilesInUse PushButton1 EndDialog Return 1 1
MsiRMFilesInUse PushButton1 RMShutdownAndRestart 0 ShutdownOption=1 2
MsiRMFilesInUse PushButton2 EndDialog Exit 1 1


RadioButton Table
We use a pair of radio buttons to alow the user to choose between using restart manager and going for an old-style post-boot replacement:

Property Order Value X Y Width Height Text Help
ShutdownOption 1 1 6 9 331 14 Automatically close all applications and attempt to restart them after setup is complete.  
ShutdownOption 2 2 6 21 322 17 Do not close applications. (A reboot will be required.)  


Property Table
A property is used to determine which of the radio buttons the user has selected:

Property Value
ShutdownOption 1

I've exported examples of these tables as IDT files, which you can import into your packages using ORCA:

MsiRMFilesInUse Related Tables

Once this is in place, the user will see different options when patching while the application is in use:

Screenshot 5: MsiRMFilesInUse dialog 

Further Reading
The above isn't everything the Restart Manager has to offer. For example, you can call on it to give you a list of processes holding a given file open, then (if the applications are registered), ask for them to be restarted - essentially what the Windows Installer does behind the scenes. Get more information here:

Restart Manager Documentation
Application Recovery and Restart Documentation
Using Windows Installer with Restart Manager
Windows Installer Team Discussion on Restart Manager

Comments
  • Richard Macdonald of the Windows Installer team at Microsoft has posted another great blog article in

  • On the The OEM Ready Program page, OEM’s can download the OEM Ready Program Test Cases for Windows Vista

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment