Unity3D: Changing game speed and pausing

This article was originally posted on 4th August 2013 at Programmer’s Ranch using Unity3D 4.2.0f4. This updated version of the article uses Unity3D 5.3.4f1, and the source code is available at the Gigi Labs BitBucket repository. Syntax highlighting and a new screenshot have been added, and the text is slightly modified.

In this article, we’ll learn about controlling time in Unity3D. This allows us to easily pause the game, slow it down, or speed it up.

Create a new project and add a sphere to your scene via GameObject menu -> 3D Object -> Sphere. Next, create a new C# script by right clicking in the Project panel, and selecting Create -> C# Script. Name it Ball, and drag it onto your Sphere in the Hierarchy panel. Double-click the script to open it in Visual Studio.

We’re going to make a very basic bouncing ball just to be able to see the effects of our change in speed. Start off with the following code for the Ball script:

public class Ball : MonoBehaviour
{
    private Vector3 velocity;

    // Use this for initialization
    void Start()
    {
        this.velocity = new Vector3(1.0f, 1.0f, 0.0f);
    }

    // Update is called once per frame
    void Update()
    {
        this.transform.position += this.velocity * Time.deltaTime;

        if (this.transform.position.x > 5.0f)
            velocity.x = -velocity.x;
        else if (this.transform.position.x < -5.0f)
            velocity.x = -velocity.x;
        else if (this.transform.position.y > 6.0f)
            velocity.y = -velocity.y;
        else if (this.transform.position.y < -5.0f)
            velocity.y = -velocity.y;
    }
}

This will make the ball bounce when it reaches the sides of the screen. This may vary depending on your monitor so use whichever values work best.

unity3d-speed-ball

Games look interactive because they generate a certain number of images (frames) per second, usually something between 30 and 60. Time.deltaTime is the time between one frame and the next; multiplying this by the velocity makes the ball move pretty uniformly.

Another important property of the Time class is Time.timeScale. This is a measure of how quickly scripts and animations run, and is set to 1.0f by default. We can change this to make the game run at different speeds. To try it out, add the following code to the Ball script’s Update() method:

        if (Input.GetKeyDown(KeyCode.P))
            Time.timeScale = 0.0f;
        else if (Input.GetKeyDown(KeyCode.N))
            Time.timeScale = 1.0f;
        else if (Input.GetKeyDown(KeyCode.F))
            Time.timeScale = 2.0f;
        else if (Input.GetKeyDown(KeyCode.S))
            Time.timeScale = 0.5f;

What we’re doing here is:

  • If the player presses ‘P’ (pause), we set the time scale to zero, effectively stopping any movement in the game.
  • If the player presses ‘N’ (normal speed), we set the time scale to the default of 1.0f.
  • If the player presses ‘F’ (fast), we set the time scale to double the normal speed.
  • If the player presses ‘S’ (slow), we set the time scale to half the normal speed.

This simple property allows you to not only pause the game, but also to play the game at different speeds. Several games including Starcraft and Warcraft 2 have settings that allow you to tweak the game speed in order to make it more challenging or less frenetic.

starcraft-speed-settings

This article showed how a single line of code in Unity3D is enough to change the speed of a game or pause it. Although this was a very easy tutorial, I hope you will also find it very useful in any games you make!

Monitoring the Size of a Folder

In this article, we’ll develop a simple application that can check the total size taken by a folder (including the files directly inside it, and those in its subfolders), and monitor it periodically to send alerts if it exceeds a certain threshold. This can be useful, for example, to ensure that automatic backups aren’t taking too much space on disk. The source code is available at the Gigi Labs BitBucket repository.

The techniques we’ll use for this are nothing new. We’ll use recursive directory traversal to calculate the total size of the folder, and we’ll use a timer to check this periodically. To send alerts, we’d typically use SmtpClient to send email, but since you’d need an actual SMTP server to test this, we’ll just write something to the console instead.

We’ll start off by calculating the total size of a folder:

        static void Main(string[] args)
        {
            string directoryPath = ConfigurationManager.AppSettings["DirectoryPath"];

            var dir = new DirectoryInfo(directoryPath);
            var size = CalculateDirectorySize(dir);
            Console.WriteLine(size);

            Console.ReadKey(true);
        }

We’re reading the path to the directory to monitor from an application setting (remember to add a reference to System.Configuration). Then we pass the resulting DirectoryInfo object to a recursive CalculateDirectorySize() method, which we’ll define next:

        static long CalculateDirectorySize(DirectoryInfo dir)
        {
            long totalSize = 0L;

            foreach (var file in dir.EnumerateFiles())
                totalSize += file.Length;

            foreach (var subdir in dir.EnumerateDirectories())
                totalSize += CalculateDirectorySize(subdir);

            return totalSize;
        }

This recursive method simply adds up the sizes of the files it contains directly, then adds the total size after recursing into its subdirectories. We’re using the long data type because int will overflow if the folder contains several gigabytes of data.

Note: you might get an UnauthorizedAccessException if you run this in something like C:. It’s easiest to just run it on a folder within your user folder.

This is the result of running the above code against my desktop (which I seem to need to clean up):

dirsize-desktop

We can now refactor our Main() method to run a timer and periodically check the size of the folder:

        private static string directoryPath;

        static void Main(string[] args)
        {
            directoryPath = ConfigurationManager.AppSettings["DirectoryPath"];

            var timer = new Timer();
            timer.Interval = 5000;
            timer.Elapsed += Timer_Elapsed;
            timer.Enabled = true;
            timer.Start();

            Console.ReadKey(true);
        }

Every 5 seconds, the timer will run the following event handler:

        private static void Timer_Elapsed(object sender, ElapsedEventArgs e)
        {
            var dir = new DirectoryInfo(directoryPath);
            var size = CalculateDirectorySize(dir);
            Console.WriteLine(size);
        }

It is now very easy to extend this with a warning mechanism:

        private static string directoryPath;
        private static long threshold;

        static void Main(string[] args)
        {
            directoryPath = ConfigurationManager.AppSettings["DirectoryPath"];
            threshold = Convert.ToInt64(ConfigurationManager.AppSettings["Threshold"]);

            var timer = new Timer();
            timer.Interval = 5000;
            timer.Elapsed += Timer_Elapsed;
            timer.Enabled = true;
            timer.Start();

            Console.ReadKey(true);
        }

        private static void Timer_Elapsed(object sender, ElapsedEventArgs e)
        {
            var dir = new DirectoryInfo(directoryPath);
            var size = CalculateDirectorySize(dir);
            string warning = size > threshold ? " WARNING - THRESHOLD EXCEEDED" : null;
            Console.WriteLine("{0}{1}", size, warning);
        }

Here’s an example run of this application:

dirsize-warnings

Add to that some exception handling and console title code, and you get the source code available in the Gigi Labs BitBucket repository.

Understanding Recursion with Directory Traversal

This article was originally posted as “C#: Understanding Recursion with Directory Traversal” at Programmer’s Ranch on 27th September 2013. It has undergone minor modifications.

In this article, we’re going to talk about recursion. This technique is often considered an alternative to iteration (i.e. loops), and is useful for a wide variety of situations ranging from computing factorials to clearing empty areas in Minesweeper:

csrecursion-minesweeper

Since factorials are boring, and Minesweeper is a bit complex for this easy tutorial, we’re going to look at the filesystem in order to learn about recursion. For example, take a look at the folder for the solution I just created in SharpDevelop:

csrecursion-cmd-files-folders

See, the filesystem is actually a tree data structure. Each folder can contain other files and folders, which can in turn contain other files and folders, and so on. It isn’t easy to work with things like trees using loops, but with recursion it just comes natural. Let’s see how.

After creating a new console application, add the following at the top, which we need to interact with the filesystem:

using System.IO;

The first thing we want to do is get the current directory where the executable will be running. We do this by using Directory.GetCurrentDirectory(). Let’s try that out:

string currentDir = Directory.GetCurrentDirectory();
Console.WriteLine(currentDir);
Console.ReadKey(true);

…and here’s what we get:

csrecursion-current-dir

Now, we want to navigate up to the first CsRecursion folder, which is the solution folder. From there we’ll be able to list the contents of all the subfolder. To do this, we create an instance of DirectoryInfo:

var dir = new DirectoryInfo(currentDir);

This allows us to get to the parent folder:

dir = dir.Parent.Parent.Parent;

…and this is what we have so far:

csrecursion-parent

Right, now about listing the folder and subfolder contents. Let’s add a method to do that:

public static void ListContents(DirectoryInfo dir)
{

}

In this method, we first want to list all the files in that folder. We can do this using DirectoryInfo.GetFiles(), or else using the static Directory.GetFiles() method, which is easier and works directly with file paths (strings):

foreach (string file in Directory.GetFiles(dir.FullName))
    Console.WriteLine(file);

Okay, now all we need is to do the same thing for all subfolders. It turns out that our ListContents() method can actually call itself, and pass in each subdirectory as a parameter:

foreach (DirectoryInfo subdir in dir.GetDirectories())
    ListContents(subdir);

When a method calls itself, it’s called recursion. In this case we say we are recursing into subdirectories.

Let’s just change Main() so that it calls our ListContents() method:

        public static void Main(string[] args)
        {
            string currentDir = Directory.GetCurrentDirectory();
            var dir = new DirectoryInfo(currentDir);
            dir = dir.Parent.Parent.Parent;
            ListContents(dir);
           
            Console.ReadKey(true);
        }

…and voilà:

csrecursion-listing

As you can see, there’s a very small amount of code, and recursion is a perfect fit for this kind of thing, because the same method can work on folders at different levels of the filesystem.

There’s an important concept about recursion you need to be aware of, that might not be so evident in this example: the stopping condition. If a method calls itself and has no way to stop calling itself, you get a sort of infinite loop which actually ends in a stack overflow (in short, there’s a limit to the number of times a method can call another method). Therefore, a recursive function always needs a way to stop calling itself.

If you’re doing factorials, recursion stops when n=1. If you’re computing a Fibonacci sequence, n=0 and n=1 are the stopping conditions. In our case, recursion stops when a folder has no further subfolders. In Minesweeper, recursion stops when there are no more adjacent blank squares (you either hit an edge or a number).

Anyhow, as we have seen in this article, recursion is a great technique to use when your data has divergent paths (most notably when dealing with trees).

C# AppSettings: Upgrading Settings between Assembly Versions

This article was originally posted at Programmer’s Ranch on 15th April 2014.

In “C# AppSettings: Saving User Preferences in a WPF Browser application“, we learned how to define and use user settings in a .NET application. In this article we’ll deal with a slight complication when it comes to maintaining settings between different application versions. But first, let’s build a very simple application to get the point across.

After creating a new Console Application in your favourite IDE, go Add -> New Item… and add a Settings file called… well… Settings.settings! In the designer, add a setting called Name which will be a String in User scope:

cs-settingsupgrade-designer

In our Main() method, let us now write some code that does something with this setting.

        public static void Main(string[] args)
        {
            string name = Settings.Default.Name;
           
            if (string.IsNullOrEmpty(name))
            {
                Console.WriteLine("Hello! Who might you be?");
                Console.Write("You say: ");
                name = Console.ReadLine();
                Console.WriteLine("Pleased to meet you, {0}!", name);
               
                Settings.Default.Name = name;
                Settings.Default.Save();
            }
            else
            {
                Console.WriteLine("Hi {0}! Nice to see you again!", name);
            }
           
            Console.ReadKey(true);
        }

We’re not doing anything fancy here. If the Name setting contains something, then we just output a one-liner; otherwise we ask the user for his name and then save it in the Name setting. Here’s what it looks like when you run it for the first time:

cs-settingsupgrade-introductions

And when we run it again:

cs-settingsupgrade-remember

Now you see, these settings are tied to the version of the program. Each project you compile has something called an assembly version. This is an internal version number assigned to each .exe and .dll file. In SharpDevelop, by default this is set to 1.0.*, which generates something like 1.0.5218.35490 (the actual value is different each time you build, because of the ‘*’ bit). You can find the AssemblyVersion within the AssemblyInfo.cs file that is automatically created when you create a new project:

cs-settingsupgrade-assemblyversion

Now, since a different assembly version is generated with each build, you’ll be quick to notice a problem. If you change the code (even just add a space) and build and run again, the setting you had earlier is somehow lost, and you’re back to the name prompt:

cs-settingsupgrade-introduction-again

The problem here is that the settings are tied not only to program and user, but also to the assembly version. Each time the assembly version changes, a new set of settings are created for the application.

We can use a fixed assembly version:

[assembly: AssemblyVersion("1.0.0.0")]

…and now even after changing code, the settings are remembered:

cs-settingsupgrade-remember-again

However, the problem remains. At some point we’ll want to change that assembly version to, say, 1.0.0.1, and we don’t want to lose our settings.

There is actually a solution to this problem, described in this StackOverflow answer. In a nutshell, you need to import the settings from your old application version by upgrading them.

To do this, first add a boolean setting called UpgradeRequired in your settings file, and make sure to set it to True by default:

cs-settingsupgrade-upgraderequired

Before we actually use this, let’s change the assembly version to see that the settings are not loaded:

[assembly: AssemblyVersion("1.0.0.1")]

And sure enough, you are asked for your name once again when running the program:

cs-settingsupgrade-introduction-3

Then, at the beginning of Main(), add the following code to upgrade the existing settings:

            if (Settings.Default.UpgradeRequired)
            {
                Settings.Default.Upgrade();
                Settings.Default.UpgradeRequired = false;
                Settings.Default.Save();
            }

If you now run the application, the old settings are retrieved and saved into the new settings. Note that the UpgradeRequired setting is set to false as part of the upgrade operation, so that it is done only the first time.

cs-settingsupgrade-remember-again

It works pretty nicely.

In this article, we learned about the assembly version, an internal version associated with each .dll and .exe file produced when compiling a .NET project. We also learned about the role it plays in .NET user settings, and how to upgrade them to make them survive changes in the assembly version.

C# AppSettings: Saving User Preferences in a WPF Browser application

This article was originally posted at Programmer’s Ranch on 23rd March 2014.

Hey Ya! 🙂

In yesterday’s article, “C# AppSettings: Launching Programs and Storing AppSettings“, we learned how you can store application settings in an App.config file so that they can be easily changed without having to recompile the program. This is useful for settings that don’t change very often, but is not the best way to store user preferences.

In today’s article, we will see how we can use a .NET Settings file in order to save user preferences. To do this, we will build a simple WPF browser application* and allow the user to save his homepage.

* For those who already know a little bit about WPF, we’re just going to make a simple application that includes a WebBrowser control – not an XBAP.

So, for starters, create a new WPF application using your favourite IDE. Aside from an App.xaml, you should also have a window – this would be Window1.xaml in SharpDevelop, or MainWindow.xaml in Visual Studio.

Change the window’s TitleWidth and Height properties to something decent (e.g. width of 800 and height of 600). Then, replace the default <Grid> in the window’s XAML with the following:

    <DockPanel>
        <DockPanel LastChildFill="True" DockPanel.Dock="Top">
            <Button Name="GoButton" DockPanel.Dock="Right" Margin="5 5 5 5" Click="Button_Click">Go</Button>
            <Button Name="SaveButton" DockPanel.Dock="Right" Margin="5 5 5 5">Save homepage</Button>
            <TextBox Name="Homepage" DockPanel.Dock="Left" Margin="5 5 5 5" />
        </DockPanel>
        <WebBrowser Name="Browser" VerticalAlignment="Stretch" />
    </DockPanel>

This isn’t a WPF tutorial so don’t worry about the above XAML; you’ll see what it does in a second. Find the window’s codebehind file by expanding your Window1.xaml (or MainWindow.xaml) node in Solution Explorer, and open it:

csbrowser-codebehind

In the window class’s constructor, add the following code after InitializeComponent():

            string homePageUrl = "http://en.wikipedia.org/wiki/Main_Page";
            this.Homepage.Text = homePageUrl;
            this.Browser.Navigate(homePageUrl);

You can now run the application to see what it looks like:

csbrowser-browser

That was pretty easy! We set up the browser embedded in our window to load Wikipedia by default, and that’s what it did. Now, let’s get our program to actually do something.

In the XAML for the “Go” button, start typing the word “Click”, then press TAB twice. This should generate the following code in your window’s codebehind file (remember, it’s the .xaml.cs file):

        void GoButton_Click(object sender, System.Windows.RoutedEventArgs e)
        {
            throw new NotImplementedException();
        }

Replace the body of this method with the following:

this.Browser.Navigate(this.Homepage.Text);

We can now type in a URL and press the “Go” button to navigate there:

csbrowser-navigate

Now, let’s work on that “Save homepage” button. First, add a button handler as you did before – by starting to type the word “Click” in the XAML for the “Save homepage” button, pressing TAB, selecting “<new event handler>”, and then pressing TAB again. You should have an empty handler similar to the one you had for the “Go” button earlier:

        void SaveButton_Click(object sender, System.Windows.RoutedEventArgs e)
        {
            throw new NotImplementedException();
        }

Next, right click on your project in Solution Explorer, and select Add -> New Item… and add a new Settings file. If you’re using SharpDevelop, you’ll find this under the Misc category:

csbrowser-addsettingsfile

This file opens up a table where you can add settings as you like. Let’s add one for the homepage:

csbrowser-editsettingsfile

You just need to set the name, data type, and default value of the property. The Scope can be either User or Application. This article at MSDN explains the difference:

Application-scope settings are read only, and can only be changed at design time or by altering the <AssemblyName>.exe.config file in between application sessions. User-scope settings, however, can be written at run time, just as you would change any property value. The new value persists for the duration of the application session. You can persist changes to user settings between application sessions by calling the Settings.Save method. These settings are saved in the User.config file.

In short, Application-scope settings are pretty similar to what we did yesterday in “C# AppSettings: Launching Programs and Storing AppSettings“, while User-scope settings are ideal for saving user preferences – which is what we want to do now.

In your window’s constructor, you can now load the homepage from your settings. You first need to build your project to allow the IDE to do some magic underneath (otherwise you won’t be able to find the property. Then, you can load the homepage setting like this:

            string homePageUrl = Settings1.Default.HomePage;

The good thing about these kinds of settings are that they are strongly-typed. This means that if you’re loading, for example, an integer, you can just assign it directly to an integer variable without further ado. Using regular AppSettings (see “C# AppSettings: Launching Programs and Storing AppSettings“), on the other hand, you first have to read values into strings and then convert them to the appropriate type.

Saving settings is also pretty straightforward. You assign them using the same notation as above, and then Save() them so that the settings can be remembered next time you run the application:

        void SaveButton_Click(object sender, System.Windows.RoutedEventArgs e)
        {
            Settings1.Default.HomePage = this.Homepage.Text;
            Settings1.Default.Save();
           
            MessageBox.Show("Settings have been saved", "Homepage update");
        }

So now, we can run our application, enter a new URL in the homepage, and click the “Save homepage” button:

csbrowser-savesettings

…and the next time we run our application, it loads our new homepage by default:

csbrowser-loadsettings

As you can see, the WPF WebBrowser control is actually some version of Internet Explorer – you can see it compared to a REAL browser in a previous screenshot. Still, Internet Explorer can sometimes be useful. To download another browser, for instance. 😀

Cool. 🙂 In this article, we saw how to use a .NET Settings file to load and save user preferences quickly and easily. We saw this in action by loading and saving the homepage in a simple WPF browser application. Thanks for reading, and see you in time for the next article! 🙂

C# AppSettings: Launching Programs and Storing AppSettings

This article was originally posted at Programmer’s Ranch on 22nd March 2014.

Hi all! 🙂

Today we’re going to write a little program that can start other programs. For example, it might launch MS Word, or your favourite browser. From this we will learn how to actually start other programs using C#, and also how to add settings into an application configuration file so that they can easily be changed.

Start off by creating a new Console Application using your favourite IDE. Throw out any code already in Main(), and add this initial code:

Console.Title = "Launcher";

// TODO code goes here

Console.ReadLine();

Now, to start a program from our code, we need to use the Process class. To be able to use it, we need to add the following to our usings:

using System.Diagnostics;

Starting a program is really easy. All we need to do is replace our “TODO” comment with the following:

string filePath = @"C:\tools\notepad++\notepad++.exe";
Process.Start(filePath);

And sure enough, when we run our program, Notepad++ is opened as well:

csappsettings-notepad++

Let us now take this a step further. We can allow the user to type in the name of an application, and the corresponding application will be launched. We could do this using a switch statement as in “C# Basics: Command Interpreter Using Methods“. Or even better, we can use a Dictionary to store the relationship between application names and their path. First, add the following using at the top if it’s not there already (e.g. if you’re using SharpDevelop):

using System.Collections.Generic;

Next, our Dictionary, using the collection initialiser syntax as in “Morse Code Converter Using Dictionaries“:

            Dictionary<string, string> programs = new Dictionary<string, string>()
            {
                { "notepad++", @"C:\tools\notepad++\notepad++.exe" },
                { "firefox", @"C:\tools\firefox\firefox.exe" }
            };

We can now accept user input and launch the appropriate program. Replace the two lines we wrote earlier (which include the call to Process.Start()) with this:

            Console.Write("Enter program to launch: ");
            string programName = Console.ReadLine();
            if (programs.ContainsKey(programName))
            {
                string path = programs[programName];
                Process.Start(path);
                Console.WriteLine("{0} launched from {1}", programName, path);
            }
            else
                Console.WriteLine("Unknown program");

The user gives us the name of the program he wants to launch. If that name exists in our dictionary, we get the corresponding path, and then launch it as we did before. If we try this now, it works pretty nicely:

csappsettings-firefox

Although this works pretty well, it isn’t very flexible to have the program names hardcoded in your program code. Imagine you give this program to a friend. It wouldn’t be very useful if he could only launch Firefox and Notepad++. What if he wanted to be able to launch SharpDevelop as well? And maybe in future he might want to add VLC as well. It obviously isn’t convenient for you to have to change the code, recompile, and give him an updated program each time.
One option could be to store these program settings in a file and read it, but .NET provides us with a simpler option that exists specifically for this kind of scenario. .NET applications can optionally come with an application configuration file, which is usually called App.config. In fact, if, like me, you’re using SharpDevelop 5 Beta 2, you should have one already (otherwise just add an Application Configuration File to your project):

csappsettings-appconfig

When you build the application, App.config gets renamed to the name of the executable, plus a “.config”, and is stored in the same folder:

csappsettings-appconfig2

In this App.config file, under the <configuration> node, we can add an <appSettings> node and store our settings. The settings have a key, which is a name that identifies them, and a value which is the value of the setting. Ours will be like this:

    <appSettings>
        <add key="notepad++" value="C:\tools\notepad++\notepad++.exe" />
        <add key="firefox" value="C:\tools\firefox\firefox.exe" />
    </appSettings>

With this done, we can now rewrite our program to use these settings. First, we need to add a reference to System.Configuration. To do this, right click on the name of the project in Solution Explorer, and select “Add Reference”:

csappsettings-addreference1

In the “Add Reference” window, locate “System.Configuration” and then click “OK”.

Next, add the following using statement at the top:

using System.Configuration;

We can now use ConfigurationManager to obtain our app settings, like this:

        public static void Main(string[] args)
        {
            Console.Title = "Launcher";
           
            string firefoxPath = ConfigurationManager.AppSettings["firefox"];
            Console.WriteLine(firefoxPath);
           
            Console.ReadLine();
        }

…And here’s what we see when we run this:

csappsettings-read-appsettings

So now, all we need to do is let the user tell us which program he wants to launch, and find it in the AppSettings:

        public static void Main(string[] args)
        {
            Console.Title = "Launcher";
           
            Console.Write("Enter program to launch: ");
            string programName = Console.ReadLine();
           
            string path = ConfigurationManager.AppSettings[programName];
            if (path == null)
                Console.WriteLine("Unknown program.");
            else
            {
                Process.Start(path);
                Console.WriteLine("{0} launched from {1}", programName, path);
            }
           
            Console.ReadLine();
        }

The only thing worth noting here is that if the specified key does not exist in the AppSettings, retrieving that key via ConfigurationManager.AppSettings[] returns null, allowing us to take appropriate action in that case.

So now, when you give this program to a friend, he can just add the following line in the CsAppSettings.exe.config file that conveniently comes with the program:

        <add key="fiddler" value="C:\tools\fiddler2\Fiddler.exe" />

…and without further ado, he can now launch Fiddler as well:

csappsettings-fiddler

Wonderful! 🙂

In this article, we learned how to start another program from our code, and we also learned how to work with application settings in an application configuration file.

Storing your application settings in an App.config file is convenient because they can be tweaked as needed, without having to recompile your program. These kinds of settings are best suited for settings that don’t change frequently, so you just set them when you need them, and forget about them. In the next article, we’ll learn about another kind of settings that are great for storing stuff like user preferences which can potentially change a lot.

Computing File Hashes in C#

This article was originally posted at Programmer’s Ranch as “C# Security: Computing File Hashes” on 2nd May 2014, which was the blog’s first anniversary. In this version of the article, I’ve removed anniversary references and made other slight edits where they were needed.

In this article, we’re going to learn a little about hashing: what it does, and how to use it to verify the integrity of a downloaded file (which is just one application where it is useful).

We’ve already seen seen in “C# Security: Securing Passwords by Salting and Hashing” that a hash function transforms an input string into a totally different piece of data (a hash):

cspwsec-hashfunc-1

If you make even a slight change to the input, such as changing the first character from uppercase to lowercase, you get a totally different output:

cspwsec-hashfunc-2

Also, if you use a decent hash function (i.e. not MD5), it is normally not possible to get the input string from the hash.

In today’s article, we’re going to use hashes for something much simpler than securing passwords. We’re going to hash the content of files, and then use that hash to check whether the file changed. Since I haven’t been very impressed with SharpDevelop 5 Beta, I’m going to ditch it and use Visual Studio 2013 instead. You can use whatever you like – SharpDevelop, Visual Studio Express for Desktop, or maybe even MonoDevelop.

Create a new Console Application, and add the following at the top:

using System.Security.Cryptography;

This will allow you to use a variety of hash functions, which all derive from the HashAlgorithm class.

We’ll also need a little helper function to convert our hashes from a byte array to a string, so that they may be displayed in hex in the command line. We’ll use the following, which is a modified version of the Hash() method from “C# Security: Securing Passwords by Salting and Hashing“:

        public static string ToHexString(byte[] bytes)
        {
            StringBuilder sb = new StringBuilder();
            foreach (byte b in bytes)
            sb.Append(b.ToString("x2").ToLower());

            return sb.ToString();
        }

Now, let’s create a text file in the same folder as our .sln file and name it “test.txt”, and put the following lyrics from the Eagles’ “Hotel California” in it:

So I called up the Captain,
"Please bring me my wine"
He said, "We haven't had that spirit here since nineteen sixty nine"
And still those voices are calling from far away,
Wake you up in the middle of the night
Just to hear them say...

Let’s read that file into memory. First, we need to add the following

using System.IO;

We can now read the contents of the file into a string:

string fileContents = File.ReadAllText(@"../../../test.txt");

…and quite easily compute the hash of those contents:

            using (HashAlgorithm hashAlgorithm = SHA256.Create())
            {
                byte[] plainText = Encoding.UTF8.GetBytes(fileContents);
                byte[] hash = hashAlgorithm.ComputeHash(plainText);
                Console.WriteLine(ToHexString(hash));
            }

            Console.ReadLine();

Note that I’m using SHA256 as the hash function this time – it’s a lot more robust than MD5. If you check the documentation for the HashAlgorithm class, you can find a bunch of different hash algorithms you can use. As it is, we get the following output:

cshashfile-output-1

Now, let’s see what happens if your little toddler manages to climb onto your keyboard and modify the file. Let’s remove the first character in the file (the initial “S”) – that might be within a toddler’s ability – and save the file. When we rerun the program, the output is quite different:

cshashfile-output-2

And here we have already seen how hashing gives us the means to verify a file’s integrity, or in other words, check whether it has been tampered with. In fact, popular Linux distributions such as Ubuntu distribute MD5 hashes for the files they release, so that the people who can download them can check that they are really downloading the file they wanted, and not some weird video of goats yelling like humans:

cshashfile-ubuntu-hashes

So let’s actually see this in action. After downloading an Ubuntu distribution, let’s change the filename to that of the Ubuntu file we downloaded, and the hash algorithm to MD5:

            string fileContents = File.ReadAllText(@"../../../../ubuntu-14.04-desktop-amd64.iso");

            using (HashAlgorithm hashAlgorithm = MD5.Create())

Now, let’s try to compute a hash of the Ubuntu file:

cshashfile-out-of-memory

Oops! We tried to read a ~1GB file into memory, and that’s a pretty stupid thing to do. Unless you’ve got a pretty awesome computer, you’ll see the memory usage spike until you get an OutOfMemoryException, as above. And even if you do have a pretty awesome computer, you shouldn’t load an entire massive file just to perform an operation on its contents.

In one of my first articles at Programmer’s Ranch, “C#: Working with Streams“, I explained how you could read a file bit by bit (e.g. line by line) and work on those parts without having to have the entire file in memory at any one time. And quite conveniently, the hash algorithms have a variant of the ComputeHash() method that takes a stream as a parameter.

So let’s change our code as follows:

        static void Main(string[] args)
        {
            using (FileStream fs = File.OpenRead(@"../../../../ubuntu-14.04-desktop-amd64.iso"))
            using (HashAlgorithm hashAlgorithm = MD5.Create())
            {
                byte[] hash = hashAlgorithm.ComputeHash(fs);
                Console.WriteLine(ToHexString(hash));
            }

            Console.ReadLine();
        }

And let’s run it:

cshashfile-streamed-hash

There are a few things to note from the output:

  • It computes pretty quickly, despite the fact that it’s going through a ~1GB file.
  • Memory levels remain at a pretty decent level (in fact the memory used by the program is negligible).
  • The output matches the first hash in the list of hashes on the Ubuntu webpage (in the background of the above screenshot).

In this article, we revisited the concept of hashing, and learned the following:

  • There are several different hash algorithms provided by .NET that you can use, including MD5, SHA256, and others.
  • A hash gives you a way to verify whether a file has been tampered with.
  • Streaming provides the ability to process large files quickly and with very little memory overhead.