mattonsoftware.com : .NET

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

.NET Resources: Updated

matt — Sat, 06 May 2006 09:25:00 GMT

Managing hyperlinks via CommunityServer has become too cumbersome, I've shifted these resources to del.icio.us, as follows:

http://del.icio.us/MattDunn

You can also subscribe to changes via the following feed:

http://del.icio.us/rss/MattDunn

Many thanks to Grant for the tip!

Issues Migrating from .NET 1.0 to .NET 1.1

matt — Mon, 06 Mar 2006 11:48:00 GMT

Mainstream support for .NET 1.0 ends 30 June 2007. For organisations migrating from .NET 1.0 to .NET 1.1, the following changes are for consideration:

In addition to the changes listed above, the following issues were encountered during a recent migration activity.

Web Service WSDL Generation Issue

After upgrading websites from ASP.NET 1.0 to 1.1, the following error message may be encountered:

The XML element named 'HelloWorldMethodResponse' from namespace 'http://www.test.com' references a method and a type. Change the method's message name using WebMethodAttribute or change the type's root element using the XmlRootAttribute.

This error occurs when the WSDL for a web service is being generated. Note that the error message includes two possible solutions. The first of these solutions which recommends changing the web methods message name using the WebMethodAttribute is undesirable as this will alter the WSDL contract and break existing consumers. The second of the two solutions, applying the XmlRoot attribute to the web methods return type, will resolve the error, however, this requires recompilation of existing web service assemblies.

Properties of web methods that cause this error include:

The return type is a class or structure;
The return type is named [WebMethodName]Response;
The web method accepts no parameters (or has parameters that do not serialise to a complex type in the WSDL, for example, strings, integers).

This error does not affect the invocation of existing client proxies as they do not consume the WSDL at runtime. This issue will affect development activities when the WSDL is requested, for example, when re-generating client-side proxies using the Visual Studio Add/Update Web Reference feature.

To resolve this issue, apply the XmlRoot attribute to the return type of the WebMethod, noting the following:

The ElementName should be of the form [ResponseType]Dummy. Note that no element named HelloWorldMethodResponseDummy will appear in the WSDL;
The DataType property should be set to the response type.

An example application of the XmlRoot attribute is as follows:

[WebMethod(Description = "Test Method")]
[return: XmlRoot(Namespace = "http://www.test.com/",
        ElementName = "HelloWorldMethodResponseDummy",
        DataType = "HelloWorldMethodResponse",
        IsNullable = false)]
public HelloWorldMethodResponse HelloWorldMethod()
{
    return new HelloWorldMethodResponse();
}

Activator.CreateInstance() raises a System.MissingMethodException exception when creating instances of Arrays

In order for the Activator.CreateInstance() method to create instances of a given type, the type must define a public default constructor. In .NET 1.0, the Activator does not raise an exception when creating instances of Arrays (which has a private default constructor), however, this issue has been fixed for .NET 1.1 and now raises a System.MissingMethodException ("No parameterless constructor defined for this object") exception as expected.

To resolve this issue, the Array.CreateInstance() method can be used instead of Activator.CreateInstance(), as follows:

...

if (typeToInstantiate.IsArray)
{
    Type elementType = typeToInstantiate.GetElementType();
    newInstance = Array.CreateInstance(elementType, arraySize);
}
else
{
    newInstance = Activator.CreateInstance(typeToInstantiate);
}

Diagnosing Binary Formatter Version Incompatability Problems

matt — Tue, 28 Feb 2006 11:37:00 GMT

Clients consuming remoting services hosted in IIS (and therefore exposed via the HTTP channel) configured to use the binary formatter may receive the following error:

An unhandled exception of type 'System.Runtime.Serialization. SerializationException' occurred in mscorlib.dll

Additional information: BinaryFormatter Version incompatibility. Expected Version 1.0. Received Version 1008738336.1684104552.

This article explains that the above error is masking the original exception, and describes a mechanism for tracing this exception. However, this tracing process requires opening additional ports on the server, which may be problematic if the application under inspection is hosted in a secured environment.

An alternative to tracing the error is to configure the remoting service to use the SOAP formatter instead of the binary formatter, which will allow the original exception to propogate to the client correctly. The SOAP formatter is the default formatter for the HTTP channel, so assuming the remoting system is configured declaratively, the following elements can be removed/commented out of the configuration files:

Client

<configuration>
    <system.runtime.remoting>
        <application>
            <channels>
                <channel ref="http">
                    <clientProviders >
                        <formatter ref ="binary" />
                    </clientProviders >
                </channel>
            </channels>
        </application>
    </system.runtime.remoting>
</configuration>

Server

<configuration>
<system.runtime.remoting>
    <application>
      <channels>
        <channel ref="http"port="1234">
          <serverProviders >
            <formatter ref ="binary" />
          </serverProviders >
        </channel>
      </channels>
    </application>
</system.runtime.remoting>
</configuration>

Also note that custom errors must be disabled on the server for the original exception to propogate correctly:

<configuration>
    <system.web>
         <customErrors mode="Off" />
    </system.web>
</configuration>

WinForms use of AssemblyInformationalVersion Attribute

matt — Sun, 26 Feb 2006 06:58:00 GMT

The AssemblyInformationalVersion attribute provides a secondary mechanism for versioning an assembly without modifying the value of the AssemblyVersion attribute, thus consumers of an assembly do not need to apply binding redirects or publisher policy when revisions of an assembly are deployed.

Contrary to the documentation:

The attribute defined by this class attaches additional version information to an assembly for documentation purposes only. This data is never used at runtime.

this attribute is referenced by the System.Windows.Forms.Application.ProductVersion static property, which in turn is referenced by the Application.CommonAppDataPath, Application.LocalUserAppDataPath and Application.UserAppDataPath static properties. This is the case for the .NET 1.* and .NET 2.0 class libraries.

If the AssemblyInformationalVersion attribute is applied to the base executable, the ProductVersion property and its dependent properties will use this value instead of the AssemblyVersion attribute value.

Microsoft states that this behaviour is by design.