Last updated on July 18, 2021
What it is the wrapper/facade pattern?
A wrapper, or facade, is when you create a new class, in order to hide how another class (or group of classes) works.
If you’d like to see this as a video, watch it here:
Why would you use a wrapper/facade?
There are two main reasons why you would use a wrapper.
The first is when you have a class, or a group of classes, that are complex to work with. For example, if you want to send an e-mail. In order to send an e-mail from a C# program, you need to create an e-mail message object, possibly create multiple objects for the e-mail addresses, and create an e-mail server object. Then, you can finally send out the e-mail. You also need to remember to include two “using” statements for namespaces that are rarely used.
That’s a lot of objects to create, in a specific order, just to send out an e-mail. It would be nice if you could create a single, simpler object that will hide all that complexity.
The second reason, which is less common, is to hide the implementation of third-party libraries – especially if they might change over time. Many libraries are updated at least once a year. And, occasionally, an update has a change that breaks your existing code.
If you have wrapper classes, that don’t do anything other than inherit from the library’s classes, you might be able to make one change in the wrapper class, in order to make the updated library work the way you want it to work.
Code Samples
For this demonstration, I’ll create a wrapper class in C# that sends an e-mail.
Simple version, without a wrapper/facade
If you’re sending a simple e-mail – only one “to” recipient – the code can be fairly simple, like this:
using System.Net; using System.Net.Mail; namespace DesignPatternDemos.Facade { public class MyClassForFacade { public void DoSomethingSimple() { // Pretend there is business-logic here // Send an e-mail - simple version, with one "to" address MailMessage simpleEmail = new MailMessage("from@test.com", "to@test.com", "Email subject here", "Email body here"); // Set up the mail server SmtpClient smtpClient = new SmtpClient("mailservername"); smtpClient.Credentials = CredentialCache.DefaultNetworkCredentials; smtpClient.Timeout = 100; // Send the email smtpClient.Send(simpleEmail); } } }
After you create the MailMessage, there is a little configuration that needs to be done for the mail server (SmtpClient). You also need to remember to include “using” statements for “System.Net” and “System.Net.Mail”.
More complex version, without a wrapper/facade
If you want to send an e-mail to multiple recipients (or CC and BCC recipients), the code gets noticeably longer. Plus, you need to use three different types of objects – MailMessage, several MailAddress objects, and the SmtpClient. It takes 36 lines of code to send out this sample e-mail.
using System.Net; using System.Net.Mail; namespace DesignPatternDemos.Facade { public class MyClassForFacade { public void DoSomethingComplex() { // Pretend there is business-logic here // Send an e-mail - complex version, with multiple "to", "cc", and "bcc" addresses. MailMessage email = new MailMessage(); MailAddress fromAddress = new MailAddress("from@test.com"); email.From = fromAddress; MailAddress toAddress1 = new MailAddress("to1@test.com"); email.To.Add(toAddress1); MailAddress toAddress2 = new MailAddress("to2@test.com"); email.To.Add(toAddress2); MailAddress toAddress3 = new MailAddress("to3@test.com"); email.To.Add(toAddress3); MailAddress ccAddress1 = new MailAddress("cc1@test.com"); email.CC.Add(ccAddress1); MailAddress ccAddress2 = new MailAddress("cc2@test.com"); email.CC.Add(ccAddress2); MailAddress bccAddress1 = new MailAddress("bcc1@test.com"); email.Bcc.Add(bccAddress1); MailAddress bccAddress2 = new MailAddress("bcc2@test.com"); email.Bcc.Add(bccAddress2); MailAddress bccAddress3 = new MailAddress("bcc3@test.com"); email.Bcc.Add(bccAddress3); MailAddress bccAddress4 = new MailAddress("bcc4@test.com"); email.Bcc.Add(bccAddress4); email.Subject = "Email subject here"; email.Body = "Email body here"; // Set up the mail server SmtpClient smtpClient = new SmtpClient("mailservername"); smtpClient.Credentials = CredentialCache.DefaultNetworkCredentials; smtpClient.Timeout = 100; // Send the email smtpClient.Send(email); } } }
Slightly simpler version, still without a wrapper/facade
You could simplify the previous code by instantiating the MailAddress objects in-line. That will make the code a little shorter (it’s down to 26 lines now). But, there is still a lot of work that needs to be done (this code still needs to use three different classes, and have the mail “using” statements added), to send out an e-mail.
using System.Net; using System.Net.Mail; namespace DesignPatternDemos.Facade { public class MyClassForFacade { public void DoSomethingComplex_SlightlySimpler() { // Pretend there is business-logic here // Send an e-mail - complex version, with multiple "to", "cc", and "bcc" addresses. MailMessage email = new MailMessage(); email.From = new MailAddress("from@test.com"); email.To.Add(new MailAddress("to1@test.com")); email.To.Add(new MailAddress("to2@test.com")); email.To.Add(new MailAddress("to3@test.com")); email.CC.Add(new MailAddress("cc1@test.com")); email.To.Add(new MailAddress("cc2@test.com")); email.Bcc.Add(new MailAddress("bcc1@test.com")); email.Bcc.Add(new MailAddress("bcc2@test.com")); email.Bcc.Add(new MailAddress("bcc3@test.com")); email.Bcc.Add(new MailAddress("bcc4@test.com")); email.Subject = "Email subject here"; email.Body = "Email body here"; // Set up the mail server SmtpClient smtpClient = new SmtpClient("mailservername"); smtpClient.Credentials = CredentialCache.DefaultNetworkCredentials; smtpClient.Timeout = 100; // Send the email smtpClient.Send(email); } } }
Simplest version, using a wrapper/facade
By building a wrapper, I’ve reduced the previous code to 7 lines. These lines don’t need to create any objects, and you don’t need to include the mail-related “using” statements.
Here’s what the code looks like now:
using System.Net; using System.Net.Mail; namespace DesignPatternDemos.Facade { public class MyClassForFacade { public void DoSomethingComplexWithWrapper() { // Pretend there is business-logic here // Send an e-mail - version behind wrapper/facade, with multiple "to", "cc", and "bcc" addresses. EmailCreator.CreateEmailFrom("from@test.com") .To("to1@test.com", "to2@test.com", "to2@test.com") .CC("cc1@test.com", "cc2@test.com") .BCC("bcc1@test.com", "bcc2@test.com", "bcc3@test.com", "bcc4@test.com") .WithSubject("Email subject here") .WithBody("Email body here") .Send(); } } }
For this wrapper/facade, I created a class that uses a fluent interface. Your wrapper classes don’t need to use a fluent interface. It’s just the technique I chose to simplify this code.
This fluent interface could be improved; it doesn’t force any “grammar rules”. But, it’s good enough to show how a wrapper/facade works. This will show you how to create a powerful fluent interface.
For this wrapper, the EmailCreator class handles building all the objects needed to send out an e-mail. The interface (IEmailFluentInterface.cs) is needed to make EmailCreator into a class with a fluent interface.
EmailCreator.cs
using System.Net; using System.Net.Mail; namespace DesignPatternDemos.Facade { public class EmailCreator : IEmailFluentInterface { private MailMessage _mailMessage = new MailMessage(); private EmailCreator(string fromAddress) { _mailMessage.Sender = new MailAddress(fromAddress); } public static IEmailFluentInterface CreateEmailFrom(string fromAddress) { return new EmailCreator(fromAddress); } public IEmailFluentInterface From(string fromAddress) { return this; } public IEmailFluentInterface To(params string[] toAddresses) { foreach(string toAddress in toAddresses) { _mailMessage.To.Add(new MailAddress(toAddress)); } return this; } public IEmailFluentInterface CC(params string[] ccAddresses) { foreach(string ccAddress in ccAddresses) { _mailMessage.CC.Add(new MailAddress(ccAddress)); } return this; } public IEmailFluentInterface BCC(params string[] bccAddresses) { foreach(string bccAddress in bccAddresses) { _mailMessage.Bcc.Add(new MailAddress(bccAddress)); } return this; } public IEmailFluentInterface WithSubject(string subject) { _mailMessage.Subject = subject; return this; } public IEmailFluentInterface WithBody(string body) { _mailMessage.Body = body; return this; } public void Send() { // Set up the mail server SmtpClient smtpClient = new SmtpClient("mailservername"); smtpClient.Credentials = CredentialCache.DefaultNetworkCredentials; smtpClient.Timeout = 100; // Send the email smtpClient.Send(_mailMessage); } } }
IEmailFluentInterface.cs
using System.Net; using System.Net.Mail; namespace DesignPatternDemos.Facade { public interface IEmailFluentInterface { IEmailFluentInterface From(string fromAddress); IEmailFluentInterface To(params string[] toAddresses); IEmailFluentInterface CC(params string[] ccAddresses); IEmailFluentInterface BCC(params string[] bccAddresses); IEmailFluentInterface WithSubject(string subject); IEmailFluentInterface WithBody(string body); void Send(); } }
With a wrapper like EmailCreator, you can easily send out e-mails from any place in your programs. You’ll also be ready if the mail objects (MailMessage, MailAddress, and SmtpClient) ever change how they work.
Where I’ve found it useful
I actually encountered the e-mail message problem in a program I worked on several years ago. The .NET 2.0 framework changed the way they handled e-mail addresses, compared to how it worked in .NET 1.1.
I’ve also seen a large system that used a third-party UI control library. After several years without updating the library, the company decided to finally move to the latest version. It took several programmers, many days, to update the UI code to the new version. Once they were “done”, they still encountered problems over the next few weeks.
If we were using a wrapper, or facade, it would have been easier for us to handle those changes.
Source code for my design pattern lessons
Hello Scott – thank you for taking the time to create these well-done articles.
I’ve a question that is not necessarily about the Wrapper pattern but is somewhat linked.
I’m writing a program that will convert objects from one class to another and I want to make it easy to see all of the property mappings, i.e. what property in the sourceclass maps to a given property in the destination class. Not all the properties would map though, some properties in the destination class would need to be computed.
I created a dictionary that holds the mappings, like so –
Dictionary<string, string> PropertyMapper; with the key being the destination property name and the value being the source property name.
The code would look something like this –
Here, ItemSKU is the propertyname in the DestItemClass.
While this would make it easy to handle propertyname updates in the source class, a class that I consume and is provided by a thirdparty, does this approach make sense?
Is there a better way to handle mapping of properties between objects?
Thanks.
Hello Rakesh,
If it fits your program’s needs, I would consider using the AutoMapper library. It is very robust, and handles many complex situations – such as, when a class has a property that is another class, or is a list of other business objects. It also includes the ability to do validation of the conversion, in case the third-party objects have a new structure.
If that won’t work for your situation, please tell me. I started to write a library to map between C# objects and SQL tables. I stopped when it needed to handle List properties (when it became very complex). That library might have some ideas, if AutoMapper will not work for you.
Thank you Scott.
Someone else did tell me about Automapper, I’ll check it out.
Thanks for this article with example. We have around 50 projects in our company and all creatinf smtp object and sending email. I would like to create 1 common component or API to send email. How would I go with considering some applications use .net smtp and some are using 3rd party smtp and mailmessage object. One solution we are thinking is to create abstract email class and implementation but this involved lot of changes to existing applications and testing.
The first thing I’d ask is if you need to continue using two different SMTP libraries for the future. Consistency across programs usually makes them easier to maintain.
It’s difficult to come up with an exact plan, without seeing the programs. But, if you need to continue using both libraries, you can create a new EmailManager class library that includes the .NET SMTP library and the 3rd party SMTP library. Then, create your email-building fluent interface to have two different “instantiating” methods – one for .NET SMTP, one for the 3rd party SMTP. You’d have a private variable (let’s call it “_smtpLibrary”) in the EmailCreator class that saves which SMTP library is being used. You can have different chaining method requirements, based on what information is needed for each library (mail server name, password, etc.). Then, the final executing “Send” method, would check the _smtpLibrary value to determine which SMTP library to use to send the email.
Once you have that library written, you can include it in your projects, but not use it until you have a need to modify the program. Then, as you make other changes to the programs, you can decide if it’s a good use of your time to also change some of that program’s email-sending routines to use the one in the new EmailManager library.
If the programs currently work, and it would take too much time and effort to modify (and test) them, you might not want to make any changes. As much as I like having clean code, you need to weigh the amount of work and the risk of breaking something with the value of the improved code. Sometimes it doesn’t make business/economic sense to improve the code.
Let me know if that makes sense, or if you have more questions.