I'm designing some services and I would like to get some feedback about the conventions I'm using.
For all operations, I always define a 'Context' object and a 'Result' one, because of the following advantages:
extensibility: I can add parameters to the context or objects to the result without changing the interface
compactness: I only have a single object in the definition, even if I need many parameters
Example:
[OperationContract]
DoSomethingResult DoSomething(DoSomethingContext context)
Anyway, I'm not really sure that this is the best way to do it because of the following reasons:
overhead: I always wrap the response properties into an object. Sometimes, the Result object has no properties
versioning: WCF has built-in versioning for contracts, and maybe it could be better to use a different version to inform about the difference
In fact I use the same technique with normal methods too, so it would be important for me to get some feedback, advices, critics and so on and so forth.
Thank you
I think that's a perfectly legitimate way to write your contracts. I've worked on a number of projects with these sort of contracts and it is has been a pleasure - very easy during development (just add a property to the object and you're done), a straightforward and clear pattern that applies to all services, and allows for things like a single validation method for all operations.
In response to your concerns:
I don't think the overhead of creating an empty object is at all significant. Don't worry about this unless it becomes an issue.
If the Result object has no properties (i.e. you aren't returning anything) then simply return void. You aren't gaining anything by returning an empty object.
You can (and probably should) version these objects as you version your contracts. What you are doing in no way precludes you from versioning your objects.
Please note that versioning objects does not mean changing them to DoSomethingResult_v1, DoSomethingResult_v2 as I've seen before. You should version with namespaces; it makes things clearer and cleaner. Just put a version in the XML namespaces in both the operation contract and data member attributes.
I don't think there are any performance concerns here, and the code looks easy to work with from the code-owners perspective.
My big concern is that it isn't at all clear from the consumers perspective how your service works. They would have to rely on separate documentation or error messages.
It would be much easier for someone unfamiliar with your code (i.e. just downloaded the WSDL) to consume your service if the parameters that it required were declared. You also get a good degree of validation out of the box.
To illustrate:
[OperationContract]
DoSomethingResult DoSomething(DoSomethingContext context)
vs
[OperationContract]
[FaultContract(typeof(CustomerNotFoundFault))]
Customer GetCustomer(UInt32 customerId)
This point is mostly relevant to the design of APIs. Where this isn't so relevant, is where you are both the author and the consumer of the service.
I totally support Kirk Broadhurst's suggestion of using namespaces for versioning. I use that and it works well.
EDIT: on a second reading, I think I misread your post. I was assuming here that your parameter and return value objects were some generic object that you use across all services. If indeed they are specific to each service, then that's a great approach which I've used successfully on many occasions. You'll do well with it.
Related
WCF beginner's question: I've been told that changing the WCF contract is costly and requires constant maintenance (recreating the proxy in the client side), and therefore the preferred method is having one very generic point-of-contact method (which decides how to act, say, according to a given enum parameter).
This sounds quite smelly to me, but I haven't been able to find any information about this issue (bad choice of search keywords? probably).
Any advice, or maybe a useful link?
Thanks!
You don't need to generate the proxy again, you can simply ensure the client is built with the correct interface version. If you're very careful and only add methods, not remove or modify, that works just fine too. That's a lot of responsibility to manage, of course.
To use an interface rather than generate a client proxy, check my question from a while ago:
WCF Service Reference generates its own contract interface, won't reuse mine
You are confusing some terms here and I think you might be referring to a known flaw which has been fixed in .Net 3.5 SP1.
Recreating the WCF proxy used to be an expensive operation at runtime. This has been improved in .Net 3.5 to cache the proxy objects transparently MSDN Blog.
If you are referring to the "code maintenance" of the proxy, then all you are referring to is implementing an interface at the client. If you need to maintain the interface then this comes back to basic SOA. If your services provide access and as much information as possible, assuming that your service will be used for purposes you haven't yet considered then you will likely not need to modify the interface after it is created. You should also consider your upgrade paths as well.
Juval Lowy has a good discussion about this problem in his book which is a little dense but has some pretty good information in it.
A piece of advice: WCF has a whole lot of features designed to make your code really simple and elegant. If you are worreid about maintenance, what you may be driven to do is write an interface:
string ServiceMethod(string xml) //returns XML
Don't do this. Take the time to design a good maintainable interface and a good data/message contract. This will let WCF provide all the extras you get for free when hosting your service for interaction.
Generic (as in non-specific, monolithic) interfaces are hard to understand and program to. The reason not to define a single method as the API is that it's impossible for clients to understand what's going on, and when you change the (implicit) API of this interface, your clients will break in horrible ways that you won't detect at compile time.
It's been a while since I touched WCF, but if your clients are internal (same codebase, versioning and deployment schemes), then regenerating the WCF proxies is very easy, and having a "strong" detailed API will make your life so much easier than a generic one.
It depends on what kind of change you mean. Change to the service contract is indeed costly and should not happen. Service contracts are (or should be) at a sufficiently high level of granularity that change is very rare.
More common are changes to the types which are exposed on the service. These changes are more common and therefore you do need to approach your change in such a way as to avoid breaking existing clients if possible.
There are several ways you can do this, such as exposing your types polymorphically using an interface, but the simplest way is to simply ensure that changes to your types on add new data member fields and make the new fields non-mandatory. If you can limit your changes to these then this is has the lowest impact to existing clients and enables new clients to use the new fields.
Hope this helps.
This is true that modifying the service contract (interface) would also required the client to recreate the proxy class at their end using the new published WSDL and may even require the client to change their code as par the new proxy. I don't think you can create such a generic interface that can handle all changes further down the road in the contract. A contract has to be written very carefully so that it doesn't change often and if there is a need to change the contract then it is better to deploy the service with a different version so that your old client can still work with the old version.
I'll start in the way most people seem to have taken to, on here....
So I was....
Nah thats gash. I'll start again (might lose a few points for not being straight to the point but wth)
Right,
I have inherited a framework which utilities WCF to provide some operation and data contracts.
This might be irksome to some, but I haven't done enough reading on SOA or WCF to garner knowledge about effective patterns (or best practices..) and therefore, don't really have a weighted opinion on my team on this subject, as of yet.
As an example in the framework I am using, there are a bunch of models for users.
Specifically we have the following models (data contracts):
users_Loaded
users_Modify
users_Create
For all intents and purposes these data contracts are exactly the same - in so much that other than their "type", they have the same members and properties etc, and therein is my first problem.
The operations which utilise the data contracts have parameters which match the data contract you might want to perform some action with
Thus the operations utilising the data contracts:
CreateUser(users_Create createdUser, ..., ...)
ModifyUser(users_Modify modifyUser, ..., ...)
GetUser(out users_Load loadedUser, .., ...) (out parameters on left most side of parameter list to boot!?)
Maybe the intent was to delineate the models and the operations from one another, but from my experience a method and its parameter list, usually give a good indication of what we are going to need to do.
Surely one data contract would have sufficed, and maybe even one operation (with a operation type parameter)
Am I missing the point. Why would you do what I have described?
Thanks.
i
It sounds like the previous developer(s) were either trying to implement some bastardized Command pattern, or they flat didn't understand WCF.
Long answer short, yes, from what you've said, you should be just fine combining these into a UserDto class that is the DataContract for all three operations. svcutil, for its part, should have no trouble generating one DataContract class on the client side that will work for all three OperationContract methods (or, since you seem to control both sides of this service, just use a shared assembly containing your DTOs on both client and server).
Although this is a fairly common problem, I am struggling with what the best way to approach it (if it needs approached at all in this case).
I have inherited a website (ASP.NET, C#) part of which contains a class full of static methods (it's a very large class, honestly). One method in particular is for sending e-mails. It has every possible parameter I can think of and it works well enough. However, the internals of that particular method are rather cumbersome to manage and understand due to the fact that everything is shoved inside - particularly when most of the parameters aren't used. In addition, it is somewhat difficult to handle errors, again, due to all the parameters for this one method.
Would it make more sense to actually have an EMail class which is instantiated when you want to send an e-mail? This just "feels" more right to me, though I can't full explain why. What are your thoughts on the way to go in this particular case? How about in general?
Thanks.
What you're describing sounds like an example of the aphorism, "You can write FORTRAN in any language."
A massive class full of static methods is often (not always) a sign that somebody just didn't "get" OOP, was stuck in a procedural-programming mindset and was trying to twist the language to do what he wanted.
As a rule of thumb: If any method, static or instance, takes more than about 5 parameters, it's often a sign that the method is trying to do too many things at once, and is a good candidate for refactoring into one or more classes.
Also, if the static methods are not really related, then they should at least be split up into classes that implement related functionality.
I'm actually wondering why you'd have a "send e-mail" method at all, given that the System.Net.Mail namespace handles just about every case, and is configurable via the app.config/web.config file, so you don't need to pass it a server name or port. Is this perchance a "notification" method - something that individual pages are supposed to call out to in order to send one of several "standard" messages based on templates with various values filled in, and certain headers/footers automatically added? If so, there are a number of designs for this type of interaction that are much easier to work with than what you seem to have inherited. (i.e. MailDefinition)
Update: Now having seen your comment that this is being used for exception handling, I think that the most appropriate solution is an actual exception handler. There are a ton of resources on this. For ASP.NET WebForms, I actually took the one Jeff Atwood wrote years ago, ported it to C# and made a few changes (like ignoring 404 errors). There are a number of good links in this previous question.
My preference these days is just to treat exception handling (and subsequent e-mailing of exception reports) as a subset of logging. log4net has an SmtpAppender that's quite capable, and you can configure it to only be used for "fatal" errors (i.e. unhandled exceptions - in your handler, you just make a LogFatal call).
The important thing, which you'll no doubt pick up from the SO link above and any referenced links, is that there are actually two anti-patterns here - the "miscellaneous" static class, and catching exceptions that you don't know how to handle. This is a poor practice in .NET - in most cases you should only catch application-specific exceptions that you can recover from, and let all other exceptions bubble up, installing a global exception handler if necessary.
Here are the Microsoft guidelines for when to use static types, generally.
Some things I would add, personally:
You must use static types to write extension methods.
Static types can make unit testing hard as they are difficult/impossible to mock.
Static types enforce immutability and referentially transparent functions, which can be a good design. So use them for things which are designed to be immutable and have no external dependencies. E.g., System.Math.
Some argue (e.g.) that the Singleton pattern is a bad idea. In any event, it would be wrong to think of static types as Singletons; they're much more broad than that.
This particular case has side-effects (sending e-mails) and doesn't appear to require extension methods. So it doesn't fit into what I would see as the useful case for static types. On the other hand, using an object would allow mocking the e-mail, which would be helpful for a unit test. So I think you're correct to say that a static type is inappropriate here.
Oh my gosh yes.
It sounds like its an old Classic ASP app that was ported.
It violates the single responsibility principle. If you can refactor that class. Use overloading for that function.
That is an example of the Utils anti-pattern.
It is always a good idea to separate those methods according on their responsibility. Creating an Email class is definitely a Good Idea™. It will give you a much nicer interface to use, and it allows you to mock out the Email in tests.
See The Little Manual of API Design, which describes the benefits of classes having minimal constructors and lots of getters/setters over the alternative of using constructor/methods having many parameters.
Since most of the parameters of the methods you mention are not used, a better approach is to use simple constructors that assume reasonable default settings for the internal variables. Having setter methods allows you to then set the few parameters (and only those parameters) that require non-default values.
I am in the process of converting all my parameters, return types, classes to all use Interfaces instead ie. IUser instead of User.
Besides the extra code required to maintain this, are their any negatives to this approach?
This isn't an uncommon approach, especially if you do a lot of mocking; however, it has issues with:
data-binding support (especially when adding rows to tables)
xml serialization (including comms WCF, asmx, etc), or contract-based serialization in general
You need to figure out whether the advantages of mocking etc outweigh these issues. It might be that you use IUser in most scenarios, but (for example) at the comms layer it may be simpler to use raw DTOs rather than interfaces.
Note that I'm applying the above to classes. If you involve structs, then remember that in most cases this will involve boxing too.
Overall, this will give you all the advantages associated with loose coupling, so in general I consider this a huge win. However, since you asked about disadvantages, here are some minor ones I can think of:
There's more code involved becase you have both the interface declaration and at least one implementation (you already mentioned this, so I'm just including it for completeness sake).
It becomes more difficult to navigate the code because you can't just Go to Definition to review what another method does (although I'm told that Resharper helps in this regard).
In some cases there may be more in a contract than mere semantics, and an interface can't capture that. The classic example from the BCL is that if you implement IList, you must increment the Count property every time you add an item. However, nothing in the interface forces you, as a developer, to do this. In such cases, abstract base classes may be worth considering instead.
Interfaces are brittle when it comes to adding new members. Once again, you may consider abstract base classes instead.
I once went through a phase of this, but in practice found that for anemic data objects (i.e. POCOs) the interfaces weren't required.
In practice it can be useful to have interfaces to define a contract for behaviour, but not necessarily for attributes.
In general I'd suggest you let your unit testing guide you. If you have rich objects throughout your application then you'll most likely need interfaces. If you have POCOs, you most likely will only need them for controller-style classes.
Interfaces are very good thing, but applying them to all artifacts is overkill. Especially in java you would end up with two distinct files (interface + implementation). So (as always), it really depends :)
Regarding 'interface or not-to-interface'
I would not have domain-objects have interfaces (e.g. User). In my view for code comprehension it is rather confusing (for domain objects interface often would define getter methods). Recently it was a real pain to get unit-tests in place and having domain-object-interfaces. I had to mock all these getters and getting test-data into the domain-object mocks was rather cumbersome.
The opposite is true for coarse grained services and api interfaces. For them I always have an interface from start on.
In more internal-module encapsulated scenarios I start without interface and after some code-evolution if necessary react and do an extract-interface refactoring.
'I' prefix for interface artifact names
I also used to work with the Ixxx prefix but I (happily) got rid of it nowadays for following reasons:
It is difficult to keep up all this 'I' naming convention in an evolving codebase, especially if you refactor a lot (extract-interface, collapse-interface etc.)
For client code it should be transparent whether the type is interface or class based
The 'I' can make you lazy about good interface and classnames.
Not so much a disadvantage but a warning. You would find that to achieve good component de-coupling you will need to use a Dependency Injection framework (that is if you want to keep your sanity and have some sort of idea what your interfaces map to).
What also tends to happen is that non-trivial classes sometimes naturally convert into more than one interface. This is especially true when you have public static methods (i.e. User.CreateAdminUser). You will also find that it's harder to get an interface to hold state AND do stuff. It's frequently more natural for an interface to be either one or the other.
If you get stuck in the process, do take a minute a do some research into what's an appropriate paradigm that you are trying to implement. Chances are someone has solved this particular design pattern before. Considering this is a big refactoring job, you might as well take extra time and do it properly.
avoid the ISuck prefix.
edit: the ISuck convention is a manifestation of the Systems Hungarian notation applied to type names.
PREAMBLE:
This is by far the longest post I've left here...but I think it's required in this case.
I've had questions about these kinds of things for a long time: how to name assemblies, and how to divide up classes within them.
I'd like to give an example of an application here, with only a bare minimum of classes to demonstrate what I'm trying to understand.
Imagine an application that
Accepts client messages, store them in a db, and then later dequeues them to an MTA server.
It's a Web application that has both an ASP.NET interface to write a message + attach attachments.
There's also a Silverlight client, so the webapp exposes a ClientServices WCF ServiceContract, with one OperationContract (SaveMessage).
There's also a Windows client...does the same thing as the Silerlight contract.
OK. that should be enough of a fake scenario to demonstrate my cluelessness.
The above will need the following classes:
Message
MessageAddress
MessageAddressType (an enum with From, To)
MessageAddressCollection
MessageAttachment
MessageAttachmentType
MessageAttachmentCollection
MessageException
MessageAddressFormatException
MessageExtensions (static extension for Message)
MessageAddressExtensions (static extension for MessageAddress)
MessageAttachmentExtensions (static extension for MessageAttachment)
Project.Contract.dll
My first stab at organizing the above into the right assemblies would be observing that Message, MessageAddress, MessageAttachment, the enums needed for its properties (MessageAddressType, MessageAttachmentType) and the collections needed for them(MessageAddressCollection, MessageAttachmentCollection), are all to be marked as [DataContract] so that they can be serialized between the WCF client and the server.
Being common to both, I think I would move them into a neutral shared assembly called Contract.
Project.Client.dll
I'll need a Client proxy of the server [ServiceContract], that refs the classes in the Contract.dll.
So now the server, which also refs Project.Contract.dll could now save serialized Messages received from a WCF Client, and save them into a db.
Plugins
Next I would realize that I would like to have these objects be processed server side by 3rd party plugins (eg; a virus checker)...
But plugins should have readonly access (only) to the variables in order to check the variables, and throw errors if they see something they don't like.
So I would think about going back to have Message inherit from IMessageReadOnly ...but where to put that interface?
Project.Interfaces.dll
If I put it in an assembly called Project.Interfaces.dll, this would work for the plugins who could reference that without having a reference to Contracts.dll...but now the client has to reference both Contracts assembly AND Interfaces...doesn't sound like a good direction...
Duplicate Objects
Alternatively, I could have two Messages structures (and duplicate the other MessageAttachment, etc. classes as well)...one for communicating from client to server (in the Contracts.dll), and then use a second ServerMessage/ServerMessageAddress/ServerMessageAddressCollection on the server side, which inherits from IMessageReadOnly, and then it would appear that I am closer to what I want.
With duplicate objects, plugins are limited in access, while Server BL, etc. has full access for types relevant to its work, all while the client has different but identical objects...
In fact...they I should probably start considering them as non-identical, making it clearer in my head that the objects are just there to talk to clients, ie Contract/Comm objects)...
The Website UI
which brings up ...hum...if there are two different Messages, and they have now different properties...which one is the most appropriate for using to back the ASP.NET forms? The ServerMessage object seems fastest (no mapping going on between types)...but all the logic has already been worked out against client message objects (with different properties and internal logic). So would I use a ClientMessage, and map it to a Servermessage, to keep the various UI logics the same, across different mediums? or should i prefer mapping, and just rewrite the UI validation?
What about the third case, Silverlight...The Contracts assembly was a Full Framework assembly...which Silverlight can't ref (different framework/build mechanism)....so the assembly that i have on the Silverlight side might be exactly the same code, but has to be a different assembly. How does that work out?
What exactly to Consider as DataContract?
Finally...and this is, I swear, near the end of my huge question...what about the pesky extra classes that are not clearly DataContract?
For example, The MessageAddress was a DataContract. Ok. And the enums it exposed are part of it...Makes sense... But if the messageAddress constructor raises a MessageAddressFormatException...is it considered part of the DataContract?
Can there be Classes common to both Server, Client, AND Plugins?
Or is it an exception that is common to BOTH ServerMessageAddress and ClientMessageAddress, so should not be duplicated, and instead be in a Common assembly...so that in the end, the client has to bind to Contracts AND Common? (Didn't we just go down this alley with the Interfaces assembly?)
What about common Base classes/Interfaces?
And should these exceptions have common base classes? for example...ClientMessageAddressException, ServerMessageAddressException, ServerMessageVirusException (from plugin)...should I struggle to get them to -- as best as possible -- all derive from an abstract MessageException...or is there a time when enheritence/reusse just no longer an appropriate goal to strive for?
HUGE THANKS FOR READING THIS FAR.
I'm a developer and on the tech side I can bumble along ok...but these kinds of questions, where I've had to lay out the assemblies, the architecture, myself, leave me hugely perplexed...and lose me SOOOO much time, as I drive myself batty, moving things around from one assembly to another to see which one is the best fit, all while not really certain of what I am doing, and trying to not get circular references...
So -- really -- thanks for listening, and I hope this gets read by people who can describe how to lay out the above cleanly, hopefully expressing how to think my way through it for future projects as well.
After spending 10 minutes editing the question for formatting, I'm still going to downvote it. There's no way I'm going to read all that.
Go pick up a copy of
Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries (2nd Edition)
As an architect, I've learned that it doesn't pay to get too wrapped up in getting things absolutely perfect the first time, and perfect is subjective. Refactoring, especially moving classes between assemblies, doesn't have too huge a cost. It sounds to me like you're already thinking things through logically and correctly. Here's my opinions on a few of your questions:
Q: Should I have read-only contracts for my data contract classes?
The plugins most-likely shouldn't be aware of your data contracts at all. A virus checker may take a byte array, a spell checker a string and locale, etc. If you're making a general interface layer for the plugins, you should just isolate what's shared to the data specific to the plugin. This will allow you to maximize their reuse. Thus, I think you'll get little payoff on creating interfaces to your data contract structures, which should mostly be dumb bags of data with little logic that are practically interfaces themselves.
Q: Should I use the same data contract classes as my Silverlight app does in my ASP.NET application or use server-side classes directly?
I would go with the client message objects so you can benefit from code reuse. Object creation is fairly cheap, and I'm sure that most of the mapping would be one-to-one. It's not as fast, true, but that won't be the bottleneck in your application.
Q: Where do I put my exception classes?
I would put your example exception classes in the assembly with the data contract, since they are all raised due to contract violations or as a means to communicate errors while fulfilling the contract.
Q: Should the exceptions have common base classes?
I have yet to need to do this, but I don't know your code base as well as you do. My guess is that it will gain you little if anything.
Edit:
You may be overplanning for the future. In my experience, taking a YAGNI approach has allowed us to get the important things done more quickly. Making incremental design changes is preferred to spending valuable time building an elaborate architecture that you might never even benefit from.