This edition of Practical Programming covers a set of three useful classes / namespaces from the .NET Framework that you probably aren’t familiar with (yet).

Let’s make some noise: System.Media

Producing sound from a computer is something you may have learned in Programmer Playschool and promptly forgot (like me), but it is a useful little feature to add to all types of software, not just desktop games. Playing a system sound or other sound files is very useful in monitoring environments where the users are not seated in front of a computer 24×7 (for example, in server rooms or manufacturing environments).

System.Media is a namespace that contains three useful classes for playing system sounds and .wav files. System sounds are defined in the Sounds applet of the Windows Control Panel.

What MSDN says:

The System.Media namespace contains classes for playing sound files and accessing sounds provided by the system.

The following classes are included in this namespace:

• A SoundPlayer class for loading and playing sounds in various file formats.
• A SystemSound class for representing and playing a system sound.
• A SystemSounds class that retrieves sounds associated with a set of Windows operating system sound-event types.

Playing a System sound couldn’t be easier:

This will play the .wav file associated with the asterisk system sound. SystemSounds is a simple wrapper for the five most common sounds – asterisk, beep, question, exclamation and hand.

If you have your own attention-grabbing, eardrum-busting sound file then you can play this just as easily:

Loading of large .wav file can take a while so, thoughtfully, Microsoft added support for loading a sound file asynchronously.

This simple C# console application will play the sound file after it is loaded. Not only will the loading of the sound occur asynchronously, but the player will also play the .wav file in a new thread.

Additionally, the player can load a wave file from various sources such as a URL, application resources, or a stream.

Brain the size of a planet? MemoryFailPoint

In these multi-gigabyte days it’s not often that an application runs out of memory – virtual or otherwise – but there are few things more frustrating to a user than an ‘Insufficient Memory’ exception. Applications that don’t handle these exceptions can potentially corrupt system data (and possibly damage your career!).

Thankfully, there is a simple solution: MemoryFailPoint.

What MSDN says:

Check for sufficient memory resources prior to execution.

MemoryFailPoint throws an InsufficientMemoryException prior to your operation beginning, rather than an OutOfMemoryException at some unpredictable point during the operation. Here’s the actual program that is used to launch the Space Shuttle Microsoft (j/k).

Hopefully, the real NASA application is a little more complicated than this, but you could imagine a situation where running out of available memory just after ignition could be somewhat problematic. It’s better to know before you begin that your countdown is likely to fail. Adding a MemoryFailPoint around the critical code will help with this:

When using MemoryFailPoint for more realistic purposes, you can make intelligent decisions about the execution path. For example, fast sorting algorithms can use more memory than slower but less resource hungry versions.

Secret Squirrel – System.Security.SecureString

What MSDN says:

Represents text that should be kept confidential. The text is encrypted for privacy when being used, and deleted from computer memory when no longer needed.

This sounds like something useful to do, and indeed it is! To use a SecureString you need to append characters to it like so:

Clearly, this would be a tad pointless! The unsecure password is right there in clear text for all to see (and discover). To understand this, you need to understand show strings in the .NET Framework work.

Strings are immutable. That is, once you create a string in memory, it can’t change – it can only be replaced. For example:

Looking at this you might think that there is some chunk of memory somewhere that starts off as "fred" and later becomes "bob". This is not the case. In actuality, both "fred" and "bob" will be in memory somewhere within the process space of the application. Every time you change a string, a new copy of the string is made and the old one is left for later cleanup by the garbage collector. A sniffer type application on a compromised machine could read through your unprotected memory quite easily.

So, when should you use SecureString? There are a few places in the framework that require a SecureString but the best time to use this is anywhere in your application that you prompt for something you don’t want to risk exposing to unauthorized users or processes.

SecureString should be used in conjunction with other secure mechanisms such as an encrypted configuration file or database record, SSL/TLS for web applications to network transport, etc.

References:

B# .NET Blog – http://bartdesmet.net/blogs/bart/archive/2006/03/31/3851.aspx

.NET Security Blog – http://blogs.msdn.com/shawnfa/archive/2004/05/27/143254.aspx

—–

Peter Jones is a 25 year veteran (vintage?) programmer and Microsoft MVP (ASP.NET) from New Zealand. He currently works for Intergen – a leading Microsoft Gold Partner. Peter has worked on and created systems for many industries such as Telecommunications, Manufacturing, Government, Education and more. He cut his programming teeth on dBase 3, Clipper 5 and C before moving to Windows development tools such as Visual Basic, Delphi and .NET. Currently he is working with content management systems (SharePoint and EPiServer) in Sydney, Australia. You can contact Peter and read his occasionally updated blog at http://jonesie.net.nz.

So you are almost done with implementing a ground breaking, state of the art, super duper plugin-enabled calculator application with syntax highlighting and now you are wondering how to get it deployed? In case you are already trying to put some arguments together to convince your boss for buying a suite to building Microsoft Installer packages worth several thousand dollars: Stop! Don’t do that. Well, at least not if your application is not as complex as let’s say your development environment.

Using Microsoft Visual Studio you should be able to create an MSI in literally no time by using the predefined Setup Project template and if you need to accomplish additional tasks that Windows Installer does not support out of the box, read on to find out how to extend your installer with own custom actions.

The Vision

A couple of years ago market researcher Evans Data noticed a massive drop of C++ developers and also forecasted a continuous decrease. Bjarne Stroustrup on the other hand said that the number of C++ developers is higher than ever (he’s the inventor of C++ by the way). Whoever you trust, you are most probably reading this because you want to know how to use C# or VB.NET for writing custom actions in Visual Studio instead of using good old C++. So let’s dive into that topic by creating a not so fictional case scenario: The first task you would want to accomplish is creating an eventlog source for your application (because you read that the installation of an application is the suggested moment for doing just that)

Note: We will do a lot more than that, so I have included a small sample solution for you to easily reproduce what I am talking about. You can download it from http://devshaped.com/files/MyCalcSln.zip.

The Solution

As I said earlier, you could use C++ to implement a native custom action. However, the easiest solution for getting this done using C# or VB.NET is deriving a class from the Installer Class and overriding the Install method. Then you would add your custom action to the Custom Action Table of the installer.

So let’s start!

Create the Custom Action

Add an Installer by right clicking your project and select Add > New Item > Installer Class. Name it CreateEventSource.cs for now.

Figure 1- Adding an Installer Class

Next right click the CreateEventSource.cs file in the solution explorer and select View Code. Replace it with the following (you may want to adjust the namespace and the actual event source name):

As you can see, deriving from the Installer base class is not enough. You need to add the attribute RunInstaller to the class and initialize it with true as shown above. This basically marks the CreateEventSource class as an Installer class and makes it visible to reflection.

Create the setup project

Simply add a new Setup Project to your solution by right clicking your solution in the solution explorer and then Add > New Project > Other Project Types > Setup Project as shown in the following figure:

Figure 2 – Adding a Setup Project

To let the Setup Project know what to install, right click the project and select Add > Project Output… Make sure your application project is selected as Project and choose Primary Output. Click OK.

Figure 3 – Adding Project Output to Setup Project

With these simple steps you just created a setup that is able to install your application. Now you would make sure your custom actions are called and configure some simple settings. Right click the Setup Project in the solution explorer and select View > Custom Actions.

Now right click the Custom Actions node and select Add Custom Action. Look in File System on Target Machine and double click Application Folder. Select the Primary Output from your application project and click OK.

Figure 4 – Custom Action View

Easy. This will create the eventlog source for you by making use of the Installer Class you created earlier. If you would build your setup now and install it, the application will be defaulted to [ProgramFilesFolder][Manufacturer]\[ProductName]. Of course it is up to you to change the default target path. In my case, C:\Program Files\TOP TECHNOLOGIES CONSULTING GmbH\MyCalc would be a little like breaking a fly on the wheel. So I right click the Setup Project in the solution explorer and select View > File System and choose Application Folder. In the properties pane, I can configure the DefaultLocation to something like [ProgramFilesFolder][ProductName]. That’s better.

Install your application

Now let’s finally make a real job of it. Right click the Setup Project in the solution explorer and select Build. After being built successfully, right click the project again and select Install.

You should be familiar with the dialogs that follow. However, after your setup successfully installed your top notch calculator, have a look at the event viewer by clicking Start and entering eventvwr.

You will find the following entry in the application log:

Figure 5 – Eventlog Entry

Observations

When using a fully featured environment for creating and using Custom Actions such as InstallShield from Acresso or Windows Installer Xml from Microsoft, you have absolute control over when and how your custom action is actually called. You can start it during the interview phase of your setup (aka UI sequence), during the immediate phase of the execution sequence when the actual installation script is generated or use it as a deferred custom action that is run in within the system context while the system changes are really applied.

Custom Actions implemented as Installer Classes are only run deferred in the system context. That means that your application is already successfully installed at that time. You have full access to all your files and also the configuration. You could implement a Custom Action for instance that alters configuration settings of your application based upon properties set by the user during the UI sequence (I will show you how later).

If you want to dive into the details of the Microsoft Windows Installer installation process, go ahead and read Alex Shevchuck’s TechNet entry here. This is a great resource for a decent understanding about what’s going on under the hood.

Potentialities (or: What the heck is CustomActionData?)

When looking at the choices in the View context menu of your Setup Project, you already noticed the following entries:

• File System
• Registry
• File Type
• User Interface
• Custom Actions
• Launch Conditions

What most certainly caught your attention is the User Interface entry. Yes! You can really add custom UI dialogs to a Visual Studio Setup Project. Although it is possible creating real custom dialogs, you can instantly start using own dialogs by choosing from the provided templates. Since we already agreed that we are talking about relatively simple applications here, in most cases that will get you started immediately (if you really really need more than that, look here).

Changing Application Settings During Installation

Let’s have some fun with custom dialogs to do something really useful here you most probably won’t instantly find by poking keywords into a search engine. Looking into the functional specification of your calculator you notice that one of your bosses (the one who usually has the most intriguing ideas of all) demanded that the calculator should welcome the user with his/her name. You heard him mumbling something about “Unique Selling Point” while he left the conference room…

So here is what you do:

Create a splash screen

Right click your calculator application and select Add > Windows Form. Name the form Welcome.cs and set its properties to the following values:

Property	Value
FormBorderStyle	None
ShowInTaskbar	False
TopMost	True
StartPosition	CenterScreen

Drag and drop three label controls into the form like this:

Figure 6 – Borderless splash screen

Create and bind an application setting to a label

Now configure the UserNameLabel label. In the property pane expand the ApplicationSettings node and click the ellipsis button (…) to the right of the Property Binding setting. Select the Text property, expand the drop down list and select New… Enter UserName as Name and Application as Scope (we’ll assume that the user who installs the calculator won’t let anyone else start it).

At this moment, Visual Studio automatically creates an app.config file for you that should basically look like this:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
      <sectionGroup name="applicationSettings" type="System.Configuration.ApplicationSettingsGroup,
          System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" >
          <section name="MyCalcWin.Properties.Settings"
              type="System.Configuration.ClientSettingsSection, System, Version=2.0.0.0,
              Culture=neutral, PublicKeyToken=b77a5c561934e089" requirePermission="false" />
      </sectionGroup>
  </configSections>
  <applicationSettings>
      <MyCalcWin.Properties.Settings>
          <setting name="UserName" serializeAs="String">
              <value />
          </setting>
      </MyCalcWin.Properties.Settings>
  </applicationSettings>
</configuration>

If you have a close look at the Welcome.Designer.cs file you will find the following line that does the binding for you:

Let the splash screen appear at startup

To make the splash screen appear, adjust the Load method of your main form like this:

Now let’s finally wire things up with the setup project.

Create a custom dialog

Right click the Setup Project in the solution explorer and select View > User Interface. Right click the Start node in the Install tree and select Add dialog. Choose Textboxes (A) and click OK.

Figure 7 – Adding a Custom Dialog

Drag and drop the new dialog in front of the Confirm Installation node. Select it and change its properties to the following values:

Property	Value
BannerText	Enter your name
BodyText	MyCalc is the only calculator that will welcome you personally on each startup! Just tell it who you are.
Edit1Label	Your name:
Edit1Property	USERNAME
Edit2Visible	False
Edit3Visible	False
Edit4Visible	False

Now right click again the Setup Project in the solution explorer and select View > Custom Actions. Select Primary Output from MyCalcWin (Active) right under the Install node and change its CustomActionData property value to /userName="[USERNAME]".

Create a new Custom Action

Now comes the tricky part. We are talking here of at least a .NET 2.0 application. As we already saw, we are working with real type safe and supposedly easy to use settings utilizing the data bound Settings.settings file. Fortunately, .NET already generated a type safe wrapper for us. Unfortunately you cannot access the settings as easily as from within the application due to the fact that the installer simply does not have a mapper for it (and we won’t supply it with one).

What you can do though is this:

Create another custom action as you already did before, call it RegisterUser and replace the generated code with the following:

As you can see, we can access the Custom Action Data we prepared earlier through the InstallContext Parameters collection. Also the InstallContext already contains a couple of default parameters such as the assemblypath (which we need to access the applications’ configuration file).

What we are doing here is loading the .exe.config file of our application, digging through to the UserName setting, creating a new Xml node containing the username value and finally putting the value into the configuration before we are saving the changes. It is really as easy as that. Wasn’t that obvious?

Now compile and install your application.

The setup will ask you for your username:

Figure 8 – User registration dialog

When starting the calculator, the splash screen welcomes you:

Figure 9 – Actual splash screen

Alternatives

Over and above the samples you saw so far there are several alternatives to using the Installer Class provided by Visual Studio. One is using native C++ (the languageWindows Installer is actually developed in, which is why it is the most powerful way of implementing custom actions). Explaining how that works is out of the scope of this article, but you can read about it for example on Steven Bone’s Blog who published three absolutely awesome articles about it here.

A native custom action that accesses the MSI log for instance basically looks like this:

extern "C" UINT __stdcall Install(MSIHANDLE hInstall)
{
  PMSIHANDLE hRecord = MsiCreateRecord(0);
  MsiRecordSetString(hRecord, 0, TEXT("Native C++ is better than Installer Class!"));
  MsiProcessMessage(hInstall, INSTALLMESSAGE(INSTALLMESSAGE_INFO), hRecord);
  return ERROR_SUCCESS;
}

Using DTF (Deployment Tools Foundation), which is part of the Windows Installer Xml Toolset, enables you to implement Custom Actions with managed code. However, you need to make sure .NET Framework is already installed on the computer you are running the setup on and also have a couple of prerequisites to fulfill.

Action	Installer Class	Native C++ DLL	WiX DTF
Run in UI sequence		X	X
Run immediate in execute sequence		X	X
Run deferred in execute sequence	X	X	X
Read MSI properties	X[1]	X	X
Write MSI properties		X	X
Debuggable	X	X	X [2]
Access MSI Logfile		X	X
Access Installstate log	X
.NET Framework must be installed	X		X
Windows Installer Xml must be installed			X

Conclusion

In many cases, installation needs are straightforward enough that it is not worth the effort to implement anything more complex than the Custom Actions that run deferred in system context. Although you gain more control over the installation process when you choose to implement Windows Installer Xml based Custom Actions or native CA’s, Installer class based Custom Actions can be a great way to extend your Visual Studio based Setup Project without the need to invest in additional installer solutions.

[1] Through stateSaver dictionary collection

[2] Simple unit testing possibility via wrapping the MSI session

—–

Christian Jacob is an IT Consultant with TOP TECHNOLOGIES CONSULTING, a Microsoft Gold Partner with focus on infrastructures, security and business solutions. He primarily uses C# and VB.NET in nowadays development and  has his roots in C++ based game development. He spends a lot of time in researching and creating innovative solutions around team development, Windows Installer, and TOP TECHNOLOGIES’ main software products. He currently resides nearby Hamburg in North Germany.

Remember XML? Remember those fun times you had creating XML data files, XSL’s and DTD’s using Notepad? It seemed like such a great thing to do. There were grandiose plans to save the world with markup.

Today, XML is just another file format thanks to great tools and (reasonably well followed) standards. The tools in Visual Studio do such a great job of encapsulating XML that we often forget that it even exists under the covers.

And then along comes a scenario where you need to dig deep and reach for those reference manuals (or search engine). Recently I had just such a challenge.

The Mission

Create a site for Students and Law Professionals to register for seminars offered by a law college. Seminar attendees would pay for seminars using a credit card. Payments would be processed online by the college’s bank.

The Solution

The web site was created using ASP.NET MVC, Visual Studio 2008 and SQL Server 2005. The college’s bank provided various documents to describe their payment gateway interface which supports payment by the usual credit cards, plus credit transactions and other services. For this site we only required the payment service.

Principals

The .NET Framework is huge. It contains over 11,000 types (classes, structs, etc). You can bet your bottom dollar that there are several ways to do just about any task you choose. My overriding principal when creating any coded solution is to use the clearest and easiest to maintain code. Performance and elegance normally come second to this – mostly because of the types of applications I create but also because simple code is usually better code.

Getting Setup

For this exercise I have created a sample web service and client web site to test it. You can download the complete sample code from here. This sample includes a complete standalone project for processing payments with a test payment gateway. With a bit of work you should be able to easily adapt this for a real payment gateway of your choice.

In the remainder of this article I will be focusing on the PaymentGatewayFormatter class from the sample. A full explanation of the sample code is beyond the scope of this article but please feel free to drop me a line if you have any questions or suggestions.

The Problem

In these enlightened times, we tend to expect ’standard’ web services to be made available for just about everything. Connecting to such a web service is trivial if you can use Visual Studio or the .NET SDK WSDL tool to generate the interface proxy for you. However, in this case, the bank provided only the following:

• A REST style web service sending and receiving plain old XML (POX) with no WSDL.
• A PDF document describing the service architecture, rules for usage, sample XML request/response messages, and DTD schemas.
• A PDF document describing the HTTP/XML and Java interfaces.

And that was it – nothing for .NET, no XSD, no WSDL and no SOAP. A call to the bank requesting a .NET interface resulted in a one word answer, which you can probably guess!

The Implementation

After some research and experimentation with Windows Communication Foundation (WCF) and Web Service Contract First (WSCF) and with limited time to create the interface, I opted for a hand coded implementation using low level framework support and HTTPWebRequest.

The Specification

The bank provided sample request and response messages as below:

Sample Request:

<?xml version="1.0" encoding="UTF-8"?>
<TransactMessage>
  <MessageInfo>
    <messageID>8af793f9af34bea0cf40f5fb5c630c</messageID>
  </MessageInfo>
  <MerchantInfo>
    <merchantID>123456</merchantID>
    <password>password</password>
  </MerchantInfo>
  <RequestType>Payment</RequestType>
  <Payment>
    <TxnList count="1">
      <Txn ID="1">
        <txnType>0</txnType>
        <amount>1000</amount>
        <purchaseOrderNo>test</purchaseOrderNo>
        <CreditCardInfo>
          <cardNumber>4444333322221111</cardNumber>
          <expiryDate>08/12</expiryDate>
        </CreditCardInfo>
      </Txn>
    </TxnList>
  </Payment>
</TransactMessage>

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>
<TransactMessage>
  <MessageInfo>
    <messageID>b9cffb095b4f460fb0d60be85975b600</messageID>
  </MessageInfo>
  <RequestType>Payment</RequestType>
  <Status>
    <statusCode>000</statusCode>
    <statusDescription>Normal</statusDescription>
  </Status>
  <MerchantInfo>
    <merchantID>123456</merchantID>
  </MerchantInfo>
  <Payment>
    <TxnList count="1">
      <Txn ID="1">
        <txnType>0</txnType>
        <amount>1000</amount>
        <purchaseOrderNo>test</purchaseOrderNo>
        <approved>Yes</approved>
        <responseCode>00</responseCode>
        <responseText>Approved</responseText>
        <txnID>009844</txnID>
        <CreditCardInfo>
          <pan>444433...111</pan>
          <expiryDate>08/12</expiryDate>
          <cardType>6</cardType>
          <cardDescription>Visa</cardDescription>
        </CreditCardInfo>
      </Txn>
    </TxnList>
  </Payment>
</TransactMessage>

My first inclination was to create XSD files using these samples. Visual Studio made this easy to achieve. With the sample XML files open in Visual Studio I selected the Create Schema option from the XML menu. This produced an accurate XSD file. However, this was not much use by itself. I needed to create a C# class to include in my web site that would enable serialization of XML to and from the payment gateway.

The command line WSDL tool provided in the .NET Framework SDK does a great job of generating code for just this purpose. But in this case it was not so useful. Note that the request and response messages both have a root node of <TransactionMessage>. When I generated the C# classes from the generated XSD files, I had duplicate classes in the files for TransactionMessage, MessageInfo, Status etc. Fixing this would have required hand coding of the schema to include request and response messages, or merging of the generated classes. This felt like a lot of error-prone work.

XmlTextWriter

All I really wanted was a simple way to send a bunch of XML to a web site and read the response. The XML was not particularly complex or large so I opted to create the request using XmlTextWriter.

XmlTextWriter could not be any easier. I’ll explain how to use it in the steps below.

1)   Create a method to compose the required XML. I use a custom object, PaymentRequest to encapsulate the details of the request.

(All of the following code belongs inside this method).

2)   Create a stream for the XmlTextWriter to write to.

3)   Create an instance of an XmlTextWriter. Note the use of UTF8 encoding to match the sample XML file.

4)   Use the XmlTextWriter to write elements and attributes to the stream. XmlTextWriter provides methods that produce validated elements only. For your example, we begin with the root node, TransactMessage:

Every element that is started must be ended:

writer.WriteEndElement(); // TransactMessage

I find it less error prone to always create the start and end element method calls in pairs, and build the structure from the outside in – much like matching curly-braces in C#. Adding a comment to the WriteEndElement method call will also help you remember what you are ending. For example:

This will produce the following XML in the output stream:

<MessageInfo>
<messageID>8af793f9af34bea0cf40f5fb5c630c</messageID>
</MessageInfo> 

Use WriteElementString to create a complete element with a simple string as its inner xml value. To create an attribute on the current element simply follow the WriteStartElement call with WriteAttributeString.

5)   Flush the writer.

6)   Convert the stream to a string and return it.

And that’s about it. XmlTextWriter has many more useful methods to deal with namespaces and other standard XML features, but for this simple example these are not required.

XmlReader

Writing an XML file is very simple. Reading one, unfortunately, is not quite as straight forward. The main issue is that you cannot assume the order of elements will totally match your expectations. In our Bank of Jones sample it may be quite feasible to receive a response with the MessageInfo, Status and MerchantInfo elements in any order.

XmlReader allows you to read elements in an expected order, in much the same way as you would write them with XmlTextWriter. This may work for a while but when dealing with external systems there is no guarantee that it will work forever. In fact, when dealing with banks, it’s a very good idea to assume it will change at random and you will only know about this when your client code fails!

Fortunately, there is a way to deal with this. XmlReader allows you to processes the XML serially. An example is the best way to describe this. Here are the steps.

1)   Create an empty method to process the response stream.

2)   Create an XmlReader instance, and somewhere to store the de-serialized response data. In my case this is a PaymentResponse object.

3)   Read through the input stream using reader.Read() which will read through the input XML one ‘item’ at a time. The item could be a start element, an attribute, an end element, comment, white space and more. Each time you call .Read() it advanced the internal pointer of the reader to the next item and sets a number of properties that you can use to determine exactly what the reader is pointing at. This is a very efficient way of parsing large XML files/streams because it is a forward only, read only mechanism.

Below is the main code I use to process the input stream.

This code uses a number of sub-processing methods that also advance the cursor through the input stream (I have excluded these from here for brevity but you can examine them in the sample source code provided). Breaking the processing method into smaller chunks like this makes the methods much clearer.

Below is the helper method to update the PaymentResponse with the CreditCardInfo node. The other processing methods follow the same pattern of looping until the node ends.

Alternatives

The .NET Framework provides several ways of reading and writing XML files. The ‘legacy’ method is to use XmlDocument. This still works well but tends to be rather inefficient, especially with large XML files. The construction of the XML with XmlDocument is simple but not as intuitive as with XmlTextWriter. Reading of data from XmlDocument generally requires navigating through the structure using XPath queries.

If the 3.5 version of the .NET Framework, the new XDocument provided with LINQ is an excellent option. Using XDocument I could construct the payment transaction thus:

This syntax is certainly easy to construct and read but as you can imagine, a large deeply nested XML file can look messy and finding a mismatched parenthesis or missing comma is not fun.

Reading XML with LINQ bypasses the need to create cryptic XPath queries but it is still a query driven process. For example, to read the MessageInfo node would require the following code:

This code is clear enough and in some ways safer than my example, but it is not available for .NET 2.0. For my situation, XmlTextWriter and XmlReader provided a clear, simple, and efficient mechanism for dealing with XML data.

—

Peter Jones is a 25 year veteran (vintage?) programmer and Microsoft MVP (ASP.NET) from New Zealand. He currently works for Intergen – a leading Microsoft Gold Partner. Peter has worked on and created systems for many industries such as Telecommunications, Manufacturing, Government, Education and more. He cut his programming teeth on dBase 3, Clipper 5 and C before moving to Windows development tools such as Visual Basic, Delphi and .NET. Currently he is working with content management systems (SharePoint and EPiServer) in Sydney, Australia. You can contact Peter and read his occasionally updated blog at http://jonesie.net.nz.

Sending email from a .NET application is incredibly simple:

With just these few lines of code, you are sending an email from from@test.com to derek@devshaped.com. Pretty easy stuff.

But what if you need something a little more complicated? The example above assumes the standard SMTP port for email with no authentication and an unencrypted connection. Fortunately these “complications” are quite easy to deal with in .NET.

Different Port

If you need to send email on a different port, simply add the following line:

SMTP Authentication

If you are not sending through a local SMTP server, your app will likely need to authenticate itself. If you need to pass credentials to the SMTP server, use the Credentials property on the SmtpClient class:

Encrypted Connection

Since you are passing credentials to the server, you really should be using a secure connection (many mail providers require you to use a secure connection). In code, it’s just one line:

Sending Email On Behalf of Someone

A final practical consideration when sending email is the distinction between From and Sender. In a simple scenario, you only need a From address. But if you are writing code to send email, chances are good that there is something not-quite-so-simple happening.

Perhaps you have received an email with a header like this in Outlook:

This is an example of one email account sending an email on behalf of someone else. This is often used by automated systems and it is trivial to add to your application. To add a Sender you cannot pass values directly to an SmtpClient object; you must create a new instance of the MailMessage class, set the properties, and then pass the MailMessage object to the SmtpClient object:

Keep in mind that your message is going through an SMTP server that might not let you set arbitrary From and Sender values.

Bringing it All Together

Here is what the final code looks like that incorporates an alternate port, credentials, encrypted transport, and a sender:

—-

Derek Hatchard is the content editor for http://microsoft.com/youshapeit/msdn and http://devshaped.com. He is also the founder of Crowd Space. You can find him online at http://derekh.com, http://ardentdev.com, and http://twitter.com/derekhat.