mattonsoftware.com : .NET, Tools

PPUtil: A Utility for Publisher Policy Generation

matt — Sun, 11 Mar 2007 09:23:00 GMT

The conventional method of creating publisher policy (PP) assemblies becomes cumbersome when dealing with many assemblies, and many earlier versions of assemblies¹.

PPUtil is a configuration-based utility for generating PP for many assemblies/versions. This tool was authored using .NET 2.0, however, the resultant PP assemblies can be used with .NET 1.0/1.1-compiled assemblies.

Download

Binaries: PPUtil_Binaries_v1_0_0_0.zip
Source: PPUtil_Source_v1_0_0_0.zip

This work is licensed under a Creative Commons Attribution 3.0 License.

Usage

PPUtil configurationFile outputDirectory

Common Usage Scenarios

Redirect a specific earlier version of an assembly to a later version;
Redirect a range of earlier versions of an assembly to a later version.

In both scenarios, resolution of the redirection for the earlier assembly versions is limited to major/minor version combinations i.e. build and revision numbers are not considered. This is due to the design of the publisher policy mechanism itself.

Configuration Examples

Redirect a specific earlier version of an assembly to a later version

Use the oldVersion attribute of the bindingRedirect element to specify the specific earlier version to redirect from. The major/minor component of the oldVersion will typically correspond to the oldMajorMinorVersion attribute of the publisherPolicy element.

<publisherPolicy>
    <assemblies>
      <assembly name="SampleAssembly"
              publicKeyToken="baa3201a127d8068"
                strongNameKeyPath="SampleKey.snk" >
        <publisherPolicies>
          <publisherPolicy oldMajorMinorVersion="1.0" version="1.0.0.0">
            <bindingRedirect oldVersion="1.0.0.0" newVersion="1.1.0.0" />
          </publisherPolicy>
        </publisherPolicies>
      </assembly>
    </assemblies>
</publisherPolicy>

Redirect a range of earlier versions of an assembly to a later version

Use the oldLowestVersion and oldHighestVersion attributes of the bindingRedirect element to specify the range of earlier versions to redirect from.

Tips

The provided configuration file must include a configuration section declaration for the publisherPolicy configuration section, as follows. The utility will also detect the absence of this declaration and prompt the user accordingly.

<configuration>
<configSections>
<section name="publisherPolicy" type="PublisherPolicyTool.Configuration.PublisherPolicyConfigurationSection, PPUtil" />
</configSections>
...
</configuration>

The PP assembly itself is versioned. When there are multiple versions of a PP assembly available, the version with the highest number is used. In .NET 1.0/1.1 a bug exists in the assembly loader whereby when determining the PP assembly with the highest number, the version numbers are sorted in alphabetic order, rather than numeric order.
The same strong name key used to sign the assembly the PP applies to must be used to sign the PP assembly;
When GACing a PP assembly, the generated PP configuration file must reside in the same folder as the PP assembly;
To diagnose binding issues, the binding resolution can be traced using fuslogw or output to disk by modifying registry values;

Acknowledgments

The idea of using the managed assembly builder APIs for PP generation was derived from Omers publisher policy generation sample.

Footnotes

1: Generating PP involves specifying the old version (major and minor version number resolution) of an assembly that the binding policy within the PP assembly will be applied to. The old version corresponds to an earlier version of an assembly that is referenced by dependent assemblies.

LibCheck: Highlight Public API Differences Between Assembly Revisions

matt — Thu, 28 Sep 2006 13:50:00 GMT

LibCheck is an assembly comparison tool that:

"... allows you to compare two versions of an assembly, and determine the differences. The tool reports the differences as a combination of 'removed' and 'added' APIs."

The comparison results present:

"removed" items: the original member has been either removed or modified;
"added" items: member has been added to the new version, or is a modified form of an original member;
breaking changes highlighted in red.

The following example compares two versions of an assembly.

Generating Metadata for Comparison

libcheck.exe -store AssemblyName FolderNameToStoreResults -full FolderContainingAssembly

For example:

libcheck.exe -store HelloWorld.dll 1.0.0.0 -full C:\HelloWorldV1\

libcheck.exe -store HelloWorld.dll 2.0.0.0 -full C:\HelloWorldV2\

Performing the Comparison

libcheck.exe -compare FolderContainingFirstStoreResults FolderContainingSecondStoreResults

For example:

libcheck.exe -compare 1.0.0.0 2.0.0.0

Here is an example comparison report.

Debugging Production Applications using ADPlus

matt — Fri, 22 Sep 2006 03:02:00 GMT

ADPlus is used to take snapshots of processes in environments where development-time debugging tools are not available e.g. Production server farms, end-users workstations. ADPlus is a Visual Basic script provided as part of the Debugging Tools for Windows that wraps the CDB debugger.

Snapshots of processes taken with ADPlus are analysed using the Windows Debugger (WinDbg). Managed processes in particular are analysed using SOS.dll, which contains extensions to WinDbg for debugging managed processes.

Practical applications include taking snapshots of WinForms and ASP.NET processes to interrogate unhandled exceptions, memory utilisation, resource contention etc.

Installing Debugging Tools for Windows in Target Environment

Download debugging tools;
XCOPY deploy to target environment;
Create a folder to store snapshots;
Set CScript as the default scripting engine (required by ADPlus, also requires Windows Script Host 5.6 or higher, interrogate version using CSCRIPT /? command)

CSCRIPT /H:CScript

Taking a Snapshop using ADPlus

The following examples demonstrate taking a snapshot of a WinForms process:

Via process id
ADPlus.vbs -c ADPlus_Config.xml -p 968
Via process name
ADPlus.vbs -c ADPlus_Config.xml -pn HelloWorldGUI.exe

Note that ADPlus will warn that the _NT_SYMBOL_PATH environment variable is not set. This is ok as the environment variable is not required for taking snapshots, however, it is required for analysing the snapshot later.

The following example ADPlus_Config.xml file configures ADPlus for Hang mode (hang mode instructs ADPlus to take the snapshot immediately, crash mode is another option that attaches the debugger to the process, then waits for process to exit before generating the snapshot):

<ADPlus>
    <Settings>
        <RunMode>HANG</RunMode>
        <Option>Quiet</Option>
      <OutputDir> C:\Snapshots </OutputDir>
    </Settings>
    
    <PreCommands>
        <Cmd> .load C:\Program Files\Debugging Tools for Windows\clr10\sos.dll </Cmd>
    </PreCommands>
    <Exceptions>
        
        
        <Config>
            <Code>
                 AllExceptions
            </Code>
            <Actions1>
                 FullDump;
            </Actions1>
            <ReturnAction1>
                 GN
            </ReturnAction1>
        </Config>
    </Exceptions>
</ADPlus>

Using WinDBG and SOS.dll

Install debugging tools;
Add installation location to PATH environment variable;
Create a folder to store symbols;
Add new environment variable, referencing the symbols folder:

Name: _NT_SYMBOL_PATH
Value: SRV*c:\temp\symbols* http://msdl.microsoft.com/download/symbols

This setting is used by WinDbg to dynamically download symbols (pdb files) on demand.

Launch WinDbg.exe;
Open the snapshot using File --> Open Crash Dump;
Load SOS.dll by entering the following command:

.load C:\Program Files\Debugging Tools for Windows\clr10\sos.dll

Useful WinDbg/SOS.dll commands are:

!help (all available commands)
!help <functionname> (help on provided function)
!clrstack (shows managed stack)
!dae (dumps all managed exceptions, noting that instances of ExecutionEngineException, StackOverflowException and OutOfMemoryException are normal)
!EEStack (shows full stack trace, including managed and unmanaged calls)
!do (dump object, including fields)

Further Information

How to use ADPlus to troubleshoot "hangs" and "crashes"

Production Debugging for .NET Framework Applications

Mini Dump Snapshots and the New SOS

Tips on Debugging Managed Exceptions with ADPlus and WinDbg