Crows Programming » C#

Runtime Scripting in .Net

crow — Thu, 01 Oct 2009 04:49:40 +0000

The ability to ship source code with your product that can be compiled or interpreted at runtime is a very valuable asset. Video games do this all the time with things like AI allowing the end-user to easily mod the game. In compiled languages like C++, this technique is highly advantageous as it allows you to avoid the costly compile-link cycle for every small change to a source file. This is also helpful in an environment where creating a new build, generating the installer, and deploying it is overkill or difficult to achieve. In this article we will examine how you can achieve this from .Net programs consuming a C# or VB.Net script. I’ll refer to this as “scripting”, even though an unambiguous definition of a “script” is somewhat difficult to nail down.

Using a C# or VB script from a .Net language is actually very simple. The basic idea is to read in a source file, which could come from the network or disk, and compile it into a temporary assembly on file or IL in memory. Then you can instantiate types from the script file and use them just as easily as any other types already defined. Normally the hard part in this process is locating and invoking the proper compiler. Luckily, we can compile IL code using a CodeDomProvider like CSharpCodeProvider. And, since these types are part of the .Net framework we know they are available on the end-user PC! Life is great eh?

Ok, so first make sure you have referenced the following namespaces:

    using System.CodeDom.Compiler;
    using Microsoft.CSharp;
    using Microsoft.VisualBasic;

Next you need to setup the compiler parameters. These are simply the options given to the compiler such as whether to create the resulting assembly in memory or if debug information should be included in the generated code. You can do this with the CompilerParameters type. Here is an example for creating an in memory assembly with debug information:

 CompilerParameters cparams = new CompilerParameters();
 
 cparams.GenerateInMemory = false;
 cparams.IncludeDebugInformation = true;
 cparams.CompilerOptions += " /debug:pdbonly";
 
 cparams.TreatWarningsAsErrors = false;
 cparams.GenerateExecutable = false;

You would also want to add any references that your code needs using CompilerParameters. ReferencedAssemblies. So, after you have the compiler options set you need to actually invoke the C# or Visual Basic compiler. You do this by creating a CodeDomCompiler of the appropriate type:

VBCodeProvider – for Visual Basic
CSharpCodeProvider – for C Sharp

Then you can use the provider to compile an assembly like so:

CodeDomProvider provider = CSharpCodeProvider();
CompilerResults result = provider.CompileAssemblyFromFile(cparams, script);

Where cparams are your compiler parameters and result is well, your results. Within results you will find out if the compilation was successful or generated warnings. It will also give you access to the resulting assembly. You can check for errors using results.Errors.HasErrors and reference the assembly with results.CompiledAssembly.

Now that you have a compiled assembly in memory, there is one last issue to address. How do you instantiate types from the assembly? The easiest way to attack the problem is to create an interface that your application can access and derive a type from that interface in your script. I’ve created a full example below (explained in code comments) to illustrate the technique I am talking about.

C# Example

Main application – Script.cs

using System;
using System.CodeDom.Compiler;
using Microsoft.CSharp;
using Microsoft.VisualBasic;
using System.Reflection;
using System.IO;
 
namespace ScriptingExample
{
    public class Script
    {
        public LoadedType LoadScript<LoadedType>(string script, string referenceString) where LoadedType:class
        {
            // this will load/compile the script source file, "script", and return a type of LoadedType
            // it is assumed that a type of "LoadedType" is defined in the script
            // the referenceString is a comma delimited string identifying all references needed by the script
            // e.g. "System.dll,System.Windows.Forms.dll"
            // either the VB or C# compiler will be invoked, based upon the file extenstion .vb or .cs
 
            // try and compile the script
            CompilerParameters cparams = CreateCompilerParameters(referenceString);
            CompilerResults results = CompileScript(script, cparams);
 
            // check for errors
            if (results.Errors.HasErrors)
            {
                string e = "";
                foreach (CompilerError error in results.Errors)
                    e += (error.ErrorText + Environment.NewLine);
 
                throw new Exception("ERROR IN SCRIPT: " + Environment.NewLine + e);
            }
 
            // find the "exported" type to load
            LoadedType scriptObject = FindScriptObject<LoadedType>(results.CompiledAssembly);
 
            if (scriptObject == null)
                throw new Exception("CAN'T LOAD SCRIPT, TARGET TYPE NOT IMPLEMENTED IN SCRIPT.");
            else
                return scriptObject;
        }
 
        private CompilerResults CompileScript(string script, CompilerParameters cparams)
        {
            // compiles the script using the specified parameters
            // either the VB or C# compiler will be invoked, based upon the file extenstion .vb or .cs
            CodeDomProvider provider = GetCompiler(script);
            CompilerResults result = provider.CompileAssemblyFromFile(cparams, script);
 
            return result;
        }
 
        CodeDomProvider GetCompiler(string script)
        {
            // returns the correct compiler to use based on the file extension of the script
            string extension = Path.GetExtension(script);
 
            if (extension == ".vb")
                return new VBCodeProvider();
            else if (extension == ".cs")
                return new CSharpCodeProvider();
            else
                throw new Exception("UNKNOWN SCRIPT TYPE");
        }
 
        private LoadedType FindScriptObject<LoadedType>(Assembly assembly) where LoadedType : class
        {
            // attempts to locate the type "LoadedType" within the assembly that was created from the "script"
            foreach (Type t in assembly.GetTypes())
                if (typeof(LoadedType).IsAssignableFrom(t))
                    return Activator.CreateInstance(t) as LoadedType;
 
            return default(LoadedType);
        }
 
        private CompilerParameters CreateCompilerParameters(string referenceString)
        {
            // creates compiler parameters to generate an in memory assembly, with debug
            // symbols if this is a debug build
            // the referenceString is a comma delimited string identifying all references needed by the script
            CompilerParameters cparams = new CompilerParameters();
 
            cparams.GenerateInMemory = true;
 
            #if DEBUG
                // create debug symbols if this is a debug build
                cparams.IncludeDebugInformation = true;
                cparams.CompilerOptions += " /debug:pdbonly";
            #endif
 
            cparams.TreatWarningsAsErrors = false;
            cparams.GenerateExecutable = false; 
 
            // seperate reference string
            string[] references = referenceString.Split(',');
 
            foreach (string reference in references)
                cparams.ReferencedAssemblies.Add(reference);
 
            return cparams;
        }
    }
}

App Showing How to Use Script.cs

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;
using System.IO;
 
namespace ScriptingExample
{
    // we have to define an interface so we know how to "talk" to
    // the script, that is, there must be a type that we *know* the
    // script implements so we can call methods on it
    public interface MyScript
    {
        void Execute();
    }
 
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
        }
 
        private void Form1_Load(object sender, EventArgs e)
        {
            // just populate the combo box with all "scripts" located in the directory "Scripts"
            foreach (string file in Directory.GetFiles("Scripts"))
                comboBox1.Items.Add(file);
 
            if (comboBox1.Items.Count > 0)
                comboBox1.SelectedIndex = 0;
            else
            {
                button1.Enabled = false;
                comboBox1.Enabled = false;
            }
        }
 
        private void button1_Click(object sender, EventArgs e)
        {
            // load the script, which contains a type that implements MyScript
            // and call the execute method on it
            Script s = new Script();
 
            // these are the references the script will need, we must reference this executable
            // because the script needs to see the MyScript data type
            // this is just a sample, in a real application such types would be defined in an assembly dll
            // that is shared between the app consuming the script and the script itself
            string references = "System.dll,System.Windows.Forms.dll," + Directory.GetCurrentDirectory() + "\\ScriptingExample.exe";
 
            MyScript script = s.LoadScript<MyScript>(comboBox1.SelectedItem as string, references);
 
            script.Execute();
        }
    }
}

A VB and C# Script

using System;
using System.Collections.Generic;
using System.Text;
using System.Windows.Forms;
 
namespace ScriptingExample.Scripts
{
    public class CSharpScript : MyScript
    {
        public void Execute()
        {
            MessageBox.Show("I AM A C# SCRIPT");
        }
    }
}

Imports System
Imports System.Collections.Generic
Imports System.Text
Imports System.Windows.Forms
 
Namespace ScriptingExample.Scripts
    Public Class VBScript
        Implements MyScript
        Public Sub Execute() Implements MyScript.Execute
            MessageBox.Show("I AM A VB SCRIPT!!")
        End Sub
    End Class
End Namespace

Conclusion

And that’s it! A very simple technique that can be used in many interesting ways. I’ve included a link to a Visual Studio project containing an implementation using the above information. The project can be found here As always, let me know if you have any questions or ideas!

See ya next time!

Using Ini Files In C#

crow — Thu, 16 Jul 2009 23:26:32 +0000

An Initialization, or Ini file, is a common text based file format commonly used on the Windows platform. Today its mostly been succeeded in favor of XML files for application configuration and persisting user data. Never the less, these files still exist and are in use by many applications. In this post, we will explore how to work with Ini files via C#.

The structure of an Ini file is very simple and straight forward. You have three primary types of information: sections, parameters, and values. They look like this:

[SectionA]
Parameter1=value1
Parameter2=value2

[SectionB]
Parameter1=value1

Below we will create a class to read this data from a file. Keep in mind as you look at this C# Ini file implementation that this is just one way to do it. You could for example, create a much more concise solution using regular expressions, etc.

Parsing the Data

The first thing we should do if figure out how to get the data from the Ini file. We could read in all the text and manually parse the file; however there is an easier approach. The Win32 API contains a function called GetPrivateProfileString that we can use specifically for this task. We can use it to directly obtain the sections, parameters, and values. For a more detailed description of the GetPrivateProfileString function, check out this link on MSDN.

To use GetPrivateProfileString in C#, we need only reference it using the DLLImport attribute with the correct function signature.

        [DllImport("Kernel32.dll", EntryPoint = "GetPrivateProfileStringW", SetLastError = true, CharSet = CharSet.Unicode, ExactSpelling = true, CallingConvention = CallingConvention.StdCall)]
        public static extern int GetPrivateProfileString(string lpAppName,
                                                         string lpKeyName,
                                                         string lpDefault,
                                                         [In, Out] char[] lpReturnString,
                                                         int nSize,
                                                         string lpFilename);

Reading from an Ini File

First, to make our job a little easier we will wrap the call to GetPrivateProfileString with our own method so that we can handle all of the details. Here is the wrapper:

        private string[] GetPrivateProfileString(string appName, string keyName, string defaultName, string inifile)
        {
            // the file inifile should exist as it's validated in the class constructor, however GetPrivateProfileString does not lock the file hence it could be locked or deleted by
            // another process between calls to this method
 
            // used to tell if we successfully read all requested data from the file 
            // from MSDN:
            //  If neither lpAppName nor lpKeyName is NULL and the supplied destination buffer is too small to hold the requested string, the string is truncated and followed by a null character, and the return value is equal to nSize minus one.
            //  If either lpAppName or lpKeyName is NULL and the supplied destination buffer is too small to hold all the strings, the last string is truncated and followed by two null characters. In this case, the return value is equal to nSize minus two.
            int sizeReadOffset = (appName != null && keyName != null) ? 1 : 2;
 
            // try and read the entire amount of data from the ini file
            int sizeRead = Kernel32.GetPrivateProfileString(appName, keyName, defaultName, _readBuffer, _readBufferSize, inifile);
 
            // if unable to read all of the data because the buffer is to small, increase the size and try again, but only allow memory to increase up to _readBufferMaxSize
            while ((sizeRead >= _readBufferSize - sizeReadOffset) && (_readBufferSize < _readBufferMaxSize))
            {
                _readBufferSize += 512;
                _readBuffer = new char[_readBufferSize];
 
                sizeRead = Kernel32.GetPrivateProfileString(appName, keyName, defaultName, _readBuffer, _readBufferSize, inifile);
            }
 
            // if memory consumption exceeded _readBufferMaxSize then we have a problem
            if (_readBufferSize >= _readBufferMaxSize)
                throw new FileLoadException("ErrorBadIniLoad");
 
            // the buffer returned from GetPrivateProfileString will be null terminated C-strings followed by a double null at the end - so split the strings on the nulls
            char[] sep = new char[1];
            sep[0] = '\0';
 
            string s = new string(_readBuffer, 0, sizeRead);
 
            string[] result = s.Split(sep, StringSplitOptions.RemoveEmptyEntries);
 
            return result;
        }

Here, the MSDN terminology refers to what I call a section as an appName and what I refer to as a paramter as a keyName.

This method has a lot going on but is very easy to use. To get an array of strings containing all of the section names you simply say:

string[] raw = GetPrivateProfileString(null, null, null, filename);

And, to get an array of all parameter names for a particular section you would say:

string[] raw = GetPrivateProfileString(sectionName, null, null, inifileName);

And finally, to get a parameter value you could say:

string[] raw = GetPrivateProfileString(sectionName, parameterName, null, inifile);

And the value is stored in the first element of the returned array.

Putting it All Together

So now we can put together a simple class encapsulating the above functionality. You can use this class as follows:

Given an Ini file:

[SectionA]
Parameter1=value1
Parameter2=value2

[SectionB]
Parameter1=value1

You could,

            INIFile file =  new INIFile(Directory.GetCurrentDirectory() + Path.DirectorySeparatorChar + "MyInifile.ini");
 
            string a1 = file["SectionA","Parameter1"]; // returns "value1"
            string a2 = file["SectionA","Parameter2"]; // returns "value2"
 
            string b1 = file["SectionB", "Parameter1"]; // returns "value1"

Have fun playing with it. You could easily add the ability to write new sections and parameters as well. If you make some changes, find some bugs, or just plain find it useful let me know. I am always interested.

Here is the complete code listing for the class. You can download it here or just copy and paste it.

    /// 
    /// Contains native Win32 API methods found in Kernel32. 
    /// 
    public static class Kernel32
    {
        /// 
        /// Retrieves a string from the specified section in an initialization file.
        /// 
        /// The name of the section containing the key name. If this parameter is NULL, the GetPrivateProfileString function copies all section names in the file to the supplied buffer.
        /// The name of the key whose associated string is to be retrieved. If this parameter is NULL, all key names in the section specified by the lpAppName parameter are copied to the buffer specified by the lpReturnedString parameter.
        /// A default string. If the lpKeyName key cannot be found in the initialization file, GetPrivateProfileString copies the default string to the lpReturnedString buffer. If this parameter is NULL, the default is an empty string, "".
        ///                         Avoid specifying a default string with trailing blank characters. The function inserts a null character in the lpReturnedString buffer to strip any trailing blanks.
        /// A pointer to the buffer that receives the retrieved string.
        /// The size of the buffer pointed to by the lpReturnedString parameter, in characters.
        /// The name of the initialization file. If this parameter does not contain a full path to the file, the system searches for the file in the Windows directory.
        /// The return value is the number of characters copied to the buffer, not including the terminating null character.
        [DllImport("Kernel32.dll", EntryPoint = "GetPrivateProfileStringW", SetLastError = true, CharSet = CharSet.Unicode, ExactSpelling = true, CallingConvention = CallingConvention.StdCall)]
        public static extern int GetPrivateProfileString(string lpAppName,
                                                         string lpKeyName,
                                                         string lpDefault,
                                                         [In, Out] char[] lpReturnString,
                                                         int nSize,
                                                         string lpFilename);
 
    }
 
 
    /// 
    /// Represents the common INI file format consisting of parameter-value pairs grouped by sections.
    /// 
    public class INIFile
    {
        #region Nested Types
        public enum CaseSensitiviy
        {
            CaseInsensitive,
            CaseSensitive
        }
        #endregion
 
        #region Properties
        /// 
        /// Provides the string value of parameter belonging to the specified section. The section and parameter must exist.
        /// 
        /// The name of the section the parameter belongs to.
        /// The name of the parameter containing the value.
        /// Thrown if either the section or parameter name do not exist.
        /// The value of the parameter.
        public string this[string sectionName, string parameterName]
        {
            get
            {
                if (_sections.ContainsKey(sectionName))
                {
                    if (_sections[sectionName].ContainsKey(parameterName))
                        return _sections[sectionName][parameterName];
                    else
                        throw new ArgumentException("ErrorBadIniFile");
                }
                else
                    throw new ArgumentException("ErrorBadIniFile");
            }
        }
 
        /// 
        /// Specifies what case sensitivity mode is being used when looking up section and parameter names.
        /// 
        public CaseSensitiviy CaseSensitivity
        {
            get { return _caseSensitivity; }
        }
        #endregion
 
        #region Events
        #endregion
 
        #region Constructors
        /// 
        /// Loads the specified INI file. By default, all searches for section and parameter names will be case sensitive.
        /// 
        /// The file name and path to the INI file. If this parameter does not contain a full path to the file, the method will search the Windows directory.
        /// Thrown if filename could not be found and doesn't exist in the Window directory.
        public INIFile(string filename) :
            this(filename, CaseSensitiviy.CaseSensitive)
        {
 
        }
 
        /// 
        /// Loads the specified INI file.
        /// 
        /// The file name and path to the INI file. If this parameter does not contain a full path to the file, the method will search the Windows directory.
        /// Specifies if letter case should be accounted for when looking up section and parameter names.
        /// Thrown if filename could not be found and doesn't exist in the Window directory.
        public INIFile(string filename, CaseSensitiviy sensitivity)
        {
            // make sure the file exists, directly, or in the Windows directory
            if (!File.Exists(filename))
                if (!File.Exists(Path.Combine(Environment.ExpandEnvironmentVariables("%WinDir%"), filename)))
                    throw new FileNotFoundException();
 
            // save local state
            _caseSensitivity = sensitivity;
            _readBufferSize = _readBufferDefaultSize;
            _readBuffer = new char[_readBufferSize];
 
            // read all section names
            string[] raw = GetPrivateProfileString(null, null, null, filename);
 
            // the data is stored in a dictionary, we must tell it if case sensitivity is important
            if (_caseSensitivity == CaseSensitiviy.CaseInsensitive)
                _sections = new Dictionary<string, IDictionary<string, string>>(StringComparer.CurrentCultureIgnoreCase);
            else
                _sections = new Dictionary<string, IDictionary<string, string>>();
 
            // now, read in all parameters and values for each section name we located
            foreach (string s in raw)
                ReadSection(filename, s, _sections);
        }
        #endregion
 
        #region Public Methods
        /// 
        /// Checks to see if a given section exists in the Ini file.
        /// 
        /// The section name to check for.
        /// True if the section exists, false if not.
        public bool DoesSectionExist(string sectionName)
        {
            return _sections.ContainsKey(sectionName);
        }
 
        /// 
        /// Checks to see if a given parameter exists for a section.
        /// 
        /// The name of the section containing the parameter.
        /// The name of the parameter to check for.
        /// True if the parameter exists, false if not.
        public bool DoesParameterExist(string sectionName, string parameterName)
        {
            if (DoesSectionExist(sectionName))
                return _sections[sectionName].ContainsKey(parameterName);
            else
                return false;
        }
        #endregion
 
        #region Private Methods
        /// 
        /// Reads all parameters and values for a given section within the Ini file.
        /// 
        /// The ini file to read from.
        /// The name of the section to read.
        /// A dictionary containing an entry for the section that will be populated with the resulting parameters/values.
        private void ReadSection(string inifile, string sectionName, IDictionary<string, IDictionary<string, string>> storage)
        {
            // create the parameter/value dictionary for the section entry
            // it is assumed that the callers logic created/validated storage[sectionName] -- we will not check again here
            if (_caseSensitivity == CaseSensitiviy.CaseInsensitive)
                storage[sectionName] = new Dictionary<string, string>(StringComparer.CurrentCultureIgnoreCase);
            else
                storage[sectionName] = new Dictionary<string, string>();
 
            string[] raw = GetPrivateProfileString(sectionName, null, null, inifile);
 
            // now read in the values for the parameters that we found
            foreach (string s in raw)
                ReadParameter(inifile, sectionName, s, storage[sectionName]);
        }
 
        /// 
        /// Reads the value of a parameter in a given section within the Ini file.
        /// 
        /// The ini file to read from.
        /// The name of the section containing the parameter.
        /// The name of the parameter to read.
        /// The dictionary that the parameter value will be written to.
        /// Thrown if more than 1 value is associated with a single parameter.
        private void ReadParameter(string inifile, string sectionName, string parameterName, IDictionary<string, string> storage)
        {
            // get the param value
            string[] raw = GetPrivateProfileString(sectionName, parameterName, null, inifile);
 
            // store the resulting value, if more than 1 value comes back for the parameter throw an exception, not sure how to parse that scenario
            // if no values come back just use an empty string by default
            if (raw.Length > 1)
                throw new ArgumentException("ErrorBadIniFile");
            else if (raw.Length == 0)
                storage[parameterName] = "";
            else
                storage[parameterName] = raw[0];
        }
 
        /// 
        /// Wrapper around the Win32 function GetPrivateProfileString to make it nicer and more robust.
        /// 
        /// The name of the section containing the key name. If this parameter is null, all section names will be returned.
        /// The name of the key whose associated string is to be retrieved. If this parameter is null, all key names in the section will be returned.
        /// A default string. If the keyName key cannot be found in the initialization file, GetPrivateProfileString copies the default string to the 
        ///                           returned value. If this parameter is null, the default is an empty string, "".
        /// The path and file name of the INI file. If this parameter does not contain a full path to the file, the system searches for the file in the Windows directory.
        /// An array of string containing either section names, parameter names, or values corresponding to appName and keyName.
        /// 
        private string[] GetPrivateProfileString(string appName, string keyName, string defaultName, string inifile)
        {
            // the file inifile should exist as it's validated in the class constructor, however GetPrivateProfileString does not lock the file hence it could be locked or deleted by
            // another process between calls to this method
 
            // used to tell if we successfully read all requested data from the file 
            // from MSDN:
            //  If neither lpAppName nor lpKeyName is NULL and the supplied destination buffer is too small to hold the requested string, the string is truncated and followed by a null character, and the return value is equal to nSize minus one.
            //  If either lpAppName or lpKeyName is NULL and the supplied destination buffer is too small to hold all the strings, the last string is truncated and followed by two null characters. In this case, the return value is equal to nSize minus two.
            int sizeReadOffset = (appName != null && keyName != null) ? 1 : 2;
 
            // try and read the entire amount of data from the ini file
            int sizeRead = Kernel32.GetPrivateProfileString(appName, keyName, defaultName, _readBuffer, _readBufferSize, inifile);
 
            // if unable to read all of the data because the buffer is to small, increase the size and try again, but only allow memory to increase up to _readBufferMaxSize
            while ((sizeRead >= _readBufferSize - sizeReadOffset) && (_readBufferSize < _readBufferMaxSize))
            {
                _readBufferSize += 512;
                _readBuffer = new char[_readBufferSize];
 
                sizeRead = Kernel32.GetPrivateProfileString(appName, keyName, defaultName, _readBuffer, _readBufferSize, inifile);
            }
 
            // if memory consumption exceeded _readBufferMaxSize then we have a problem
            if (_readBufferSize >= _readBufferMaxSize)
                throw new FileLoadException("ErrorBadIniLoad");
 
            // the buffer returned from GetPrivateProfileString will be null terminated C-strings followed by a double null at the end - so split the strings on the nulls
            char[] sep = new char[1];
            sep[0] = '\0';
 
            string s = new string(_readBuffer, 0, sizeRead);
 
            string[] result = s.Split(sep, StringSplitOptions.RemoveEmptyEntries);
 
            return result;
        }
        #endregion
 
        #region Fields
        /// 
        /// Stores the sections from the Ini file. The section name is the key. The value is another dictionary containing the parameter values, keyed on the parameter name.
        /// 
        private IDictionary<string, IDictionary<string, string>> _sections;
 
        /// 
        /// Determines if case is ignored or not when referencing section and parameter names.
        /// 
        private CaseSensitiviy _caseSensitivity;
 
        /// 
        /// Holds the information from the last read of the ini file. The buffer is overwritten with sections, parameters, or values on each call to GetPrivateProfileString.
        /// 
        private char[] _readBuffer;
 
        /// 
        /// The size, in bytes, of _readBuffer.
        /// 
        private int _readBufferSize;
 
        /// 
        /// The starting size of _readBuffer, in bytes.
        /// 
        private const int _readBufferDefaultSize = 1024;
 
        /// 
        /// The maximum size _readBuffer is allowed to grow to in order to hold all information obtained from GetPrivateProfileString.
        /// 
        private const int _readBufferMaxSize = 4096;
        #endregion
    }

Accessing the System Task Bar in C#

crow — Sun, 10 May 2009 06:56:18 +0000

In this post I’ll show you how to access the system taskbar and obtain information like its location, size, etc. You may find yourself needing to do something like this if you had a “popup” window for instance that is always supposed to “pop up” from the system tray. This is a common feature in many of today’s applications; however the task bar may be docked somewhere other than the bottom of the screen or maybe even on a different monitor in a multi-monitor setup.

The Taskbar is an APPBAR

First, the task bar is considered an appbar (or desktop application toolbar) albeit with some special restrictions. Being an appbar we can talk to it with the Win32 API function SHAppBarMessage. SHAppBarMessage allows us to send a message to the system to get or set information about a registered appbar. The necessary C# definitions to access the function are as follows:

[StructLayout(LayoutKind.Sequential)]
private struct RECT
{
public int left;
      public int top;
      public int right;
      public int bottom;
}
 
[StructLayout(LayoutKind.Sequential)]
private struct APPBARDATA
{
public Int32 cbSize;
      public IntPtr hWnd;
      public Int32 uCallbackMessage;
      public ABEdge uEdge;
      public RECT rc;
      public IntPtr lParam;
}
 
private enum ABMsg
{
ABM_NEW = 0,
      ABM_REMOVE = 1,
      ABM_QUERYPOS = 2,
      ABM_SETPOS = 3,
      ABM_GETSTATE = 4,
      ABM_GETTASKBARPOS = 5,
      ABM_ACTIVATE = 6,
      ABM_GETAUTOHIDEBAR = 7,
      ABM_SETAUTOHIDEBAR = 8,
      ABM_WINDOWPOSCHANGED = 9,
      ABM_SETSTATE = 10
}
 
private enum ABEdge
{
ABE_LEFT = 0,
      ABE_TOP = 1,
      ABE_RIGHT = 2,
      ABE_BOTTOM = 3,
}
 
private enum ABState
{
ABS_MANUAL = 0,
      ABS_AUTOHIDE = 1,
      ABS_ALWAYSONTOP = 2,
      ABS_AUTOHIDEANDONTOP = 3
}
 
[DllImport("shell32.dll")]
private static extern IntPtr SHAppBarMessage(ABMsg dwMessage, [In, Out] ref APPBARDATA pData);

Using SHAppBarMessage

In order to use SHAppBarMessage we must first fill out the APPBAR struct with at least the cbSize and hWnd members. For hWnd we need to get the handle to the system taskbar window. It just so happens that you can use the FindWindow API function with a system class name of “Shell_TrayWnd” to get the required handle. Of course, to the best of my knowledge the class name “Shell_TrayWnd” is not a “documented” part of the Win32 system therefore it could change with any Windows release. However, I think it’s probably a safe bet to rely on it given the number of applications in the field that already do. Without further ado, some code to get the size of the task bar.

[DllImport("user32.dll")]
private static extern IntPtr FindWindow(string lpClassName, string lpWindowName);
 
APPBARDATA appBar = new APPBARDATA();
 
appBar.hWnd = FindWindow("Shell_TrayWnd", "");
appBar.cbSize = Marshal.SizeOf(appBar);
 
System.IntPtr ret = SHAppBarMessage(ABMsg.ABM_GETTASKBARPOS, ref appBar);
 
Size s = new Size(appBar.rc.right - appBar.rc.left, appBar.rc.bottom - appBar.rc.top);

Simple right?

Modifying the Taskbar

Remember earlier I said the system taskbar is not quite like a normal appbar? Well it’s special in that you can’t really change any of its properties like its size or position. This makes sense as you wouldn’t just want any program you install to play with the users taskbar; it’s sort of like an invasion of privacy. I’ve seen claims around the Internet that this can be pulled off in application code, which may be true prior to Vista; however I’ve tried all kinds of tricks based on SHAppBarMessage and can’t change the taskbar properties under Vista. Do you know how this can be done or if it’s even possible? I have found that you can change the task bar state. That is, you can toggle between “autohide” mode and “always on top” mode.

Example Taskbar Code

So, here is a little class I’ve put together to wrap the SHAppBarMessage functionality. I really haven’t paid attention to error handling or anything with it so if you use this you would need to address that.

using System;
using System.Collections.Generic;
using System.Text;
using System.Runtime.InteropServices;
using System.Drawing;
 
namespace TaskbarInfoExample
{
    /// 
    /// Provides methods for obtaining and modifying information for the system taskbar.
    /// 
    class TaskBar
    {
        #region Native API
        // The native API functions/enums/structs needed to access taskbar info
        // consult MSDN for more detailed information about them
        [StructLayout(LayoutKind.Sequential)]
        private struct RECT
        {
            public int left;
            public int top;
            public int right;
            public int bottom;
        }
 
        [StructLayout(LayoutKind.Sequential)]
        private struct APPBARDATA
        {
            public Int32 cbSize;
            public IntPtr hWnd;
            public Int32 uCallbackMessage;
            public ABEdge uEdge;
            public RECT rc;
            public IntPtr lParam;
        }
 
        private enum ABMsg
        {
            ABM_NEW = 0,
            ABM_REMOVE = 1,
            ABM_QUERYPOS = 2,
            ABM_SETPOS = 3,
            ABM_GETSTATE = 4,
            ABM_GETTASKBARPOS = 5,
            ABM_ACTIVATE = 6,
            ABM_GETAUTOHIDEBAR = 7,
            ABM_SETAUTOHIDEBAR = 8,
            ABM_WINDOWPOSCHANGED = 9,
            ABM_SETSTATE = 10
        }
 
        private enum ABEdge
        {
            ABE_LEFT = 0,
            ABE_TOP = 1,
            ABE_RIGHT = 2,
            ABE_BOTTOM = 3,
        }
 
        private enum ABState
        {
            ABS_MANUAL = 0,
            ABS_AUTOHIDE = 1,
            ABS_ALWAYSONTOP = 2,
            ABS_AUTOHIDEANDONTOP = 3
        }
 
        [DllImport("shell32.dll")]
        private static extern IntPtr SHAppBarMessage(ABMsg dwMessage, [In, Out] ref APPBARDATA pData);
 
        [DllImport("user32.dll")]
        private static extern IntPtr FindWindow(string lpClassName, string lpWindowName);
        #endregion
 
        /// 
        /// Represents the edge of the screen the task bar is docked to.
        /// 
        public enum TaskBarEdge
        {
            Left = ABEdge.ABE_LEFT,
            Top = ABEdge.ABE_TOP,
            Right = ABEdge.ABE_RIGHT,
            Bottom = ABEdge.ABE_BOTTOM
        }
 
        /// 
        /// The states the task bar can be in.
        /// 
        [Flags]
        public enum TaskBarState
        {
            /// 
            /// No autohide, not always top
            /// 
            None = ABState.ABS_MANUAL,
 
            /// 
            /// Hides task bar when mouse exits task bar region
            /// 
            AutoHide = ABState.ABS_AUTOHIDE,
 
            /// 
            /// Taskbar is always on top of other windows
            /// 
            AlwaysTop = ABState.ABS_ALWAYSONTOP
        }
 
        /// 
        /// Gets the location, in screen coordinates of the task bar.
        /// 
        /// The taskbar location.
        public static Point GetTaskBarLocation()
        {
            APPBARDATA appBar = GetTaskBarData();
 
            return new Point(appBar.rc.left, appBar.rc.top);
        }
 
        /// 
        /// Gets the size, in pixels of the task bar.
        /// 
        /// The taskbar size.
        public static Size GetTaskBarSize()
        {
            APPBARDATA appBar = GetTaskBarData();
 
            return new Size(appBar.rc.right - appBar.rc.left, appBar.rc.bottom - appBar.rc.top);
        }
 
        /// 
        /// Gets the edge of the screen that the task bar is docked to.
        /// 
        /// 
        public static TaskBarEdge GetTaskBarEdge()
        {
            APPBARDATA appBar = GetTaskBarData();
 
            return (TaskBarEdge)appBar.uEdge;
        }
 
        /// 
        /// Gets the current state of the taskbar.
        /// 
        /// 
        public static TaskBarState GetTaskBarState()
        {
            APPBARDATA appBar = CreateAppBarData();
 
            return (TaskBarState)SHAppBarMessage(ABMsg.ABM_GETSTATE, ref appBar);
        }
 
        /// 
        /// Sets the state of the task bar.
        /// 
        /// The new state.
        public static void SetTaskBarState(TaskBarState state)
        {
            APPBARDATA appBar = CreateAppBarData();
 
            appBar.lParam = (IntPtr)state;
 
            SHAppBarMessage(ABMsg.ABM_SETSTATE, ref appBar);
        }
 
        /// 
        /// Gets an APPBARDATA struct with valid location,size,and edge of the taskbar.
        /// 
        /// 
        private static APPBARDATA GetTaskBarData()
        {
            APPBARDATA appBar = CreateAppBarData();
 
            System.IntPtr ret = SHAppBarMessage(ABMsg.ABM_GETTASKBARPOS, ref appBar);
 
            return appBar;
        }
 
        /// 
        /// Creats an APPBARDATA struct with its hWnd member set to the task bar window.
        /// 
        /// 
        private static APPBARDATA CreateAppBarData()
        {
            APPBARDATA appBar = new APPBARDATA();
 
            appBar.hWnd = FindWindow("Shell_TrayWnd", "");
            appBar.cbSize = Marshal.SizeOf(appBar);
 
            return appBar;
        }
    }
}

That’s All!

That’s all I’ve got for now. I have included a little demo app you can download to demonstrate the class. You can find that here Basically it just allows you to modify the task bar state and shows you all of its properties.

Hope you found this useful and saved yourself some time!

Launching and Viewing Processes in C#

crow — Wed, 15 Apr 2009 05:23:19 +0000

You can launch a new process from a C# application by using the Process class located in the System.Diagnostics namespace. The Process class also allows you to obtain a collection of all running processes on the system.

How to Launch a New Process

Starting a process is really easy.

Process.Start( "Notepad.exe" );

And that’s it. If Notepad.exe exists on your system then it will start. Make sure that if you do not specify a complete path then the name you do present is available in your environment path. You can wait for the newly created process to terminate as well.

Process p = Process.Start( "Notepad.exe");
 
p.WaitForExit();

Keep in mind that WaitForExit will block the calling thread. If you don’t want that behavior considering launching the new process on a thread of its own. You can also use the ProcessStartInfo class to pass information to the Start method. This example launches the new process on a thread from the thread pool via an anonymous method. Remember to include System.Threading.

// launch the program / process on a new thread from the thread pool
ThreadPool.QueueUserWorkItem( (WaitCallback)delegate(object state)
{
    ProcessStartInfo psi = new ProcessStartInfo("Notepad.exe", "");
 
    Process p = Process.Start(psi);
 
    p.WaitForExit();
});

Passing Arguments to the New Process

You can also pass arguments to a new process. The next example will launch Notepad and tell it to open the file MyFile.txt.

ProcessStartInfo psi = new ProcessStartInfo("Notepad.exe", @"C:\My\Path\MyFile.txt");
 
Process p = Process.Start(psi);

Launching a Document and Setting the Verb

There are some other interesting things you can do with the Process class. For instance, instead of specifying a file name in Process.Start like we did above with Notepad.exe, we could specify a file or document. The method would then open that file with the registered default application for that type of file. You can also specify a verb that is associated with that file type. A verb represents an action that is associated with that file type. So, if I wanted to launch the default application for a .txt file and have that file printed I could do the following:

ProcessStartInfo psi = new ProcessStartInfo(@"C:\My\Path\MyFile.txt");
psi.Verb = "print";
 
Process p = Process.Start(psi);
 
p.WaitForExit();

Listing All Running Processes

The last thing I want to show you is how easy it is to view a list of all processes running on the system with C#. Assuming you have a ListBox name listbox1, the following code fragment would add an entry to the ListBox with the name of each process running on the system.

Process[] processes = Process.GetProcesses();
 
foreach( Process process in processes )
   listBox1.Items.Add( process.ProcessName );

Well, that’s it for today. Hope this information comes in handy for some of you!

How To Get Screen Shot Capture in C#

crow — Mon, 13 Apr 2009 06:36:10 +0000

It’s often necessary to programmatically get a screen shot of the desktop and save it to a file. This is pretty easy with C#; we can create a simple method that will save an image of whatever is on the screen or desktop.

Saving a Bitmap Image of the Screen

First make sure you include the System.Drawing.Imaging namespace. Now, all we really have to do is create a new bitmap and use the CopyFromScreen method of the bitmaps Graphics device.

/// 
/// Saves a screen capture in the specified image format to a file.
/// 
/// 
/// 
private void SaveScreenShot(string filename, ImageFormat format)
{
        Bitmap screenShot = CaptureScreenShot();
 
  	screenShot.Save(filename, format);
}
 
/// 
/// Saves a picture of the screen to a bitmap image.
/// 
/// The saved bitmap.
private Bitmap CaptureScreenShot()
{
 	// get the bounding area of the screen containing (0,0)
        // remember in a multidisplay environment you don't know which display holds this point
    	Rectangle bounds = Screen.GetBounds(Point.Empty);
 
    	// create the bitmap to copy the screen shot to
   	Bitmap bitmap = new Bitmap(bounds.Width, bounds.Height);
 
    	// now copy the screen image to the graphics device from the bitmap
   	using (Graphics gr = Graphics.FromImage(bitmap))
   	{
       	   gr.CopyFromScreen(Point.Empty, Point.Empty, bounds.Size);
   	}
 
  	return bitmap;
}

And that’s really all there is to capturing a screen shot. You can save it to whatever file you would like and in any of the image formats supported by ImageFormat such as PNG or JPEG. Keep in mind if your working in a multidisplay environment you’ll want to be careful which display your targeting. Or perhaps you may want a huge image of all the desktop displays.

You can use the above code simply by calling the SaveScreenShot method with a file name and image format to save to:

//save screen shot in PNG image format
SaveScreenShot("MyScreenShot.png", ImageFormat.Png);

With a really small change you can modify the above code to save a screen shot of an arbitrary control instead of the entire desktop display.

Saving a Screen Capture of a Control

/// 
/// Saves a screen capture of the specified control to a file.
/// 
/// 
/// 
/// 
private void SaveControlShot(Control control, string filename, ImageFormat format)
{
   	Bitmap controlShot = CaptureControlShot(control);
 
   	controlShot.Save(filename, format);
}
 
/// 
/// Gets a bitmap image of the specified control.
/// 
/// 
/// 
private Bitmap CaptureControlShot(Control control)
{
        // get control bounding rectangle
     	Rectangle bounds = control.Bounds;
 
   	// create the new bitmap that holds the image of the control
     	Bitmap bitmap = new Bitmap(bounds.Width, bounds.Height);
 
   	// copy controls image data to the bitmaps graphics device
    	using (Graphics gr = Graphics.FromImage(bitmap))
    	{
        	gr.CopyFromScreen(control.Location, Point.Empty, bounds.Size);
     	}
 
    	return bitmap;
}

And you can use this just as easily as the previous screen capture method:

// if "this" is a control, like a form
SaveControlShot(this, "MyControlShot.png", ImageFormat.Png);

And there you have it, an example of simple methods for saving a screen shot or an image of a control. I Hope you find this helpful.

Introduction to Multithreading in C#

crow — Thu, 09 Apr 2009 00:34:18 +0000

This article is a very basic introductory tutorial for using multiple threads in C#. I’ll explain what threads are, why you would want to use them, and how to use them. I’ll also show you several examples for creating threads, killing threads, etc.

What’s a Thread?

A computer program is generally very linear. That is, you have a sequence of instructions that get executed one after another in an orderly and predictable fashion. This scenario only affords you one path of execution. Threads allow you to execute multiple paths of code simultaneously. Now, simultaneously in this case does not necessarily mean physically at the same time. Both your operating system and processor must support this for that to be true. Threads are not particular to C#; most modern programming languages such as Visual Basic.Net support the concept of threads.

So Why Do I Need Multiple Threads?

Threading is handy because many programming tasks are asynchronous. That is, I can start the task and go on about my business and when that task is finished it can let me know and I can take action. An example of this would be downloading files from a remote location. I can start downloading three files and when the first is finished I can process it while the others continue to download.

There are numerous other reasons. Consider for instance a long task like sorting a million numbers. If I start that task on the thread that runs the GUI then I couldn’t update my user interface which means I couldn’t respond to user requests like button clicks.

Ok, lets move on to an example of creating a new thread via C#.

Creating a Thread with C#

Creating a thread is easy; we make use of the Thread object from the System.Threading namespace. When we create the thread we must pass it a ParameterizedThreadStart or ThreadStart delegate. This will be the method that gets invoked on the new thread – it’s the starting point. New threads begin life in a stopped state. To make it run we call the Thread.Start method.

Thread myThread = new Thread(MyThreadFunction);
myThread.Start();
 
private void MyThreadFunction()
{
   MessageBox.Show("HI");
}

Congratulations, you’ve created your first thread that runs in parallel with your main thread.

Passing an Argument to the New Thread

You can easily pass an argument to the thread like so:

Thread myThread = new Thread(MyThreadFunction);
myThread.Start("HELLO WORLD");
 
private void MyThreadFunction(object x)
{
   MessageBox.Show(x as string);
}

Keep in mind that this is not the best way to pass data to the thread. Since Thread.Start accepts only an object this is not very type safe. Image if we didn’t pass a string or the object didn’t have a ToString method. The best way to accomplish this would be to encapsulate your thread function in a class with data members you could set ahead of time.

Waiting for a Thread to Stop

Now that we have our thread up and running, we may at some point wish to wait for it to complete. This is accomplished with the Thread.Join method. Here is an example for Thread.Join:

myThread = new Thread(MyThreadFunction);
myThread.Start("HELLO WORLD");
 
myThread.Join();
 
MessageBox.Show("ALL DONE!");
 
//-elsewhere
private void MyThreadFunction(object x)
{
   MessageBox.Show(x as string);
}

When the first piece of code executes it will create a new thread that will begin running in MyThreadFunction. After calling myThread.join that thread will go to sleep and stop executing until MyThreadFunction returns. This will happen after you dismiss the message box. Finally, when MyThreadFunction exits and the thread is destroyed, the original thread will continue execution at the next statement and pop its message box.

One thing to watch out for is what happens if the thread function never returns meaning the thread never dies. In this situation you can specify a timeout value in Thread.Join. The method will block for a predetermined amount of time waiting for the thread to terminate. If the thread did not terminate then Thread.Join would return false.

Stopping a Thread

Stopping a thread is simple. You call Thread.Abort on the thread you wish to stop.

myThread.Abort();

This will cause a ThreadAbortException to be raised on the thread you are trying to stop. Now this usually stops the thread. It’s possible that the thread can abort your abort and continue living. There are a few other circumstances that can prevent the thread from aborting.

Sharing Variables

When you have two or more threading running it’s possible that they could be executing at the same time. This can create problems when both threads are trying to read/write to the same variable. You have to synchronize thread access to shared variables. There are many synchronization primitives available to you in C# via the .Net Framework Library such as AutoResetEvent, Monitor, and Mutex. This is a big subject so I will defer it till another post.

Along those same lines here’s a tip: If you create secondary threads they cannot modify controls on your GUI. Only the thread that created a control can modify its properties. You will generate the dreaded illegal cross thread exception. I’ve already posted a brief work around for this problem

So that’s it for my C# threading tutorial. Now you know the basics of how to create a thread, how to kill a thread, how to wait for a thread, and some general threading principles. This is a big subject and I’ve hardly done it justice with this little bit of writing. If there are sufficient interests, I will elaborate on some more advance multithreading techniques that are applicable in all .Net languages – not just C#. I’ll leave you with a small incomplete pro and con list about using multiple threads.

Advantages of Multithreading

Improved performance – Multiple threads can execute concurrently.
Streamline application logic – Some tasks are easier to conceptualize this way
Improves responsiveness of an application – GUI still works under heavy load.

Disadvantages of Multithreading

Hard to write and debug – Nuff said!!
Performance impact from synchronizing access to shared variables
There is a limit to how many threads an operating system can handle efficiently
Context switching between threads can hurt performance

Playing an MP3 or WAV File in C#

crow — Sun, 05 Apr 2009 05:43:20 +0000

Playing an audio file such as an MP3 or WAV is incredibly easy in C#. For WAV files you can use the SoundPlayer class found in the System.Media namespace. Playing an MP3 will require referencing the Windows Media Player COM component.

How to Play a WAV file

To play the WAV file simply create a new SoundPlayer object, set the SoundLocation property to the location of your WAV file, and then use the Play method to play it.

System.Media.SoundPlayer player = new System.Media.SoundPlayer();
 
player.SoundLocation = "My Wav File.wav";
player.Play();

How to Play an MP3 file

Playing an MP3 with C# is just as easy as playing a WAV except that it requires you to use the Window Media Player COM component. So first, add a reference to wmp.dll, which you can find in the System32 directory. Here is an example of how to play an MP3 file:

WMPLib.WindowsMediaPlayer wplayer = new WMPLib.WindowsMediaPlayer();
 
wplayer.URL = "My MP3 file.mp3";
wplayer.controls.play();

So there you have it; a simple example of how to play an MP3 and WAV file using C#. I hope you find it useful. If you have any questions feel free to ask.