Monthly Archives: August 2012

WCF contract guidelines

Designing WCF services means you have to specify the contracts of the functionality that you want to expose. This blog entry contains some notes about the guidelines I follow.

Be explicit

The Name and Namespace properties control the name and namespace of the elements in the WSDL. Especially namespace is important because when you send SOAP messages, the elements need to be namespace qualified so that they can be serialized/deserialized correctly.

Namespaces follow the URI format, like http://schemas.dunatis.be, but are not actual addresses – they just represent the domain of your company, which is guaranteed to be unique.

In general, I recommend to:

  • explicitly specify the Name property, as to clearly distinguish the internally used names from the ones that will be exposed publically. Changing an internal property name will then not break the contract!
  • explicitly specify the Namespace property, because if you don’t specify the namespace, it defaults to http://tempuri.org – so it’s recommended to specify you own namespace – one that is relevant to your application.
  • explicitly specify the IsRequired property
  • explicitly specify the Order property, because if you don’t, the schema will be generated in alphabetical order. As a result, if you add new properties they will not appear at the end of the schema, which may cause issues.

Strict versus lax versioning

If you don’t have control over the clients that consume your service, you have to assume that contract changes would break their implementation. After all, a contract change means that the XML message changes, and clients may not be able to deal with that. In that case, use strict versioning, so that the original contract is not changed and instead, a new version is created and made available.

On the other hand, if you control the clients, you may choose lax versioning, and in this case you are allowed to modify the existing contract (in a non-breaking way) because it won’t break the clients using it.

For versioning I use a date indication yyyy/mm instead of version number, because it’s a W3C standard and it has more meaning.

Here’s a nice article that discusses versioning rules in detail. And this series is an excellent explanation about versioning strategies: part 1, part 2 and part 3.

Case sensitivity

Important to notice is that when contracts are processed, the WCF infrastructure is case-sensitive to both the namespaces and the names of data contracts and data members. Therefore I use:

Of course, this is personal taste.

Examples

Service contracts

[ServiceContract(Name = "CustomerService",

Namespace = "http://schemas.dunatis.be/2012/08")]
public interface ICustomerService
{
[OperationContract(Name = "GetCustomerDetails")]
GetCustomerDetailsResponse GetCustomerDetails(

GetCustomerDetailsRequest request);
}

The service contract has an explicit name and namespace. Namespace also has a version specification; this allows me to have a second version of the service later on in case breaking changes were needed in the contract (strict versioning).
 
The operation contract has an explicit name.
 

Message contracts

[MessageContract(WrapperName = "GetCustomerDetailsRequest",
WrapperNamespace =

"http://schemas.dunatis.be/customer/getcustomerdetailsrequest/2012/08")]
public class GetCustomerDetailsRequest
{
[DataMember(Name="Customer", IsRequired=true, Order=0)]
public Customer Customer { get; set; }
}

The message contract has an explicit wrapper name and namespace. Namespace also has a version specification.

The data members have an explicit name, and also Order and IsRequired are specified.

Data contracts

[DataContract(Name = "Customer", 
Namespace = "http://http://schemas.dunatis.be/customer/2012/08")]
public class Customer
{
[DataMember(Name = "FirstName", IsRequired = true, Order = 0)]
public string FirstName { get; set; }
}

The data contract has an explicit name and namespace. Namespace also has a version specification.

The data members have an explicit name, and also Order and IsRequired are specified.

Service implementation

[ServiceBehavior(Name = "CustomerService",
Namespace = http://schemas.dunatis.be)]
public class CustomerService : ICustomerService
{
public GetCustomerDetailsResponse GetCustomerDetails(

GetCustomerDetailsRequest request)
{
throw new NotImplementedException();
}
}

The service behavior has an explicit name and namespace.
 

Using constants

Instead of writing every namespace multiple times as a string, you could define constants and use these. Using the constant ensures that the namespace is the same for the contract and the service. If you make it available in a shared library, it also remains consistent across all of your projects/services/solutions.

public class NamespaceConstants
{
// Ensures consistency in the namespace declarations across services
public const string Namespace = “http://schemas.dunatis.be/2012/08;
}

[ServiceContract(Name = "CustomerService",             
Namespace = NamespaceConstants.Namespace)]
public interface ICustomerService
{
[OperationContract(Name = "GetCustomerDetails")]
GetCustomerDetailsResponse GetCustomerDetails(
GetCustomerDetailsRequest request);
}

 
Advertisements

A list of useful libraries

One of my previous blog entries was about productivity tools, more specifically a list of tools I like to use during development. In this post I will do the same, but about libraries and frameworks I like to use. After all, the first thing you need to do before you start developing is to check whether it already exists – so that we don’t reinvent the wheel! So here goes… and of course, I’ll update this list if needed.

EPPlus

“EPPlus is a .net library that reads and writes Excel 2007/2010 files using the Open Office Xml format (xlsx).”

Reading and writing excel files is something I already needed to do a number of times, and this free library is the best I have found!

Fluent validation

“A small validation library for .NET that uses a fluent interface and lambda expressions for building validation rules for your business objects.”

Validation is part of every development you do, and this free library allows you to validate objects in a fluent way, using external validators.

StructureMap

“StructureMap is a Dependency Injection / Inversion of Control tool for .Net that can be used to improve the architectural qualities of an object oriented system by reducing the mechanical costs of good design techniques. StructureMap can enable looser coupling between classes and their dependencies, improve the testability of a class structure, and provide generic flexibility mechanisms. Used judiciously, StructureMap can greatly enhance the opportunities for code reuse by minimizing direct coupling between classes and configuration mechanisms.”

Dependency injection is a technique I use by default in almost every application; and StructureMap is my favorite tool for that.

SQLite

“SQLite is a software library that implements a self-contained, serverless, zero-configuration, transactional SQL database engine. SQLite is the most widely deployed SQL database engine in the world.”

An excellent standalone SQL server database engine, which I use for standalone client applications that need database functionality at the client’s side.

WPFLocalizeExtension

“The LocalizationExtension is the easiest way to localize any type of DependencyProperties or native Properties on DependencyObjects under WPF & Silverlight.”

This free library takes care of localizing any resource in your WPF/SIlverlight application based on the culture being set. It can be applied on the fly, which means your application doesn’t need to be restarted when culture is changed!

Prism

“Prism provides guidance designed to help you more easily design and build rich, flexible, and easy-to-maintain Windows Presentation Foundation (WPF) desktop applications, Silverlight Rich Internet Applications (RIAs), and Windows Phone 7 applications. Using design patterns that embody important architectural design principles, such as separation of concerns and loose coupling, Prism helps you to design and build applications using loosely coupled components that can evolve independently but that can be easily and seamlessly integrated into the overall application. These types of applications are known as composite applications.”

I have used this library to build WPF applications as a collection of loosely coupled and independent components. It takes a while to learn it, but once you get it, combined with MEF and MVVM it’s a powerful environment to write flexible applications.

Log4Net

“The Apache log4net library is a tool to help the programmer output log statements to a variety of output targets. log4net is a port of the excellent Apache log4j™ framework to the Microsoft® .NET runtime. We have kept the framework similar in spirit to the original log4j while taking advantage of new features in the .NET runtime.“

Whenever I need to log (and that is, well, almost always), I use log4net. It’s a powerful and flexible logging framework, that by default contains everything you need; and in case you need more it’s extensible by writing your own log4net adapters.

SignalR

“Async library for .NET to help build real-time, multi-user interactive web applications.”

I used this library because I needed real-time feedback on a web site from a long running process. It mimics a persistent connection between the UI of a web site and the backend.

GalleryView

GalleryView is capable of creating a wide variety of gallery types, and provides an extensive set of options to the user. Not only will the user be able to adjust photo and thumbnail sizes, and transition speeds, but he will also have the ability to choose from a selection of element positions, transition styles and other features.”

For a site I had to make I needed a picture gallery jquery plugin. There are so many free libraries available, and I tested a number of them, but I finally choose this one because it was very extensive and works very nice!

Operating devices in network

In a previous post Streaming Spotify to DNLA device over network, I managed to play Spotify on the laptop but stream the sound to my television or receiver over the network. This is only one example of the power of controlling devices that are connected to a network.

My setup is: Telenet modem is connected to:

  • a switch, which is connected to two laptops
  • a switch, which is connected to the Telenet digicorder; the Panasonic Vierra television and the Yamaha receiver
  • an iPad (wireless)

Now, because my iPad is also connected to the network (wireless connection), this opens even more possibilities. In fact, I’m experimenting with ways to make my iPad the central remote device that controls every other device hooked on the network.

Using the iPad as remote control for the receiver

As a first example, it is possible to control the receiver using the iPad. First download the AV Controller for iPad application from the app store. If you start it, it will try to find a device connected to your network. In my case it finds the Yamaha RX-V771 receiver:

remote1

Select the device you want to control, and from this moment you are able to manipulate the device on your iPad from anywhere, as long as it’s connected to the network. For example, selecting the tuner will start playing the radio station:

remote2

Select DSP to decide the sound setting, in my case I have selected 7ch Stereo so that all 7 speakers are used:

remote3

You can even send music that’s on your iPad to the receiver!

Using the iPad as remote control for the television

To use the iPad as a remote control for the television, download the Viera Remote for iPad application from the app store. If you start it, it will try to find a connected Panasonic Viera television. In my case, it finds:

viera1

Select it, and now you can control your television on the iPad, for example changing volume or channel:

viera2

Or even show images from your iPad on the television:

viera3

 

Watching television on the iPad

Another example is Yelo, which is an offering of my internet provider Telenet. It allows you to watch television on any ‘smart’ device, like a laptop, iPhone, iPad etc, and also remotely program the digicorder:

yelo

These are the first of my experiments, and at this moment it’s still a bit limited; but as these remote applications will become more and more powerful, the possibilities will be fantastic!