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.

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.