Junfeng Zhang's Windows Programming Notes : Win32

Windows Performance Tools Kit

junfeng — Mon, 11 Feb 2008 19:00:40 GMT

Windows Performance Team has released Windows Performance Tools Kit to the Windows SDK for Windows Server 2008 and .NET Framework 3.5.

http://www.microsoft.com/whdc/system/sysperf/perftools.mspx

This is the same tool Windows team uses to diagnose Windows performance problem. Along with the tool comes with a 60-page Quick Start Guide. It offers significant details how the system works.

Having a performance problem lately? Fire up Xperf and look at the pretty chart.

From Unhandled Exception to Debugger Attach

junfeng — Mon, 19 Nov 2007 19:00:45 GMT

I was always wondering what is happening between an application throws an unhandled exception, and a debugger attached to the process. Apparently the information is right under my nose, but I was blind.

Windows Debugger's documentation about post-mortem debugging has all the details you want to know.

Enabling Postmortem Debugging

The most common application errors are called exceptions. These include access violations, division-by-zero errors, numerical overflows, and many other kinds of errors.

Applications can also cause breakpoint interrupts. These occur when Windows is unable to run the application (for example, when a necessary module cannot be loaded) or when a breakpoint is encountered. Breakpoints can be inserted into the code by a debugger, or invoked through a function such as DbgBreakPoint. In assembly language, a breakpoint interrupt is generated by an int 3 instruction.

Windows can handle user-mode errors in a variety of ways. The following sequence shows the precedence used for error handling:

If a user-mode debugger is currently attached to the faulting process, all errors will cause the target to break into this debugger.
As long as the user-mode debugger is attached, no other error-handling methods will be used — even if the gn (Go With Exception Not Handled) command is used.
If no user-mode debugger is attached and the executing code has its own exception handling routines (for example, try - except), this exception handling routine will attempt to deal with the error.
If no user-mode debugger is attached, and Windows has an open kernel-debugging connection, and the error is a breakpoint interrupt, Windows will attempt to contact the kernel debugger.
Kernel debugging connections must be opened during Windows' boot process. If you are using Windows Server 2003 or a later version of Windows and wish to prevent a user-mode interrupt from breaking into the kernel debugger, you can use the KDbgCtrl utility with the -du parameter. For details on how to configure kernel-debugging connections and how to use KDbgCtrl, see Configuring Software on the Target Computer.

If Windows does attempt to contact a kernel debugger but there is no debugger running at the other end of the connection, Windows will freeze until kernel debugger is activated.

In the kernel debugger, you can use gh (Go With Exception Handled) to disregard the error and continue running the target. You can use gn (Go With Exception Not Handled) to bypass the kernel debugger and go on to step 4.
If the conditions in steps 1, 2, and 3 do not apply, Windows will activate a debugging tool. Any program can be selected in advance as the tool to use in this situation. The chosen program is referred to as the postmortem debugger. This is also known as the just-in-time debugger or the JIT debugger.
If the postmortem debugger is a standard user-mode debugger (such as CDB, WinDbg, or Microsoft Visual Studio), this debugger will start up and break into your application.

If the postmortem debugger is a tool for writing dump files (such as Dr. Watson), a memory dump file will be created, and then the application will be terminated.

Note If Dr. Watson is activated on Windows XP or a later version of Windows, a message box will appear. This window gives you the option of sending an error report to Microsoft. If you choose Don't Send, a dump file will created and stored on your hard disk. If you choose Send Error Report, a dump file will be created and stored on your hard disk, and will also be transmitted to Microsoft over the internet.

If you have not reconfigured Windows' postmortem settings, Dr. Watson is used as the default postmortem debugger. This setting can be changed programmatically or through the registry; any changes take effect immediately.

To change the postmortem debugger to WinDbg, run windbg -I. (The I must be capitalized.) This command will display a success or failure message after it is used. When WinDbg is the postmortem debugger, it will be activated whenever an application crashes.
To change the postmortem debugger to CDB, run cdb -iae or cdb -iaec KeyString.. When the -iaec switch is used, KeyString specifies a string to be added to the end of the AeDebug registry key. This command will display no message if it succeeds, but will display a failure message if it fails. When CDB is the postmortem debugger, it will be activated whenever an application crashes.
To change the postmortem debugger to NTSD, run ntsd -iae or ntsd -iaec KeyString.. When the -iaec switch is used, KeyString specifies a string to be added to the end of the AeDebug registry key. If KeyString contains spaces, it must be enclosed in quotation marks. This command will display no message if it succeeds, but will display a failure message if it fails. When NTSD is the postmortem debugger, it will be activated whenever an application crashes.
To change the postmortem debugger back to Dr. Watson, run drwtsn32 -i. When Dr. Watson is the postmortem debugger, a memory dump file will be written to disk if an application crashes. See Dr. Watson Command-Line Options for details.

Only a system administrator can alter the postmortem settings.

If a postmortem debugger has been installed, you can deliberately break into the debugger from a user-mode application by calling the DebugBreak function.

Editing the Registry

The postmortem debugging settings are stored in the registry. If you wish to control these settings, it is recommended that you use the WinDbg, CDB, NTSD, or Dr. Watson commands described above; these will automatically change the relevant registry keys. If you do need to manually edit the registy, do so very carefully, since improper changes to the registry may render Windows unusable.

On an x86 computer, the postmortem settings are stored in the \\HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\AeDebug key.

On an Intel Itanium computer, there are two registry keys used for postmortem debugging:

A failing 64-bit application will be debugged according to the settings stored in the \\HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\AeDebug key.
A failing 32-bit application will be debugged according to the settings stored in the \\HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\Windows NT\CurrentVersion\AeDebug key. However, if the Debugger value in this key specifies an application in the %windir%\system32 directory, Windows will look in %windir%\syswow64 instead.

When using an Itanium computer, it is often simplest to place identical values in each of these keys. In particular, if you are using WinDbg, CDB, or NTSD as your postmortem debugger, the same version will work for 32-bit and 64-bit user-mode applications on an Itanium computer. See Choosing a 32-bit or 64-bit Debugger Package for details.

There are two registry values that should appear in these keys:

Debugger: This REG_SZ value specifies the debugger that will handle postmortem debugging. The full path to the debugger must be listed, unless the debugger is located in a directory that is in the default path.
Auto: This REG_SZ value is always either 0 or 1. If Auto is set to 0, a message box will be displayed prior to postmortem debugging.

When an unhandled application error occurs, Windows checks to see if the Debugger and Auto registry values exist.

If the Auto value is 0, a message box will appear.

In Windows NT and Windows 2000, the message box will have one of the following formats:

If the Debugger value contains the name of a valid debugger or Dr. Watson, the message box will have two buttons: OK and Cancel. If the OK button is pressed, the application will be terminated. If the Cancel button is pressed, the tool specified in the Debugger value will be started.
If the Debugger value is empty, the message box will have only an OK button and no debugger will start.

In Windows XP and later versions of Windows, the message box will have one of the following formats:

If the Debugger value contains the name of a valid debugger or Dr. Watson, the message box will have three buttons: Send Error Report, Don't Send, and Debug. If the Don't Send button is pressed, the application will be terminated. If the Send Error Report button is pressed, a minidump file will be sent to Microsoft and the application will be terminated. If the Debug button is pressed, the tool specified in the Debugger value will be started. (Note that all of these buttons have different effects than the buttons on the message window for Dr. Watson when the Auto value does not equal 0.)
If the Debugger value is empty, the message box will have only the Send Error Report and Don't Send buttons.

If the Auto value equals 1, no message box appears. The debugger referred to in the Debugger value is automatically started.

Registry Examples

The following registry values can be used to set Dr. Watson as the postmortem debugger (this is the default):

Debugger = "drwtsn32 -p %ld -e %ld -g"
Auto = 1

The following values can be used to set WinDbg as the postmortem debugger:

Debugger = "Path\WinDbg -p %ld -e %ld"
Auto = 1

The following values can be used to set CDB as the postmortem debugger:

Debugger = "Path\CDB -p %ld -e %ld -g"
Auto = 1

In these examples, Path is the directory where the debugger is located, -p %ld specifies the process ID that will be debugged, -e %ld provides the event that caused the exception, and -g causes the debugger to skip the initial breakpoint. (Dr. Watson ignores the -g option.)

Security Vulnerabilities

If you are considering enabling postmortem debugging on a computer that you share with other people, see Security During Postmortem Debugging.

Windows Vista Sxs Activation Context Cache

junfeng — Mon, 01 Oct 2007 18:00:00 GMT

Sxs activation model is built on top of Actication Context. To create an activation context, use the API CreateActCtx.

Activation Context is used very frequently in Windows. For example, a simple operation like start notepad, open the common file dialog, select a file, will call CreateActCtx many times (I measured 18 times in Vista). With the adoption of Sxs model in VC++ libraries, the usage of activation context will certainly be much higher.

However, creating an activation context is a very expensive operation. It has to resolve the full assembly binding closure, which includes probing for policies for all the assemblies, probing for each assembly, and parse each manifest. If you have read the output of sxstrace, you will certainly understand there are a lot work during CreateActCtx.

Fortunately, activation context is fairly static. Given a steady state, it is likely the same input to CreateActCtx will always create an activation context with exactly the same content. This makes it an attractively target for caching.

In Windows Vista, Sxs implements an activation context cache. The article discusses some detail of the Vista activation context cache.

1. What to cache

Only applications from local disk are cached. For applications running off network or CD, the cache has no effect.

2. Location of the cache

From this article (http://blogs.msdn.com/junfeng/archive/2007/06/12/activation-context-creation-flow.aspx) , we understand that the real work of CreateActCtx is done in CSRSS.exe. And this is where the cache is. The main reason is so that the activation context can be shared with multiple processes.

Since each session has a copy of CSRSS.exe, the cache is not shared across use login sessions.

3. Life time of the cache

The cache is only stored in memory. The first time CreateActCtx is called, it adds an entry to the cache. Next time when the same CreateActCtx is called, the result is returned from the cache immediately, saving the expensive probing and xml parsing. The cache is lost when the machine reboots.

4. size of the cache

The cache in Vista RTM has a fixed size, with a Least Recently Used (LRU) replacement algorithm. This may change in the future.

5. Cache Key

The activation context stores the parsed content of all manifests in the full assembly binding closure. Ideally, the cache key should be the path of all the manifests, and their last modified time.

However, if Sxs uses that as the key to the cache, it means Sxs will have to do all the expensive probing, parsing, which makes the cache useless.

To make a compromise, Sxs chooses the path of the entry manifest of CreateActCtx and its last modified time as the key. This means, if one of its dependent assemblies has changed, it is necessary to "touch" (i.e. change the last modified time of) the entry manifest for Sxs to see the change.

Here is an example. You may have a manifest myapp.exe.manifest depending on VC80, and you decides to deploy vc80 privately. So you have a private Microsoft.VC80.CRT.manifest. In Vista, when you change Microsoft.VC80.CRT.manifest, in order for Sxs to see the change in this manifest, you need to change the last modified time of myapp.exe.manifest.

5. WinSxs

If the dependent manifests are part of the application, this update requirement is very reasonable. However, if the assembly you depend on is in the global WinSxs store, you may not get a chance to update your manifest when the assembly in Winsxs changes.

Thus in Vista, Sxs adds a WinSxs store timestamp. Whenever a publisher policy assembly is installed to Winsxs store, Sxs updates the timestamp. The activation context cache saves the Winsxs store timestamp in the cache when the cache is created. When Sxs processes a CreateActCtx request, it checks to see if the cached Winsxs store timestamp matches the real Winsxs store timestamp. If it does not, Sxs throws out the cache, and re-creates it from scratch.

The reason that the timestamp is updated only when a publisher policy assembly is installed, is because Sxs requires a publisher policy when update an assembly in Winsxs store.

6. Disable the SxS Cache

Remember in the post DotLocal (.local) Dll Redirection, we know that for private testing, we can use registry HKLM\Software\Microsoft\WindowsNT\CurrentVersion\Image File Execution Options!DevOverrideEnable:REG_DWORD to enable DotLocal Dll redirection for applications with SxS manifest. Since disabling the SxS cache should be really for testing only, the same registry key is used to disable the SxS cache.

advantages and disadvantages of delay load (LoadLibrary)

junfeng — Wed, 01 Aug 2007 18:00:00 GMT

Some knowledgeable people posted the following wisdom about delay load. Archived here to share.

The advantages are that dlls get loaded only when they are used, and you can “statically” bind to an import that may not exist at runtime, and as long as you are careful not to call it, the program will still work downlevel.

The disadvantage is:

1) Some DLLs don’t work DelayLoaded (as mentioned in the limitations of LoadLibrary). In particular, any dll that uses __declspec(thread), or any dll that you want to import data from.

2) You can’t call any API that might be delay loaded in your DllMain (since you can’t call LoadLibrary during DllMain). Probably not a big deal since you’re generally not supposed to call any APIs in DllMain.

3) The DLLs in your process are now initialized in random order. There may be some orders that cause bizarre bugs.

4) In particular, if you “statically” bind to a dll, then your dll is uninitialized before that other dll. If you delayload, then you will be uninitialized after your delayloaded dlls.

5) Since DLLs may be loaded “late”, their preferred base address may be used already by stack or heap data, resulting in a rebasing performance penalty that wouldn’t happen if the Dll was loaded at boot.

6) If the LoadLibrary fails for some reason (at the delay loading site), then your program just crashes. You can catch this exception, but it is difficult to recover from and definitely the API callsite that was expecting to make a call into this delayed dll will have no direct way of detecting failures.

The last one is the biggest burden. It can mean random crashes when your app is under stress (because you’re out of memory to load that DLL). Unless your feature is specifically designed to deal with that DLL not loading (and you’d have to put this code around every place where you call a delayed API), you run this random crash risk.

Delay Loading definitely has its uses and its benefits, but the limitations means it is not correct to blindly delayload everything.

RT_MANIFEST resource, and ISOLATION_AWARE_ENABLED

junfeng — Tue, 26 Jun 2007 18:00:00 GMT

RT_MANIFEST

Since Windows XP, Windows reserves a new type of resource RT_MANIFEST for SxS manifests.

Within the RT_MANIFEST resource, Windows reserves ID 1-16. A binary cannot have two IDs of resource type RT_MANIFEST within 1-16. Windows will refuse to load such binary in Windows XP/Windows Server 2003.

Only three IDs are used today in Windows.

excerpt from Winuser.h

#define RT_MANIFEST MAKEINTRESOURCE(24)
#define CREATEPROCESS_MANIFEST_RESOURCE_ID MAKEINTRESOURCE( 1)
#define ISOLATIONAWARE_MANIFEST_RESOURCE_ID MAKEINTRESOURCE(2)
#define ISOLATIONAWARE_NOSTATICIMPORT_MANIFEST_RESOURCE_ID MAKEINTRESOURCE(3)
#define MINIMUM_RESERVED_MANIFEST_RESOURCE_ID MAKEINTRESOURCE( 1 /*inclusive*/)
#define MAXIMUM_RESERVED_MANIFEST_RESOURCE_ID MAKEINTRESOURCE(16 /*inclusive*/)

CREATEPROCESS_MANIFEST_RESOURCE_ID

CREATEPROCESS_MANIFEST_RESOURCE_ID is used primarily for EXEs. If an executable has a resource of type RT_MANIFEST, ID CREATEPROCESS_MANIFEST_RESOURCE_ID, Windows will create a process default activation context for the process. The process default activation context will be used by all components running in the process.

CREATEPROCESS_MANIFEST_RESOURCE_ID can also used by DLLs. When Windows probe for dependencies, if the dll has a resource of type RT_MANIFEST, ID CREATEPROCESS_MANIFEST_RESOURCE_ID, Windows will use that manifest as the dependency.

ISOLATIONAWARE_MANIFEST_RESOURCE_ID

ISOLATIONAWARE_MANIFEST_RESOURCE_ID is used primarily for DLLs. It should be used if the dll wants private dependencies other than the process default. For example, if an dll depends on comctl32.dll version 6.0.0.0. It should have a resource of type RT_MANIFEST, ID ISOLATIONAWARE_MANIFEST_RESOURCE_ID to depend on comctl32.dll version 6.0.0.0, so that even if the process executable wants comctl32.dll version 5.1, the dll itself will still use the right version of comctl32.dll.

When LoadLibrary is called, before loading the dependencies of the dll, the NT library loader checks to see if the dll has a resource of type RT_MANIFEST, ID ISOLATIONAWARE_MANIFEST_RESOURCE_ID. If it does, the loader calls CreateActCtx with the resource, and use the generated activation context to probe the dll's static dependencies. This is reason why the dll can have private dependencies with the ISOLATIONAWARE_MANIFEST_RESOURCE_ID resource.

The activation context created during LoadLibrary is stored in the loader data structure tracking the dll.

Normally this activation context is used only during LoadLibrary, for the dll's static dependencies.

Sometimes, you want to use the activation context outside of probing the dll's static dependencies. You can define macro ISOLATION_AWARE_ENABLED when you compile the module.

ISOLATION_AWARE_ENABLED

When ISOLATION_AWARE_ENABLED is defined, Windows re-defines certain APIs. For example LoadLibraryExW is redefined to IsolationAwareLoadLibraryExW.

When IsolationAwareLoadLibraryExW is first called, it tries to retrieve the activation context stored in the loader data structure when the calling library is loaded. If the library does not have such activation context (for example, the library does not have a manifest of id ISOLATIONAWARE_MANIFEST_RESOURCE_ID), IsolationAwareLoadLibraryExW tries to create a new activation context with the calling library with id ISOLATIONAWARE_NOSTATICIMPORT_MANIFEST_RESOURCE_ID MAKEINTRESOURCE. If the creation fails, IsolationAwareLoadLibraryExW will use the process default activation context.

Once the activation context is determined, IsolationAwareLoadLibraryExW will call ActivateActCtx on the activation context, call the real API (LoadLibraryExW), and on return, it calls DeactivationActCtx. This way, the correct activation context is automatically used.

Not all APIs affected by activation context are wrapped. For example, GetModuleHandleEx is not wrapped, and neither is any of the COM APIs. For a complete list of APIs wrapped by ISOLATION_AWARE_ENABLED, check your copy of Windows SDK.

C:\Program Files\Microsoft SDKs\Windows\v6.0\Include>dir *.inl
Volume in drive C has no label.
Volume Serial Number is ECD1-6DB0

Directory of C:\Program Files\Microsoft SDKs\Windows\v6.0\Include

10/30/2006 01:44 AM           159,222 commctrl.inl
10/30/2006 01:44 AM            32,836 commdlg.inl
10/30/2006 01:44 AM            12,065 prsht.inl
10/30/2006 01:44 AM            23,430 WinBase.Inl
10/30/2006 01:44 AM            36,308 WinUser.Inl

If the APIs you use are not wrapped by ISOLATION_AWARE_ENABLED, you have to do the activation/deactivation yourself properly. You can use the C++ helper class described in MSDN http://msdn2.microsoft.com/en-us/library/aa375197.aspx.

For more information, please see MSDN section about Sxs Isolated Applications and Side-by-side Assemblies.

Diagnose SideBySide failures in Windows XP/Windows Server 2003

junfeng — Tue, 12 Jun 2007 22:00:00 GMT

Since I published my article on how to diagnose SideBySide failures, I have received many feedbacks that since Sxstrace is not available in Windows XP/Windows Server 2003, it is hard to figure out what is wrong in Windows XP/Windows Server 2003.

This article intends to help people diagnose SideBySide failures in Windows XP/Windows Server 2003.

SideBySide failures usually results in error code Win32 error ERROR_SXS_CANT_GEN_ACTCTX (or HRESULT 0x800736B1), or ntstatus code STATUS_SXS_CANT_GEN_ACTCTX (0xc0150002). You may see it when launching a process with Sxs manifest, or loading a dll with sxs manifest.

From this article, we learned that the real work is done by CSRSS.exe.

Since most of the work in Creating Activation Context is probing, we can use the sysinternals tool FileMon.exe to understand what is going on.

Let's run an example.

I am running on Windows Server 2003.

F:\tools>ver

Microsoft Windows [Version 5.2.3790]

There is a tool CoCreate.exe. It has a Sxs manifest depends on common control.

F:\tools>more cocreate.exe.manifest
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
    <assemblyIdentity
        name="CoCreate"
        version="1.0.0.0"
        />

</assembly>

Unfortunately it says it depends on common control version 6.1.0.0, which does not exist anywhere currently.

Let's run the tool anyway.

F:\tools>cocreate
The system cannot execute the specified program.

Just as expected, the tool refuses to run.

Let's look at what event log tells us.

The message is accurate. But it is not really helpful here. What referenced assembly is not installed on my system?

Let's see if Filemon can help us here or not.

Launch filemon, and set the filter to CSRSS, as we want to monitor file access from the process CSRSS.exe.

Re-run CoCreate.exe. Now we have this in FileMon:

Ok. CSRSS.exe did a lot probing for Microsoft.Windows.Common-Controls_6595b64144ccf1df_6.1.0.0.xxx. Given that CoCreate.exe.manifest says it depends on common control version 6.1.0.0, it is pretty clear that the missing referenced assembly is common control version 6.1.0.0.

Warning!!! Please do not attempt to copy files to the Winsxs directories shown in filemon output to workaround the Sxs activation context creation problem. Sxs keeps other metadata about the assembly besides the files in %windir%\Winsxs. Please always use the documented way to install Sxs assemblies.

Activation Context Creation flow

junfeng — Tue, 12 Jun 2007 18:00:10 GMT

The following describes how activation context is created currently in Windows XP/Windows Server 2003/Windows Vista.

1. CreateProcess/CreateActCtx is called.

2. CreateProcess/CreateActCtx does some validation, constructs a message, sends the message to CSRSS.exe, and waits for CSRSS.exe to return.

3. CSRSS.exe receives the message, and creates the activation context as described in http://blogs.msdn.com/junfeng/archive/2006/04/22/580482.aspx.

4. Once the activation context is created, CSRSS returns it to the client.

5. CreateProcess/CreateActCtx proceeds.

The getaway from the flow above is: most work is done in CSRSS.exe.

Genman32 – A tool to generate Sxs manifest for managed assembly for Registration Free COM/.Net Interop

junfeng — Sat, 14 Apr 2007 18:00:00 GMT

Attached to this article is GenMan32, a tool to generate sxs manifest for managed assembly to use in registration free COM/.Net Interop scenario.

(For more information about registration free COM/.Net interop, please read http://blogs.msdn.com/junfeng/archive/2006/05/17/595140.aspx.)

GenMan32 uses reflection API to enumerate all the types in the assembly. For each type, if it requires registration (as determined by System.Runtime.InteropServices.RegistrationServices.TypeRequiresRegistraton), depending on what kind of type it is, the tool generates either a clrClass element, or a clrSurrogate element.

For most basic scenarios, the sxs manifest generated by the tool is sufficient. For more complex scenarios, we may have to edit the generated manifest file before add the manifest to the assembly.

Here is the usage of the tool.

D:\tools>genman32

Microsoft (R) .NET Framework Win32 Manifest File Generation Utility 2.0.60120.0

Syntax: GenMan32 AssemblyName [Options]

Options:

/add Add manifest file to the assembly as a resource.

If /manifest option is provided, use the filename a

s input.

Otherwise generate one from the assembly.

/remove Remove an embedded manifest from the assembly.

/replace Replace embedded manifest with new manifest.

New manifest is specified by /manifest option.

/manifest:filename Specify the manifest file to add or replace.

Used together with option /add or /replace.

/typelib Generate typelib and record all the interfaces in

manifest. This option cannot be used with interop

assemblies.

/reference:filename Specify the dependency of the assembly. To specify

multiple dependencies, specify the /reference optio

n multiple time.

/asmpath:directory Look for assembly references here.

/out:filename Generate manifest. If filename is omitted, the

manifest is generated as AssemblyName.manifest.

/nologo Prevents GenMan32 from displaying logo.

/silent Silent mode. Success messages not displayed.

/? or /help Display this usage message.

We can use the tool to generate a Sxs manifest for managed assembly.

D:\tools>more testlib.cs

using System;

using System.Runtime.InteropServices;

[ComVisible(true)]

public class TestClass

{

public void TestAPI()

{

}

[ComVisible(true)]

public struct TestStruct

{

int testField;

}

D:\tools>genman32 testlib.dll /out:1.man

Microsoft (R) .NET Framework Win32 Manifest File Generation Utility 2.0.60120.0

Win32 Manifest file D:\tools\1.man is created successfully

Let’s look at the generated manifest.

D:\tools>more 1.man

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">

<assemblyIdentity

name="testlib"

version="0.0.0.0"

processorArchitecture="MSIL" />

<clrClass

clsid="{ED653D53-DA9A-35A8-B16E-6C8704AC432D}"

progid="TestClass"

threadingModel="Both"

name="TestClass"

runtimeVersion="v2.0.50727">

</clrClass>

<clrSurrogate

clsid="{D250790F-F50A-33FD-990F-FF5DC3E26E9B}"

name="TestStruct">

</clrSurrogate>

<file name="testlib.dll">

</file>

</assembly>

We can also use this tool to add the manifest to the managed assembly.

D:\tools>genman32 testlib.dll /add /manifest:1.man

Microsoft (R) .NET Framework Win32 Manifest File Generation Utility 2.0.60120.0

Win32 Manifest added to assembly 'D:\tools\testlib.dll' successfully

We can verify the manifest is indeed successfully embedded to the managed assembly.

D:\tools>dumpmanifest -f testlib.dll 1

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">

<assemblyIdentity

name="testlib"

version="0.0.0.0"

processorArchitecture="MSIL" />

<clrClass

clsid="{ED653D53-DA9A-35A8-B16E-6C8704AC432D}"

progid="TestClass"

threadingModel="Both"

name="TestClass"

runtimeVersion="v2.0.50727">

</clrClass>

<clrSurrogate

clsid="{D250790F-F50A-33FD-990F-FF5DC3E26E9B}"

name="TestStruct">

</clrSurrogate>

<file name="testlib.dll">

</file>

</assembly>

Let’s prove ourselves that this is indeed working.

CoCreate.exe simply calls CoCreateInstance. If it fails, CoCreate.exe prints an error message, else it prints success.

D:\tools>more cocreate.exe.manifest

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">

<assemblyIdentity

name="CoCreate"

version="0.0.0.0"

type="win32"/>

</assembly>

D:\tools>cocreate {ED653D53-DA9A-35A8-B16E-6C8704AC432D}

Error: CoCreateInstance({ED653D53-DA9A-35A8-B16E-6C8704AC432D}) failed with hr=

0x80040154.

Let’s add TestLib to CoCreate.exe’s dependency.

D:\tools>more cocreate.exe.manifest

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">

<assemblyIdentity

name="CoCreate"

version="0.0.0.0"

type="win32"/>

<dependency>

<dependentAssembly>

<assemblyIdentity

name="testlib"

version="0.0.0.0"

processorArchitecture="MSIL" />

</dependentAssembly>

</dependency>

</assembly>

D:\tools>cocreate {ED653D53-DA9A-35A8-B16E-6C8704AC432D}

Success!

Good job!

How to tell if the current user is in administrators group programmatically

junfeng — Sat, 27 Jan 2007 02:00:00 GMT

You can use CheckTokenMembership (http://msdn2.microsoft.com/en-us/library/aa376389.aspx) to check whether a user is in administrators group. There is an example in the MSDN document.

The example will not work in Windows Vista. In Windows Vista, even if the user is in administrators group, the OS will create a filtered user token when user log on. The SID of administrators group is not included in the filtered user token. The full token is linked to the filtered user token, and can be retrieved with API GetTokenInformation with the new TokenLinkedToken information type.

The following is the sample code. You need to download Vista SDK to compile it. Please make sure you read the article in the reference section.

HRESULT IsUserAdmin(BOOL *pIsAdmin)
{
    int b;
    HANDLE hProcess = NULL;
    HANDLE hProcessToken = NULL;
    HANDLE hLinkedToken = NULL;
    BOOL fIsAdmin = FALSE;
    DWORD dwLength = 0;
    OSVERSIONINFO osver = {sizeof(OSVERSIONINFO)};
    HRESULT hr = S_OK;

*pIsAdmin = FALSE;

    // get handle to our process token
    hProcess = GetCurrentProcess();
    if (!OpenProcessToken(hProcess, TOKEN_QUERY, &hProcessToken))
    {
        hr = HRESULT_FROM_WIN32(GetLastError());
        goto Exit;
    }

    // get admin SID
    char AdminSID[SECURITY_MAX_SID_SIZE];
    dwLength = sizeof(AdminSID);
    if(!CreateWellKnownSid(WinBuiltinAdministratorsSid, NULL, &AdminSID, &dwLength))
    {
      hr = HRESULT_FROM_WIN32(GetLastError());
        goto Exit;
    }

    // check to see if the current token contains admin SID
    if (!CheckTokenMembership( NULL, &AdminSID, &fIsAdmin))
    {
        hr = HRESULT_FROM_WIN32(GetLastError());
        goto Exit;
    }

    if (fIsAdmin)
    {
        // printf("The user is in admin group, and the process is elevated.\n");
        *pIsAdmin = TRUE;
        goto Exit;
    }

    // if the current token does not contain admin SID, it does not mean
    // that the current user is not admin. In Vista by default the token of
    // users in administrator group has the the admin SID filtered. We nee
    // to use the unfiltered token to do the check.
    if (!GetVersionEx(&osver))
    {
        hr = HRESULT_FROM_WIN32(GetLastError());
        goto Exit;
    }

    // XP and below, we are done.
    if (osver.dwMajorVersion < 6)
    {
        // printf("The user is not in admin group.\n");
        goto Exit;
    }

// get handle to linked token (will have one if we are lua)
    if (!GetTokenInformation(   hProcessToken,
                                TokenLinkedToken,
                                (VOID*) &hLinkedToken,
                                sizeof(HANDLE),
                                &dwLength) )
    {
        b = GetLastError();
        if (   b == ERROR_NO_SUCH_LOGON_SESSION
            || b == ERROR_PRIVILEGE_NOT_HELD)
        {
            // printf("The user is not in admin group.\n");
            goto Exit;
        }

        hr = HRESULT_FROM_WIN32(b); // a real error
        goto Exit;
    }

    if (!CheckTokenMembership(   hLinkedToken, &AdminSID, &fIsAdmin))
    {
        hr = HRESULT_FROM_WIN32(GetLastError());
        goto Exit;
    }

    if (fIsAdmin)
    {
        // printf("The user is in admin group, and the process is not elevated.\n");
        *pIsAdmin = TRUE;
    }
    else
    {
        // printf("The user is not in admin group.\n");
    }

Exit:
    if (hProcess)
    {
        CloseHandle(hProcess);
    }

    if (hProcessToken)
    {
        CloseHandle(hProcessToken);
    }

    if (hLinkedToken)
    {
        CloseHandle(hLinkedToken);
    }

return hr;
}

Reference:

Teach Your Apps To Play Nicely With Windows Vista User Account Control

Debugging LoadLibrary Failures

junfeng — Mon, 20 Nov 2006 19:00:00 GMT

LoadLibrary is one of the mostly used yet unbelieveably complex APIs in Windows, if not the one. Russ Osterlund has a full MSDN article discussing LoadLibrary, yet he only touches the surface of the problem (how it works under normal condition.) Mike Grier is one of the most talented developers I have worked with in Microsoft. He devoted a full series on the intricacy of LoadLibrary. Yet he has to put it to a halt due to the complexity of the problem.

For developers that outside of the loader team, they don't have to understand all the intricacy of LoadLibrary (though they do need to understand how it works, the dos and don'ts of LoadLibrary, etc.). But then LoadLibrary fails, they do need to figure out why it fails. There are times that this is just hard to figure out why, especially when the binary depends on other dlls that they don't have source code available.

Fortunately, the loader team recognized the problem, and provided a built-in trace log to debug obsure LoadLibrary failures. The trace log is called "loader snaps" internally.

You can turn on loader snaps using gflags.exe. gflags.exe is part of Debugging Tools for Windows. You can download it from http://www.microsoft.com/whdc/devtools/debugging/default.mspx.

To enable loader snaps, run "gflags.exe -i your-app-without-path.exe +sls"

You have to run your application under debugger to see the loader snaps. You can use debuggers in the Debugging Tools for Windows package. An example is shown at the bottom of this article.

If there is any failures, you will see "failed" in loader snaps.

Be warned that loader snaps may have enormous output. You may want to isolate the problem before turning on loader snaps.

gflags.exe can also turn on all kinds of debugging capabilities, please refer to MSDN http://technet2.microsoft.com/WindowsServer/en/library/00d4872f-eeb3-4a6e-910a-299ad55aed631033.mspx?mfr=true for more information.

An example of loader snaps:

D:\Tools>c:\debuggers\cdb loadlib svn-win32-1.4.2\bin\ssleay32.dll

CommandLine: loadlib svn-win32-1.4.2\bin\ssleay32.dll
Symbol search path is: *** Invalid ***
****************************************************************************
* Symbol loading may be unreliable without a symbol search path. *
* Use .symfix to have the debugger choose a symbol path. *
* After setting your symbol path, use .reload to refresh symbol locations. *
****************************************************************************
Executable search path is:
ModLoad: 00400000 0040a000 image00400000
ModLoad: 7c900000 7c9b0000 ntdll.dll
ModLoad: 7c800000 7c8f4000 C:\WINDOWS\system32\kernel32.dll
(b1c.f94): Break instruction exception - code 80000003 (first chance)
eax=00241ea4 ebx=7ffd3000 ecx=00000000 edx=00000001 esi=00241f18 edi=00241ea4
eip=7c901230 esp=0012fb20 ebp=0012fc94 iopl=0 nv up ei pl nz na po nc
cs=001b ss=0023 ds=0023 es=0023 fs=003b gs=0000 efl=00000202
*** ERROR: Symbol file could not be found. Defaulted to export symbols for ntdl
l.dll -
ntdll!DbgBreakPoint:
7c901230 cc int 3
0:000> g
[b1c,f94] LDR: Real INIT LIST for process D:\Tools\loadlib.exe pid 2844 0xb1c
Loading library svn-win32-1.4.2\bin\ssleay32.dll...
LDR: LdrLoadDll, loading svn-win32-1.4.2\bin\ssleay32.dll from D:\Tools;C:\WINDO
WS\system32;C:\WINDOWS\system;C:\WINDOWS;.;c:\debuggers\winext\arcade;C:\WINDOWS
\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\PROGRA~1\CA\SHARED~1\SCANEN~1;C
:\PROGRA~1\CA\ETRUST~1;C:\Program Files\ATI Technologies\ATI Control Panel;C:\Pr
ogram Files\Common Files\Roxio Shared\DLLShared;C:\WINDOWS\system32\WindowsPower
Shell\v1.0
LDR: Loading (DYNAMIC, NON_REDIRECTED) D:\Tools\svn-win32-1.4.2\bin\ssleay32.dll

ModLoad: 10000000 10031000 D:\Tools\svn-win32-1.4.2\bin\ssleay32.dll
LDR: LIBEAY32.dll used by ssleay32.dll
LDR: LdrpResolveDllName - call to RtlDosSearchPath_U failed
DllName: "LIBEAY32.dll"
Path: "D:\Tools;C:\WINDOWS\system32;C:\WINDOWS\system;C:\WINDOWS;.;c:\debugge
rs\winext\arcade;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\PROG
RA~1\CA\SHARED~1\SCANEN~1;C:\PROGRA~1\CA\ETRUST~1;C:\Program Files\ATI Technolog
ies\ATI Control Panel;C:\Program Files\Common Files\Roxio Shared\DLLShared;C:\WI
NDOWS\system32\WindowsPowerShell\v1.0"
LDR: LdrpLoadImportModule - LdrpMapDll(00143278, LIBEAY32.dll, NULL, TRUE, 0, 00
12F658) failed with status c0000135
LDR: LdrpWalkImportTable - LdrpLoadImportModule failed on import LIBEAY32.dll wi
th status c0000135
LDR: Unloading svn-win32-1.4.2\bin\ssleay32.dll due to error c0000135 walking im
port descriptors
LDR: UNINIT LIST
(1) [ssleay32.dll] D:\Tools\svn-win32-1.4.2\bin\ssleay32.dll (0) deini
t 0
LDR: Unmapping [ssleay32.dll]
LoadLibrary failed with GetLastError() = 126
LDR: LdrGetDllHandle, searching for mscoree.dll from
LDR: LdrGetDllHandle, searching for mscoree.dll from D:\Tools;C:\WINDOWS\system3
2;C:\WINDOWS\system;C:\WINDOWS;.;c:\debuggers\winext\arcade;C:\WINDOWS\system32;
C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\PROGRA~1\CA\SHARED~1\SCANEN~1;C:\PROGRA~1
\CA\ETRUST~1;C:\Program Files\ATI Technologies\ATI Control Panel;C:\Program File
s\Common Files\Roxio Shared\DLLShared;C:\WINDOWS\system32\WindowsPowerShell\v1.0

LDR: PID: 0xb1c finished - 'loadlib svn-win32-1.4.2\bin\ssleay32.dll'
eax=0012faa0 ebx=00000000 ecx=0000e6dc edx=0012fb4d esi=7c90e88e edi=00000001
eip=7c90eb94 esp=0012fdb8 ebp=0012feb4 iopl=0 nv up ei pl zr na pe nc
cs=001b ss=0023 ds=0023 es=0023 fs=003b gs=0000 efl=00000246
ntdll!KiFastSystemCallRet:
7c90eb94 c3 ret

Touch the exe, after you added a manifest for it, in Vista

junfeng — Wed, 25 Oct 2006 18:00:00 GMT

You are an enthusiastic and responsible developer. You love programming, and you love programming the right way.

So you get the latest and greatest Windows Vista. You try your hard-worked amazing.exe application in Vista. Did not work. Apparently, amazing.exe needs admin privilege to do wonderful things. But in Vista, the user by default does not have admin privilege.

You did your research. You understand that you need to add a manifest to your application, and declare that the application requires administrator in the manifest. So you added amazing.exe.manifest, and put it next to amazing.exe.

Did not work. Amazing.exe did not get admin privilege.

You double checked the syntax of the manifest. Yes, it is right. You compared it to another working example. Yes, they are the same. You run amazing.exe again. Still did not work.

You are angry. What is going on, Microsoft?

The truth is, in Windows Vista, in order to improve CreateProcess performance, we cache the fact that an exe has manifest or not. The key to this cache, are the full path of the exe, and the last modified time of the exe file.

After you execute the exe without manifest, when you add a manifest to the exe, in order for the OS to see the manifest, you need to change the last modified time of the exe (or simply say, touch the exe), to invalidate the cache entry for the exe.

The cache only exists in memory, and is never flushed to disk. On reboot the cache starts clean.

At the time we did the work, our measurement shows that the cache improved CreateProcess performance by 10-15% in warm case, when the application does not have manifest.

So remember, touch the exe, after you added a manifest for it, in Vista.

Application Shutdown Changes in Windows Vista

junfeng — Thu, 19 Oct 2006 22:00:00 GMT

MSDN documented the Windows Vista changes regarding application shutdown.

http://windowssdk.msdn.microsoft.com/en-us/library/ms700677(VS.80).aspx

Programmatically determine if an application requires elevation in Windows Vista

junfeng — Wed, 18 Oct 2006 18:00:00 GMT

In Windows Vista, by default, application will execute without administrator privilege, even when the user launching the application is part of the administrators group.

You can explicitly elevate the application with administrator privilege using the shell "Runas" verb.

There are some cases the OS will decide to launch the application as elevated by default. The decision points are:

1. If the application has a manifest that explicitly asks for administrator privilege.
2. The application is one of the well known setup installers.
3. Application Compatibility testing reveals that the application requires admin privilege.
4. A certain heuristics to determine if the application is an installer. For example, if the application name contains "setup" or "installer", it is a good indication that the application is an installer, thus requires administrator privilege.

There are times you may want to know if the OS will decide to launch the application elevated. For example, you may want to warn user before launch the application.

There is no direct API for this. But there is an alternative way to determine so:

Call CreateProcess() with dwCreationFlags as CREATE_SUSPENDED. If the application requires elevation, CreateProcess will fail, and GetLastError() will return ERROR_ELEVATION_REQUIRED.

Run/RunOnce/RunOnceEx Registry Key

junfeng — Wed, 20 Sep 2006 01:00:41 GMT

Run\RunOnce\RunOnceEx are documented ways to automatically run certain tasks when system startup or a user logs in.

Run\RunOnce keys are documented here:

Run and RunOnce Registry Keys
http://windowssdk.msdn.microsoft.com/en-us/library/ms723554.aspx

RunOnceEx is documented here:

Syntax for the RunOnceEx Registry Key
http://support.microsoft.com/default.aspx?kbid=232509

Description of the RunOnceEx Registry Key
http://support.microsoft.com/kb/310593

You can also specify RunOnce when install device drivers

KB 281820: INFO: Specifying RunOnce in Device INF Files
http://support.microsoft.com/default.aspx?scid=kb;EN-US;Q281820

Be careful about RunOnce registry key: It may run before system restart.

According to KB 281829, RunOnce registry key will run in the following cases:

1. At the end of installation through InstallFromHinfSection even in the cases where you must restart the computer.

2. After the default processing of DIF_INSTALLDEVICE even if you must restart the computer (with the exception of server-side processing).

3. After the system has been restarted.

This means, RunOnce registry key entries may be executed immediately after a device driver installation, which may happen at any given time.

If your RunOnce entry needs to be executed after certain event, make sure you write the RunOnce registry key after the event, or if you cannot do so, use RunOnceEx. Otherwise you may experience random failures.

Windows XP may reboot when encounter certain manifest files

junfeng — Thu, 14 Sep 2006 11:11:53 GMT

If you are developing applications for Windows Vista using Visual Studio 2005, and you are adding Vista UAC manifest to your application, when your application runs on Windows XP with Service Pack 2 or Windows Server 2003 RTM (without SP1), Windows may reboot unexpectly.

This is due to a bug in Sxs.dll that it improperly handles duplicated namespaces in the same XML element. The following is an example of the problematic XML file:

Notice there are two namespaces for element trustInfo, and they are duplicate.

To workaround this bug, remove one of the duplicated namespaces (for example, remove the namespace in red).

A hotfix is available in http://support.microsoft.com/kb/921337.

This bug is fixed in Windows Server 2003 SP1 and Windows Vista.