However, I have discovered that some developers and architects seriously question the value of such a construct. This actually surprised me, especially after it was noted that one reason to question it is that such a construct is rarely, if ever, seen.

I have not considered this perspective, perhaps because I did see usage of it years ago by others (using Ruby). But now that it has been raised as an issue, I would like to investigate this further.

To begin, I did a search online concerning how many people use it and for what reasons, focusing specifically on its usage in C#.

The first article I came across is at CSharpFriends. I noted these two points:

1. “At times you need to define a class only to serve [an]other class and there are no other reasons to make it visible.”

2. “Nested classes have the advantage of access to all the members of the outer class. “

The second article was by Jason Whittington, and demonstrated an elegant approach to managing derived classes. He sums up its advantage in this statement:

” The key turns out to be that given a Type object you can enumerate over its NestedTypes collection to see the contained subtypes. You can’t do this with namespaces, because namespaces can be arbitrarily extended into new assemblies.”

The next article by Scott Baldwin describes how he was able to avoid maintaining the same list in two places while working with the Infragistics UltraGrid control.

“This means that I can let the user control maintain the row names and no-one ever needs to know about our RowSelectorDrawFilter class as it’s happily nested in MyControlClass.”

Yet another article by Christopher Lord provides two reasons for using nested classes.

“Nested classes are usually used for two big reasons. the first is to hide implementation of interfaces. … Additionally, the nested class gains access to private/protected methods and variables in [the outer class, which] leads to the second reason to use nested classes: it allows you to use object-oriented programming to implement your classes, while keeping everything packaged up in a clean interface for your target audience. … This is keeping with the principle of “least interface,” ie, expose as little of your engine as possible. Provide a gas pedal and a steering wheel while keeping details about crankshafts under the hood.”

A more advanced example is given by Jon Skeet wherein he compares five implementations of the singleton pattern in C#. The fifth one provided a fully lazy instantiation using nested classes.

public sealed class Singleton
{
    Singleton()
    {
    }

    public static Singleton Instance
    {
        get
        {
            return Nested.instance;
        }
    }

    class Nested
    {
        // Explicit static constructor to tell C# compiler
        // not to mark type as beforefieldinit
        static Nested()
        {
        }

        internal static readonly Singleton instance = new Singleton();
    }
}

“This means the implementation is fully lazy, but has all the performance benefits of the previous ones.”

Interestingly, although he considered it elegant, he also seemed to believe it was a tricky solution.

“Solution 5 is elegant, but trickier than 2 or 4, and as I said above, the benefits it provides seem to only be rarely useful.”

I also found a pertinent thread on StackOverFlow discussing this same question about using nested classes. Opinions diverged, but it was agreed that it was not commonly used in C# yet. Still, Jon Skeet brought out a nice new pattern he calls the “better enum” pattern.

public class MyCleverEnum
{
    public static readonly MyCleverEnum First = new FirstCleverEnum();
    public static readonly MyCleverEnum Second = new SecondCleverEnum();

    // Can only be called by this type *and nested types*
    private MyCleverEnum()
    {
    }

    public abstract void SomeMethod();
    public abstract void AnotherMethod();

    private class FirstCleverEnum : MyCleverEnum
    {
        public override void SomeMethod()
        {
             // First-specific behaviour here
        }

        public override void AnotherMethod()
        {
             // First-specific behaviour here
        }
    }

    private class SecondCleverEnum : MyCleverEnum
    {
        public override void SomeMethod()
        {
             // Second-specific behaviour here
        }

        public override void AnotherMethod()
        {
             // Second-specific behaviour here
        }
    }
}

If you are wondering why I am referencing so many places, it is because some developers have been asking me who uses it; why would anyone use it; what specific, real-life examples demonstrate its use; and, in short, on what basis should it be allowed into the codebase?

But I am not finished.

Microsoft itself provided some recommendations about nested classes on it MSDN site. This is based on .NET version 1.1, but it probably is still relevant:

The use of nested classes in your components is a powerful and convenient way to supply subordinate objects that your component might use. Nested classes allow your component to create and use objects without making them accessible or creatable by external users. Overuse of nested classes, however, can make your components difficult to work with and maintain. Here are some design recommendations that will help you to use nested classes in your components.

• If your class is logically contained by another class, but has no stand-alone significance, implement it as a nested class…
• If members of your class need to access private member variables of the object containing it, you can implement it as a nested class…
• If a class needs to implement an interface for interaction with other components, you can create an implementation of that interface as a nested class and expose an instance of the class as an interface property.
• If your component will need to use one of several different subtypes of a contained object, but the subtype will not be known until run time, you can implement each subtype as a nested class as opposed to implementing all possible subtypes within a single class. When used with Just-In-Time compilation, nesting classes improves program performance because only the required type is compiled.
• If other classes will reasonably need access, or will want to collect or contain your class, do not implement it as a nested class. A class that is accessed by several other classes should stand alone.
• In general, do not implement public nested classes. Nested classes should primarily be for the internal use of the containing class…

In addition to the above findings, I came across some books that mention nested classes in particular.

For example, Trey Nash makes some useful comments in his book, Accelerated C# 2008 (p.66):

“Nested classes have some special capabilities and lend themselves well to situations where you need a helper class that works on behalf of the containing class.

For example, a container class might maintain a collection of objects. Imagine that you need some facility to iterate over those contained objects and also allow external users who are doing the iteration to maintain a marker, or an iterator of sorts, representing their place during the iteration. This is a common design technique. Preventing the users from holding on to direct references to the contained objects gives you much greater flexibility to change the internal behavior of the container class without breaking code that uses the container class. Nested classes provide a great solution to this problem for several reasons. First, nested classes have access to all the members that are visible to the containing class, even if they’re private… “

Here he then gives an example in code, and points out that you can apply the same access modifiers to nested classes as you can to any other member of the class, while non-nested classes can only be declared as either public or internal.

In another book I read, Design Patterns in C# (Software Patterns Series), author Steven J. Metsker recommends using nested classes when implementing the Flyweight pattern (pp. 150-153).

Extracting the immutable part of an object is half the battle in applying the Flyweight pattern. The remaining work includes creating a flyweight factory… You also have to ensure that clients will use your factory instead of constructing instances of the flyweight class themselves…

Access modifiers do not supply the complete control over instantiation that you might want. You might like to ensure that [your factory] is absolutely the only class that can create new instances. To achieve this level of control, you can apply a nested class…

In conclusion, there are definitely valuable use cases for nested classes, but C# programmers are generally not familiar with them yet. Lack of familiarity is no reason to avoid a capability that has been found useful.

I hope this post helps more developers better understand the usefulness and acceptability of C# nested classes.

The article is an interview with Erich Gamma, one of the members of the “Gang of Four” (GoF) responsible for the landmark book, Design Patterns: Elements of Reusable Object-Oriented Software (Addison-Wesley, 1995).

I would like to summarize some of what Gamma says that I find interesting.

First, regarding what patterns are good for, Gamma says:

• patterns are good for learning OO and design in general
• the GoF patterns help by explaining trade-offs
• the fact that patterns are implementable is what makes them so valuable
• patterns provide names for design building blocks, which allows you to describe and discuss a particular design

Regarding learning patterns, he says:

• you only appreciate a pattern when it takes away some design pain
• just enumerating the patterns is really boring

In this regard, Gamma said that Head First Design Patterns is a great book – “not only because it is fun to read but also because they are able to communicate the essence of design patterns in a novel and highly visual way”.

Regarding the use of patterns, he says:

• do not start immediately throwing patterns into a design
• wait until you understand more of the problem, then refactor to patterns
• use patterns after encountering a design pain

He then points out that the GoF book describes a library of patterns (as building blocks), as opposed to Christopher Alexander’s landmark book, which describes a pattern language.

In part 2 of the interview, the focus is on reusability.

• it’s hard to create highly reusable frameworks
• it is crucial to have well-defined APIs
• Plug-ins provide reusable code following explicit conventions to separate the API from internal code
• you are not done until you have also thought about the extension points your plug-in might offer
• Patterns allow you to reuse design ideas and concepts independent of concrete code

Interestingly, a point regarding thinking ahead brings Gamma to admit he’s changed his perspective. The GoF book says, “The key to maximizing reuse lies in anticipating new requirements and changes to existing requirements, and in designing your systems so they can evolve accordingly…”  Interviewer Bill Venners noted that this contradicts the XP philosophy. Gamma confides, “I probably wouldn’t write this exactly this way anymore. To add flexibility, you really have to be able to justify it by a requirement.”

In part 3 of the interview, focus was placed on a couple of design principles.

The first was “program to an interface, not an implementation”.

• dependency relationships have to be carefully managed in a large application
• depending on an interface is often beneficial because you’re decoupled from varying implementations

Caution is advised here. One should weigh use of interfaces with abstract classes.

• Since changing interfaces breaks clients you should consider them as immutable once you’ve published them
• Alternatively, an abstract class gives you the freedom to add new methods later
• writing against a type far up in the hierarchy is consistent with the programming to an interface principle

The second was “favor object composition over class inheritance”.

• you should favor composition because plugging in a behavior is simpler and results in reduced coupling
• increased flexibility comes from ability to use different strategy objects that can change at run-time
• inheritance results in tight coupling between the base class and the subclass, due to the implicit context in which the subclass code will be called
• composition does use inheritance, but typically in the form of implementing a small interface and not from extending a big class

In part 4 of the series, the focus was on patterns and practice.

• patterns have both a problem and a solution, and you need to see both
• if you just look at the solution part, it isn’t that enlightening and all patterns start to look the same
• patterns have both positive effects and associated liabilities
• One of the key values of a pattern is that it captures trade-offs so that you don’t have to do the analysis again.

On the importance of practice:

• in the book we only tell when to apply a pattern, but removing a pattern can simplify a system
• you cannot learn patterns just from reading a book
• You become a master by mimicking the work of excellent developers

There was another segment, but it focused on a particular tool, so I will disregard it here.

Overall, I found this series insightful, particularly since it incorporates a self-assessment by an original author of such an influential work as the Gang of Four book. It highlights the points he considers salient, as well as some aspects he considers superceded by lessons learned after ten years of additional experience.

Attempts with SVCUTIL.EXE

We are using WCF, so my first thought is to use svcutil.exe to generate just the data contract. This utility gives the option to refer to local files or remote files, but past experience tells me to just download the XML Schema files and run it locally.

The files are available from http://metadata.dod.mil/mdr/irs/DDMS/ and include some different dependencies than the previous version. For example, XLink is now used, and the ICISM has been updated, among other things. I extract the relevant files to a working directory.

The main file is DDMS-v2_0.xsd, so I run svcutil against that one. I need to use the /dconly option to generate just the data contracts. Unfortunately, this results in an error.

Error: Type ‘ResourceType’ in namespace ‘http://metadata.dod.mil/mdr/ns/DDMS/2.0/’ cannot be imported. ‘maxOccurs’ on element ” must be 1. Either change the schema so that the types can map to data contract types or use ImportXmlType or use a different serializer.

If you are using the /dataContractOnly option to import data contract types and are getting this error message, consider using xsd.exe instead. Types generated by xsd.exe may be used in the Windows Communication Foundation after applying the XmlSerializerFormatAttribute attribute on your service contract. Alternatively, consider using the /importXmlTypes option to import these types as XML types to use with DataContractFormatAttribute attribute on your service contract.

I googled for “svcutil error type in namespace cannot be imported” and came across someone asking about a similar issue. The moderator, Eugene Osovetsky, pointed out the following:

The Data Contract Serializer only supports a very specific subset of XML schema. In particular, as you have discovered, it does not support abstract types or attributes (except for some very special attributes from one special namespace).

You have two options: either fix the schema to follow the Data Contract rules, or use a different serialization engine (the XmlSerializer). As the error message tells you, “if you are using the /dconly option … consider using xsd.exe instead”. The xsd.exe tool (included as part of the .NET Framework 2.0 SDK) will generate valid XmlSerializer-compatible classes that you will be able to use in WCF by applying the [XmlSerializerFormat] attribute to your service contract.

I agree that it would seem intuitive for “/useXmlSerializer” to work in your case. Unfortunately, in v1 of WCF, the “/useXmlSerializer” option will only work when importing WSDL and will not work when importing XSD. We may add this in a future version (/uxs with /dconly will automatically do what xsd.exe does).

Ok, so this means first try /importXmlTypes with svcutil, then try using xsd.exe.

Using “svcutil /dconly /importXmlTypes DDMS-v2_0.xsd” resulted in tons of validation errors.

Error: There was a validation error in the schemas provided for code generation:
Source:
Line: 88 Column: 5
Validation Error: The ‘http://metadata.dod.mil/mdr/ns/DDMS/2.0/:identifier’ element is not declared.

Error: There was a validation error in the schemas provided for code generation:
Source:
Line: 89 Column: 5
Validation Error: The ‘http://metadata.dod.mil/mdr/ns/DDMS/2.0/:title’ element is not declared.
:

:

I reviewed the help for svcutil, and noticed that it accepts standard wildcards for the file path. It also accepts multiple, separately listed files.

Using “svcutil /dconly /importXmlTypes *.xsd” generated the data contract types without errors. However, when I tried using the resulting classes, I discovered that they were quite superficial and made extensive use of XmlNode arrays. I couldn’t use Intellisense to access nested properties in a meaningful way. I would have to manually iterate and check types, then downcast to make use of them.

Obviously, svcutil is limited in its ability to generate data contracts from XML Schema files. Time to try xsd.exe.

Attempts with XSD.EXE

Using the same working directory, I run xsd.exe against the main file, specifying the option to generate classes: “xsd.exe /c DDMS-v2_0.xsd”. This resulted in numerous erros regarding undeclared attribute groups.

Schema validation warning: Reference to undeclared attribute group ‘urn:us:gov:ic:ism:v2:SecurityAttributesOptionGroup’.
Line 61, position 4.
Schema validation warning: Reference to undeclared attribute group ‘urn:us:gov:ic:ism:v2:SecurityAttributesOptionGroup’.
Line 83, position 4.

:

As it turns out, the import tags were not taking effect. I did some googling on this and discovered that others had the same problem. The solution is to include the needed imports on the command line. This required 4 files for DDMS.

The resulting command is:

xsd.exe /c DDMS-v2_0.xsd IC-ISM-v2.1.xsd DDMS-GML-Profile.xsd DDMS-XLink-Profile.xsd

I checked out the ResourceType, and it had a nice outlay of the various types.

public partial class ResourceType {

private CompoundResourceIdentifierType[] identifierField;

private TitleType[] titleField;

private SubtitleType[] subtitleField;

private DescriptionType descriptionField;

private CompoundLanguageIdentifierType[] languageField;
:

:

I made some tweaks regarding the output filename and namespace, then incorporated it into the code for testing.

Everything compiled, but I encountered a runtime error: “There was an error reflecting ‘Notify’.”

I enabled CLR exception reporting, and caught the problem. The exception contained more than 20 levels of nested inner exceptions! It follows the Notify to NotificationMessage to ResourceType to GeospatialCoverageType all the way down to DirectPositionType and its “text” property.

Member ‘Text’ cannot be encoded using the XmlText attribute. You may use the XmlText attribute to encode primitives, enumerations, arrays of strings, or arrays of XmlNode.

The interesting thing is that xsd.exe generated a double[] for this property while also annotating it with an XmlText attribute, thus breaking some rule in the process.

[System.Xml.Serialization.XmlTextAttribute()]
public double[] Text {
get {
return this.textField;
}
set {
this.textField = value;
}
}

We decided to just comment out the XmlText attribute, and everything then ran smoothly and passed our tests.

Conclusion

In spite of experiencing some shortcomings in both the operation and documentation of the svcutil.exe and xsd.exe tools, it is possible to generate WCF data contract classes for DDMS v2.0.

I just checked out the very first tip, and was amazed because it resolved an annoyance that I have had only too often. I asked a fellow developer whether he ever runs into such a problem, and he said it just happened to him yesterday. When I told him this tip, he thought it was awesome, and suggested that every developer in the company be notified. He also questioned why such a setting was the default in Visual Studio to begin. I asked another developer who sits next to me the same thing, and he responded with the same disbelief. I myself wonder the same thing.

So what is this annoyance and its resolution?

I often use the keyboard shortcuts to cut or copy some lines of code using [Ctrl]-[X] or [Ctrl]-[C], and then [Ctrl-V] to paste them elsewhere. But somehow, it occasionally happens that when I put the cursor on the blank line where they should be pasted, instead of pasting with [Ctrl]-[V], I accidentally hit [Ctrl]-[C] again. This can easily happen since the [C] and [V] are right next to each other on the keyboard. Anyway, once I realize nothing was pasted, I realized my mistake, and then correct my action by following up with the correct [Ctrl]-[V] combination. However, my lines of code are not pasted even then, because the previous [Ctrl]-[C] copied the blank line. This results in the annoyance that the buffered lines I meant to paste have been lost and replaced with the blank line I did not mean to copy.

The cause of this turns out to be that Visual Studio by default copies a blank line if nothing is selected. If Microsoft is reading this, then please note that this is an annoyance. I would like the default to be the opposite. And I am not the only one. My fellow developer expects it that way also. Finally, the very fact it has to be in a book  is an indication that a lot of others are annoyed by the current default as well. So please change it.

Here is the fix.

In Visual Studio 2008, go to Tools > Options as shown.

Visual Studio Tools Menu - Select Options

This will bring up the Options Dialog. Go to the Text Editor > All Languages > General pane. There will be an option with a check box titled “Apply Cut or Copy commands to blank lines when there is no selection”. It is checked by default.

Visual Studio Options Dialog - Text Editor: Copy Blank Lines

Uncheck this checkbox.

Visual Studio 2008 Options Dialog Checkbox: Apply Cut or Copy commands to Blank Lines

Now when you accidentally use [Ctrl-C] instead of [Ctrl-V], you won’t lose your buffered lines, and can correct your mistake without having to go find and re-copy (or restore and re-cut) those lines again.

Again, thanks to the author Sara Ford and her book Microsoft Visual Studio Tips. I look forward to learning more tips from the rest of her book.

Disclosure: Purchasing this book through the link in this post will provide a commission to the owner of Developer’s Quest. Thank you for your support.

There is very little documentation or experience with the other vendor’s system, so the first task was to see if we could even connect to their service. We obtained some URL’s to their services, and I set out to create a client to make the connection.

Attempting to Add a Service Reference from Visual Studio 2008

My development environment is Visual Studio 2008 SP1 on Windows XP. Since this is just a test application, I decided to make it simple and create a console application project to serve as the client.

The typical approach to connecting to a remote service is to start by adding a reference to it from within Visual Studio. This option is in the right-click menu of the project:

Menu Selection for Add Service Reference

Note that we would not use the “Add Reference” option in this case, since we need to reference a URL. Now, I didn’t think of it before, but notice that there is no menu item for “Add Web Reference”. Why is that? Perhaps because we are not working in a web site project? I will have to investigate this some other time. Either way, adding a URL-based reference has the effect of enabling you to use objects and methods in your code that map to the services and operations available via the URL. Meanwhile, we will have to use the “Add Service Reference” option.

Selecting this menu item brings up the Add Service Reference dialog.

I entered the URL, which uses the SSL-based https scheme. Note that, for this post, I will be blocking any identifying information pertaining to the remote site.

Add Service Reference Dialog - HTTPS Address

When I clicked Go, the remote server triggered an authentication dialog on my end. I was not expecting this…

Trying to Get By on Minimal Security

I have a smart-card reader, and it seemed this would only be triggered if the remote site was doing mutual authentication and wanted my certificate.

Dialog to Insert Smart Card

I canceled, but it kept popping up. Finally, after clicking Cancel four times, it stopped popping up.

Then I faced a new dialog. This was a Security Alert indicating that the remote site was using a self-signed certificate that was not trusted on my side.

Security Alert Dialog

I decided not to trust the remote site at first. I was returned to the Add Service Reference dialog, and it now reported an error:

“An error (Details) occurred while attempting to find services”

Add Service Reference Dialog - Error after declining to trust remote certificate

I clicked on the (Details) link, and it brought up a dialog explaining that it

“Could not create SSL/TLS secure channel”

because it

“Could not establish trust relationship for the SSL/TLS secure channel.
The remote certificate is invalid according to the validation procedure.”

Add Service Reference Error Dialog - Invalid Certificate

Ok, so I decided to retry and accept their certificate. I clicked Go again, bypassed the smart card prompts, and clicked Yes in the Security Alert dialog to accept it. But I still found an error reported in the Add Service Reference dialog as before:

“An error (Details) occurred while attempting to find services”.

I clicked on the (Details) link again, to see if it was any different. It was longer this time.

Add Service Reference Error Dialog

As you can see in the screenshot, it was still complaining that it “Could not create SSL/TLS secure channel”. However, now that I accepted the untrusted cert, different reasons for that failure are given. Note that none of them are for not providing a certificate via the smartcard reader, so I am not yet convinced that mutual authentication is required. Meanwhile, what are these errors?

Discovering that the Remote Service Requires SOAP 1.1

First, the content type of the response does not match that of the binding. But why are they different? Why didn’t the built-in feature provided by VS2008 figure out the correct binding?

I’m not sure what my options are now, but I noted that there was an “Advanced” button on the Add Service Reference Dialog. might let me do. But first I wanted to find out the possible cause of the errors in the rest of the response…

Along with the complaint of the mismatch, the error dialog displayed what it received from the remote host. (It is interesting that in spite of not being able to establish a secure channel, the server still returned a legible response). Inside this content, the remote host itself reported an error in what it received:

“no SOAPAction header!”.

That struck me as odd, since I seemed to recall that the SOAPAction header is only required for SOAP 1.1. In fact, looking at the XML, I can tell it is the older version of SOAP, because the new version (SOAP 1.2) no longer uses “faultcode” and “faultstring“. Plus, the namespace for this SOAP envelope is “http://schemas.xmlsoap.org/soap/envelope/“. I pulled that URL up in a browser to see if it actually resolved to anything, and it pulled up an XSD file. The first thing it says in the comments is:

“Schema for the SOAP/1.1 envelope”.

This is clearly a SOAP 1.1 response, and it contains an error complaining that it did not receive a SOAP 1.1 request. (By the way, here is an excellent article discussing SOAP 1.2 and how it differs from SOAP 1.1: http://www.xml.com/pub/a/ws/2003/06/10/salz.html – and an authoritative list of changes is here: http://www.w3.org/TR/2007/REC-soap12-part0-20070427/#L4697)

Interestingly, its faultcode uses a namespace of “http://xml.apache.org/axis”. I pulled that up in a browser and it redirected to “http://ws.apache.org/axis/”. It seems outdated, because the most recent news item at the top of the page is

“NEWS (April 22, 2006): Axis 1.4 Final is now available!”.

Hmm. Ok, so Axis is only accepting requests using SOAP 1.1 and sending me responses using SOAP 1.1. I wonder if it is even capable of using SOAP 1.2? Well, I don’t know Axis, but after scouring the Axis site, I came across http://ws.apache.org/axis/java/requirements.html, and found the following part way down:

100      SOAP 1.1           done
101      SOAP 1.2           Partial – doesn’t yet do envelope versioning or namespaces

In other words, I probably can’t expect this vendor to support SOAP 1.2 fully with Axis 1.4. But I also discovered that there is a rewrite of Axis called Axis2, and that it does in fact support both SOAP 1.1 and 1.2. One option is to see if they will upgrade. After all, it looks like Axis is no longer being updated, and Axis2 has taken its place. (Interestingly, the current version is Axis2 v1.4! This could be a source of confusion…).

Ok, so I am now facing the prospect of having to use SOAP 1.1 to connect with the remote service. However, I was merely using some built-in feature of VS2008. Why did it not detect the remote service using SOAP 1.1 and comply?

Now a new question on my mind is whether “Add Service Reference” is even capable of SOAP 1.1? If not, I will have to generate proxy classes via the commandline.

Discovering that Add Service Reference is only for WCF

After some searching, I have come to a tentative answer. According to http://msdn.microsoft.com/en-us/library/bb386382.aspx,

“The Add Service Reference dialog box enables you to add references to Windows Communication Foundation (WCF) services and ADO.NET Data Services.”

Notice no mention is made of other technologies. But then, no exclusive claim is made regarding WCF, either. So for all I know, it might be some form of marketing spin where they just aren’t mentioning the competition.

Looking further, there is a link near the bottom for “How to: Add, Update, or Remove a Service Reference” linked to http://msdn.microsoft.com/en-us/library/bb628652.aspx, and it states clearly on that page:

“A service reference enables a project to access one or more Windows Communication Foundation (WCF) services. Use the Add Service Reference dialog box to search for WCF services in the current solution, locally, on a local area network, or on the Internet.“

Could it really be that it is for Microsoft-specific technologies? Why? For some reason, I had been thinking it was for any web services accessible by additional protocol schemes other than ones such as HTTP. After all, services can serve SOAP over other transport protocols.

I pretty much exhausted my options here. But wait, that web page also indicates that the Advanced button “Displays the Configure Service Reference Dialog Box”.

Seems like now is a good time to revisit this button to see what it lets me do. Here is a screenshot showing where this button is, exactly.

Add Service Reference Dialog - Advanced Button

I clicked on the Advanced button and discovered the “Service Reference Settings” dialog. Note that the dialog title doesn’t quite match “Configure Service Reference” that was mentioned in the documentation.

Service Reference Settings dialog

Anyway, according to http://msdn.microsoft.com/en-us/library/bb514724.aspx,

“The Configure Service Reference dialog box enables you to configure the behavior of Windows Communication Foundation (WCF) services.”

Ok, so this is obviously a WCF-only feature. So I can’t use this with the Axis 1.4 remote service.

Trying to Use the “Add Web Reference” Option

But wait a minute – there is another button at the bottom of this new dialog…

Service Reference Settings Dialog - Add Web Reference Button

It is interesting that it says “Add a Web Reference instead of a Service Reference”. What exactly is the difference?

Ok, so I tried this Add Web Reference button to see if the compatibility option would be useful.

Add Web Reference Dialog

I entered the https URL into the new dialog and clicked Go. Once again, as with the Add Service Reference dialog, the remote server triggered an authentication dialog on my end seeking a certificate.

Choose A Digital Certificate Dialog

I decided not to provide one at this time, and clicked Cancel. (I didn’t have a smartcard in the reader, so I believe it pulled these up from the local store).

I was then alerted that the remote site was using a self-signed certificate that was not trusted on my side, just as before when I tried adding a Service Reference. But this time the dialog was slightly different.

Security Alert Dialog - from Add Web Reference

When I clicked No, it merely returned me to the Add Web Reference dialog. I decided to click Yes, and it proceeded to ask me again for a certificate. This time it wanted me to insert a smart card. (Perhaps it remembered I rejected all the ones listed in my local store earlier, and is therefore asking for alternatives).

Dialog to Insert Smart Card

I clicked cancel four times again, and it then returned to the Add Web Reference dialog with some feedback.

Add Web Reference Dialog - Error Downloading metadata

This result seems strange. It displays content from the URL while simultaneously reporting an error that it could not create the SSL/TLS secure channel. Since I accepted their cert, then perhaps it failed because I did not provide one back. So, I clicked Go again and provided my smart card with the cert, and it responded with this dialog:

Insert Smart Card Dialog - Card Selected

I clicked OK to continue, expecting new feedback. Unfortunately, even after providing my cert to the remote service, I still get the same failure feedback as before:

“Could not create the SSL/TLS secure channel”.

It might be that I am simply not authorized, or that my private key is not exportable, or that the VS2008 feature is running under a user that does not have access to the store where the cert is kept. It might also be that I need to install the remote cert and make it trusted rather than just accepting an untrusted cert.

At this point, though, I would like to see how things pan out if I go directly to a browser. I am just trying to create a proxy to this service, and am expecting to require minimal security to obtain the necessary information.

Trying to Access the Service with the Browser

I entered the URL into the browser and got the invalid certificate error.

Secure Connection Failed - Firefox

I decided to add a temporary exception.

Add Security Exception Dialog - Firefox

I noticed that this dialog has a button to [Get Certificate]. That struck me as relevant to the issues I mentioned before about how and where the server and/or client certificate is stored locally. It also reminds me of some google results I came across where mention is made of how IIS and IE and VS handle certificates differently, among other things. (For example, zybermark and kerrywong and an MSDN forum thread discuss this)

Anyway, I retrieved it and unchecked the “Permanently store this exception” option.

Add Security Exception Dialog - Firefox: Confirm Exception

After confirming this exception, the browser loaded up the service page, which was not much different than before:

Axis Web Service in Browser - Firefox

What is interesting here is that no security error seems apparent, yet no services seem to be available. Also, I was not asked for a certificate via the smartcard reader. Hmm.

Trying to Access the WSDL with the Browser

I have something else I want to try, so I will move on for now. I will try appending ?wsdl to the url to see if I can get what I actually need to generate a proxy from the commandline. As you can see below, I did in fact get a WSDL.

Axis Web Service WSDL - Firefox

However, notice that the lower right-hand corner displays an icon with an alert symbol with a tooltip indicating unauthenticated content:

Firefox Error Icon - Unauthenticated Content Tooltip

When I click on this error icon, I get another dialog with more information:

Page Info Security Tab - Firefox

I looked into this security error, because I am wondering why the remote service sent the WSDL information without having a fully secure connection. I am still not clear on this yet. It might be a configuration error, or it might be that they really do want anyone to be able to get the WSDL.

Likewise, if the remote site sent a WSDL file to my browser in spite of being unauthenticated, would it send it to Visual Studio?

Trying to Access the WSDL from the “Add Web Reference” Dialog

I quickly tried it, and it did fetch something:

Add Web Reference Dialog - Using URL for WSDL

It does list the service and its operations. But it does not allow me to select anything. At this point, I am thinking that I should become more familiar with how this dialog is intended to work.

According to this MSDN article:

“The Add Web Reference dialog box enables you to browse for Web services and add Web references to a Web site. A Web reference enables you to use objects and methods provided by a Web service in your code. You can search for Web services on a local computer or on servers in your company’s local area network, or you can search the Internet for commercial Web services.”

It also notes this:

“When you open a project for editing that includes a Web reference, a local proxy file for the Web service runs in an instance of the Devenv.exe process that has been started by a trusted user — yourself.”

That point might have something to do with the SSL certificate problems. Maybe not.

At this point, I am inclined to stop bothering with the security problems and just run with the fact that I can fetch the WSDL via the browser. Using the WSDL, I can generate a proxy from the commandline and use the resulting generated code in my client console application to access the remote service. But it still bothers me, because the previous SSL failures might be an indication that even after I have the proxy code for connecting, I won’t be able to complete the secure connection to make use of the operations on the service.

This article has gotten long, so I will resume this adventure in a later post.

(to be continued…)

As a developer, I am typically engaged in doing software engineering, web development, and architectural analysis, among other things. And in that capacity, I often find myself engaging in a quest to gain competence or expertise in a new or existing technology, technique, language, framework, platform, tool, standard, or product that might or must be used in a project I am or might become involved in. I then take some time to read up on pertinent topics, study the relevant standards, read about lessons learned in the blog postings of others, and think about the implications of all this as it applies to the task at hand. As a result, I gain understanding and confidence. But I haven’t been recording much of what I have learned. Other developers I interact with occasionally express an interest in benefitting from what I have learned, without having to find all the resources all over again on their own. They could use a map to save them time.

I hope the record of my discoveries here provides just such a map to aid others who are on a similar quest.