An Engineer

As Ben mentioned in the first installment (I am a guest blogger for this installment), part of the original decision to build Phanfare on Microsoft’s .NET platform was the ease with which Visual Studio lets you build web services and clients that integrate with those services.

Building a .NET web service method within Visual Studio isn’t really much different than writing any other function. You make it a web method by simply adding the “[WebMethod]â€? attribute. Visual Studio takes care of everything else under-the-hood. For example, here is the C# web service definition of an imaginary method:

[WebMethod]
public PhanfareAlbum GetAlbum(string sessionId, long albumId, bool getImagesToo, out int albumVersion, out string albumName, out PhanfareImage[] images)
{
…
}

Easy, huh?

Using that web method in another application (like the Phanfare Photo client) is also simple. By referencing the web service in the client application’s Visual Studio project, Visual Studio will fetch the service’s WSDL document (Web Services Definition Language — an XML document that describes the methods that the service provides) and generates a proxy class that contains the stub methods — methods that look just like the ones you wrote on the service side. This generated code handles all the icky details of performing the under-the-hood magic to invoke the method on another machine across the network, while making it look like a local method call to you, the programmer.

The web method declared above is invoked from a C# client application like this:

PhanfareWebService ws = new PhanfareWebService();
string albumName;
int albumVersion;
PhanfareImage[] images;

// Now use the info!
Debug.WriteLine(String.Format(“This album was created on {0}â€?, myAlbum.createdDate.ToString()));

Facile!

Now for the Mac side of the story.

To make the Phanfare Photo Mac client work, it would have to talk to the same SOAP web service as the Windows client. When we first began looking at the Mac platform, we were excited to have read somewhere that OS X supports SOAP-based web services. However our excitement quickly dissipated when, in typical Apple style, we couldn’t find any coherent, useful documentation on how to integrate a Cocoa application with a SOAP-based web service (if you find some, please let us know. Here is Apple’s documentation. Now go build a complex web service client on the Mac. Have fun.). From what I could gather you put all of your parameters (no complex user-defined types, please) into a hash table (so if I get the parameters wrong I can still compile my client with no errors? Wonderful.), pass it to some web service invocation function, and then get a hash table back. Oh and if you run Apple’s WSMakeStubs application on Phanfare’s WSDL you basically get a lot of methods that have nothing but comments stating that complex types are not supported. Great.

After quickly realizing that Apple’s limited support for web services wasn’t going to make our lives any easier, we started looking for alternatives (to be honest Apple’s support seemed so lacking that we never even tried to build a test application before looking elsewhere). What we found was gSOAP, by Robert van Engelen at Florida State University. We decided to use gSOAP for several reasons: it is open source and distributed under the very favorable gSOAP License, it is extremely well documented, it is widely used, and it has an extremely active user community. Oh, and it works on the Mac (it even came with a Mac-specific makefile).

The primary complaint we had with gSOAP was that it did not integrate seamlessly with Objective-C/Cocoa, the environment in which we’d chosen to develop the Mac client. While gSOAP worked quite well in our tests, calling it from Objective-C/Cocoa looked something like this:

struct soap *mySoap = soap_new2(SOAP_IO_DEFAULT, SOAP_IO_DEFAULT);

NSString albumName = [[NSString stringWithCString:soapOutParameters->albumName] retain];
int albumVersion = soapOutParameters->albumVesrion;

Clearly this will become very tedious very quickly and is not conducive to rapidly developing an application (especially on a platform that’s new to you and especially when you make lots of web service calls, like we do). What we needed was a way to make the web service calls look like the calls we were used to, but using Objective-C/Cocoa types.

To achieve this, we modified the gSOAP compiler (the thing that generates the web service stub methods from the WSDL — the same thing Visual Studio does when you add a web service reference to your project) to emit Objective-C in addition the code it already generates. This new code includes Objective-C class equivalents for all user-defined classes, using Cocoa/Objective-C types where appropriate (e.g., for member strings, arrays, booleans, dates, and other user-defined classes). It also contains an automatically generated Objective-C proxy class that implements Objective-C methods that look just like the original web service methods we’ve come to know and love, but using Objective-C/Cocoa types. These methods contain all the yucky glue (like in the example above) needed to convert between the C and Objective-C/Cocoa types (again, for strings, dates, arrays, binary data and such).

Now the web service call from Objective-C looks like this:

// PhanfareWebService is the Objective-C “proxyâ€? class
PhanfareWebService *ws = [PhanfareWebService init];
int albumVersion;
NSString *albumName;
NSArray *images;

// Now use the info!
NSLog([NSString stringWithFormat:@�This album was created on %s�, [[myAlbum createdDate] description]]);

Much nicer, huh?

In addition the proxy layer does a few other nice things, like cleaning up some minor rough edges in gSOAP (e.g., beautifying enumeration types and values and such) and providing support for pooling multiple gSOAP contexts to simplify multithreading.

So, after initial excitement, then disappointment in Apple’s support for SOAP web services, gSOAP, with the addition of our own Objective-C/Cocoa layer, has turned out to be a very nice alternative. It has caused us very few headaches (and most of those were from bugs in our own generated code) and is now as easy to code against as Visual Studio generated stubs on the Windows side. Granted, we don’t have the right-click-and-choose-Update-Web-Reference level of integration and ease that Visual Studio provides. But we’ve come darn close.

GUI apps are like sausages, it is better not to see them made. Apple and Microsoft have a fundamentally different approach to sausage production. Visual Studio integrates its GUI designer right into the IDE. On the Mac, you use Interface builder, a separate application, to create your GUI elements.

The integration of GUI design within Visual Studio follows from Microsoft’s approach to GUI synthesis. The drag-and-drop GUI designer generates C# code that is then compiled into your application, and that code can be edited by the developer. Apple’s Interface Builder generates data files that are read in at runtime to display GUI elements. Considering that the code generated by Visual Studio’s GUI builder is in fact data to the Common Language Runtime after it is compiled into IL, there would seem to be a general equivalence between the techniques. One person’s code is another person’s data. But in terms of developer workflow and customization, the Visual Studio approach is far more efficient.

Here is how you create a button in each environment.

Visual Studio:


1. Drag a button onto the window
2. Double click the button
3. Write code


Xcode/Interface Builder:


1. In Xcode, go to your window controller header file, add two lines for your outlet and action
2. Switch to Interface Builder
3. Drag a button onto the window
4. Change tab to the class browser
5. Find your window controller and re-read the file to get your updates
6. Change back to the object browser
7. Apple-drag from the window controller instance to the button
8. Select the outlet you defined before and click 'Connect'
9. Apple-drag the button onto the window controller instance
10. Select the action you defined before and click 'Connect'
11. Switch back to Xcode and into your window controller code file
12. Add the action method definition and write code


I soon came to dread the UI design work involved with Phanfare Photo for the Mac. The Mac may look nice on the outside, but it is not so nice on the inside.

There is an argument for separating out the GUI design component to a separate application. Ideally, this would allow someone more artistically gifted than I am to do the GUI work and hand me back a bunch of GUI design data objects with a big red bow. But for this separation to work, the GUI designer (and I mean the person) needs to be able to work without requiring fine-grained communication with the application engineer (that would be me).

The Apple approach fails here in that the programmer must muck around in the designer stuff to get anything working (sometimes not getting the behavior quite right), and because the set of built-in GUI controls is so limited that the GUI designer must constantly ask the programmer to create custom controls. There really is nothing wrong with the idea of separation, if well implemented. Microsoft’s new venture into the designer/programmer split with Avalon and their designer tool Sparkle looks promising.

There are two parts of GUI design: the ‘fun stuff’ (laying out the UI) and the ‘boring stuff’ (implementing custom controls/behaviors). That was the layout, now on to the behavior:

As I said, in Visual Studio, the GUI designer generates code that you can tweak by hand if needed. In Interface Builder, serialized objects are written out to be loaded when your application runs. This means that if you don’t like the way Interface Builder does something, you have to rewrite your entire GUI by hand (something I found myself doing with shocking regularity).

One of the nice features of.NET is that it has dozens of built-in controls (over 100 in the latest version) and thousands of custom controls built by users. And because controls in .NET are expressed in text-based code, they are easy to tweak and display on web pages, making for a vibrant user community.

The Mac, on the other hand, comes with a very limited set of controls. There are the basic buttons, grid views, etc, but for anything more than a text editor this isn’t enough. Interface Builder provides about 25 built-in controls (they didn’t even get a date picker until Tiger, and even then it’s almost unusable!) and with the size of the Apple developer community it’s hard to find anything on the net.

In the end, I found myself always writing my own controls. Now, to be fair, I had to do this occasionally in .NET too, but with far less regularity.

In the end, both Apple’s approach to GUI design and Microsoft’s can produce modern GUIs, but Apple’s approach required more effort on my part and significantly more hours spent in the not-so-sweet-smelling sausage factory.