Desktop Functions:

   Smart Device Functions:

Show Recent Changes
Subscribe (RSS)
Misc. Pages
Helpful Tools
Suggested Reading
Website TODO List
Download Visual Studio Add-In

SHMessageBoxCheck (shlwapi)
Displays a message box with a "Never show this dialog again" check box. This dialog is useful for displaying a one-time message to the user where they are likely never to want to see the dialog again.

C# Signature:

/* The SHMessageBoxCheck() function is a Windows Shell API function that displays a custom messagebox with a "never ask me again" check box.  When the user checks the checkbox, the dialog never shows up again.  The shell API .dll exports this function by ordinal only.  The entrypoint  is ordinal 185 for ASCII and 191 for unicode. */

[DllImport("shlwapi.dll", EntryPoint="#185", ExactSpelling=true, PreserveSig=false)]
public static extern int SHMessageBoxCheck(
    [In] IntPtr hwnd,
    [In] String pszText,
    [In] String pszTitle,
    [In] MessageBoxCheckFlags uType,
    [In] int iDefault,
    [In] string pszRegVal

VB Signature:

Declare Function SHMessageBoxCheck Lib "shlwapi.dll" (TODO) As TODO

User-Defined Types:


Alternative Managed API:

I had to set PreserveSig=true in order to get this to work. Without it, I would receive a PInvokeStackImbalance exception from MDA.


/* We use the Windows Shell function SHMessageBoxCheck, so we have to define this parallel enum of the definitions in winuser.h. */

public enum MessageBoxCheckFlags : uint
    MB_OK             = 0x00000000,
    MB_OKCANCEL           = 0x00000001,
    MB_YESNO          = 0x00000004,
    MB_ICONHAND           = 0x00000010,
    MB_ICONQUESTION       = 0x00000020,
    MB_ICONEXCLAMATION    = 0x00000030,
    MB_ICONINFORMATION    = 0x00000040

The Windows Shell (Explorer) stores your preference in the following registry key:


The problem of leaving behind the registry keys: Since the registry key gets stored in HKEY_CURRENT_USER, every different user on a system will have their own preference saved. If you uninstall the program for one user, you'll leave behind the registry keys for the other users. For example, suppose users X and Y have checked the "Do not show me this dialog again" checkbox, and therefore each have the registry key in their HKEY_CURRENT_USER area. Now user X uninstalls the program. The uninstaller must leave behind the registry key for user Y because that user is not logged in.

Raymond Chen, a popular Microsoft blogger, recommends that you not worry about leaving keys because it's per-user data anyway and in many environments it's preferable to leave it behind. Definitely do not try to enumerate all user profiles to remove the keys for the other users because in the case of roaming profiles you'll likely corrupt a lot of stuff. If you want to remove all traces of your program, one alternative is to write your own SHMessageBoxCheck dialog and store the preference wherever you want. Source:

Tips & Tricks:


Note the discussion on what to do when you have multiple dialog options, like YES/NO and OK/CANCEL.

Sample Code:

/* This code displays a dialog box with a "Don't show me this dialog again" checkbox and an OK button.  In normal circumstances, result will always be 0 on return. */

int result;

    result = SHMessageBoxCheck(
        "This text fills the dialog",
        "This text is in the title bar",
        MessageBoxCheckFlags.MB_OK | MessageBoxCheckFlags.MB_ICONINFORMATION,
        "MyApplicationName.exe" // This last argument is the value of the registry key
catch( Exception e )
// Note that the only exceptions we can get here are inter-op exceptions, I think.
    result = -1;

if( result == -1 )
// The dialog didn't show up, so do some alternate action here.


Please edit this page!

Do you have...

  • helpful tips or sample code to share for using this API in managed code?
  • corrections to the existing content?
  • variations of the signature you want to share?
  • additional languages you want to include?

Select "Edit This Page" on the right hand toolbar and edit it! Or add new pages containing supporting types needed for this API (structures, delegates, and more).

Access directly from VS:
Terms of Use
Edit This Page
Find References
Show Printable Version