From zero to hero in JSON with C#

Introduction and Background

I have been reading many posts and articles about JSON and C# where every article tries to clarify the purpose of either one thing, or the other thing: JSON or C# libraries. I want to cover both of these technologies in one post so that if you have no idea of JavaScript Object Notation (JSON), and the C# libraries available for processing and parsing the JSON files you can understand these two concepts fully. I will try my best to explain each and every concept in these two frameworks and I will also try to publish the article on C# Corner and to share an offline copy of this post as an eBook, so excuse me if you find me sliding through different writing formats because I have to stick to both writing styles in order to qualify this post as an article and as a miniature guide.

When I started to do a bit of programming, I knew there were many data-interchange formats, serialization and deserialization techniques and how objects can be stored including their states in the disk to fetch the same data back for further processing and further working on the same objects that you just left while you were going outside. Some of these techniques are tough to be handled and understood while others are pretty much framework-oriented. Then comes JSON into the image, JSON provides you with a very familiar and simple interface for programming the serialization and deserialization of the objects on runtime so that their states can be stored for later use. And we are going to study JSON notation of data-interchange and how we can use this format in C# projects for our applications.

What is JSON?

I remember when I was starting to learn programming there was this something called, Extensible markup language, or as some of us know it as, XML. XML was used to convert the runtime data of the objects or the program states or the configuration settings into a storable string notation. These strings were human-readable. Programmers could even modify these values when they needed to, added more values or removed the values they didn’t want to see in the data.

Introduction of XML

For a really long time and even today, XML is being used as the format for data-interchange. Many protocols for communication are built on the top of XML, most notably SOAP protocol. XML didn’t even power a few of the protocols, it even kick-started many of the most widely known and used markup languages, of which HTML and XAML are the ones that most of you are already familiar with.

Figure 1: XML file icon.

History has it, XML has been of a great use to many programmers for building applications that share the data across multiple machines. The world wide web started with the pages written in a much XML-oriented way, markup language called, HTML.

The purpose of XML entirely was to design the documents in plain-text that can be human-readable and can be used by the machines to define the state of applications, program or interfaces.

1. State of applications: You can store the object states, which can be loaded later for further processing of the data. This would allow you to maintain the states of the applications too.
2. Program: XML can be used to define the configuration of the programs when they start up. Microsoft has been using web.config and machine.config files to define how a program would start. Programmers and developers can easily modify the files as they needed them to. This would alter the design of the way program starts.
3. Interfaces: HTML is being used to define how the user-interface would look like. Windows Presentation Foundation uses XAML as the major language for designing the interfaces. Android supports XML-based markup language for defining the UI controls.

<?xml version="1.0" encoding="UTF-8"?>

Empty XML documents are not meant to contain any blank object or document tree. They can be omitted.

This is not it. XML is much more than this, WCF, for example supports SOAP communication. Which means that you can download and upload the data in XML format. ASP.NET Web API supports data transfer in the form of XML documents.

Usage of XML

I want to show you how XML is used, then why shouldn’t I used something that comes from a real-world example. RSS for example, uses XML-based documents for delivery of feeds to the clients. I am using the same technology feature on my blog to deliver the blog posts to readers and other communities. The basic XML document for a single post would look like this,

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"
    xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:media="http://search.yahoo.com/mrss/">

<channel>
    <title>Learn the basics of the Web and App Development</title>
    <atom:link href="https://basicsofwebdevelopment.wordpress.com/feed/" rel="self" type="application/rss+xml" /> 
    <link>https://basicsofwebdevelopment.wordpress.com</link>
    <description>The basics about the Web Standards will be posted on my blog. Love it? Share it! Found an error, ask me to edit the post! :)</description>
    <lastBuildDate>Fri, 03 Jun 2016 09:48:29 +0000</lastBuildDate>
    <language>en</language>
    <generator>http://wordpress.com/</generator>
    <cloud domain='basicsofwebdevelopment.wordpress.com' port='80' path='/?rsscloud=notify' registerProcedure='' protocol='http-post' />
    <image>
         <url>https://s2.wp.com/i/buttonw-com.png</url>
         <title>Learn the basics of the Web and App Development</title>
         <link>https://basicsofwebdevelopment.wordpress.com</link>
    </image>
    <atom:link rel="search" type="application/opensearchdescription+xml" href="https://basicsofwebdevelopment.wordpress.com/osd.xml" title="Learn the basics of the Web and App Development" />
    <atom:link rel='hub' href='https://basicsofwebdevelopment.wordpress.com/?pushpress=hub'/>
    <item>
        <title>Hashing passwords in .NET Core with tips</title>
        <link>https://basicsofwebdevelopment.wordpress.com/2016/06/03/hashing-passwords-in-net-core-with-tips/</link>
        <comments>https://basicsofwebdevelopment.wordpress.com/2016/06/03/hashing-passwords-in-net-core-with-tips/#respond</comments>
        <pubDate>Fri, 03 Jun 2016 08:42:49 +0000</pubDate>
        <dc:creator><![CDATA[Afzaal Ahmad Zeeshan]]></dc:creator>
        <category><![CDATA[Beginners]]></category>
        <category><![CDATA[C# (C-Sharp)]]></category>
        <guid isPermaLink="false">https://basicsofwebdevelopment.wordpress.com/?p=1313</guid>
        <description>
            <![CDATA[Previously I had written a few stuff for .NET framework and how to implement basic security concepts on your applications that are working in .NET environment. In this post I want to walk you to implement the same security concepts in your applications that are based on the .NET Core framework. As always there will be […]<img alt="" border="0" src="https://pixel.wp.com/b.gif?host=basicsofwebdevelopment.wordpress.com&blog=59372306&post=1313&subd=basicsofwebdevelopment&ref=&feed=1" width="1" height="1" />]]>
        </description>
    </item>
</channel>
</rss>

Of course I snipped out most of the part, but you get the point of XML here. This data can be read by humans themselves, and if the machine is set to parse this data it can provide us with runtime association of data with the objects. In a much similar manner, we can share the data from one machine to another by serializing and deserializing the objects.

What is the need of JSON, then?

JSON comes into the frame back in 1996 or around that time. The purpose of XML and JSON is similar: Data-interchange among multiple devices, networks and applications. However, the language syntax is very much similar to what C, C++, Java and C# programmers have been using for their regular day “object-oriented programming“; pardon me C programmers. The language syntax is very similar to what JavaScript uses for the notation of objects. JSON provides a much compact format for the documents for storing the data. JSON data, as we will see in this guide, is much shorter as compared to XML and in many ways can be (and should be…) used on the network-based applications where each byte can be a bottleneck to your application’s performance and efficiency. I wanted to take this time to disgust XML, but I think your mind will consider my words as personal and bias views. So, first I will talk about JSON itself how it is structured and then I will talk about using the time to show the difference between JSON and XML and which one to prefer.

JSON format and specifications were shared publicly as per ECMA-404. The document guides the developers to find their APIs in such a way that they work as per the teachings of the standard. API developers, programmers, serialization/deserialization software developers can get much help from the documentation in understanding how to define their programs to parse and stringify the JSON content.

Structure of JSON

JSON is an open-standards document format for human-readable and machine-understandable serialization and deserialization of data. Simply, it is used for data-interchange. The benefit of JSON is that it has a very compact size as compared to XML documents of the same purpose and data. JSON stores the data in the form of key/value pairs. Another benefit of JSON is (just like XML) it is language-independent. You can work with JSON data in almost any programming language that can handle string objects. Almost every programming framework that I can think of most of the programming frameworks support JSON-based data-interchange. For example, ASP.NET Web API supports JSON format data transfer to-and-from the server.

The basic structure of JSON document is very much simple. Every document in JSON must have either an object at its root, or an array. Object and array can be empty there is no need for it to contain anything in it, but there must be an object or an array.

A sample, and simple JSON document can be the following one:

{ }

What that means, is something that I am going to get into a bit later. At the moment just understand that this is a blank JSON document about any object in the application. A JSON document can contain other data in the form of key/value pairs, that are of the following types:

1. Object
2. Array
3. String; name or character.
4. Integer; numeric
5. Boolean; true or false
6. Null.

Note that JSON doesn’t support all of the JavaScript keywords, such as you cannot use “undefined” in a valid JSON schema. Nothing is going to stop you from using it in your files, but remember that valid JSON schema should not include such values. One more thing to consider is that JSON is not executable file, although it shares the same object notation but it doesn’t allow you to create variables. If you try to add a few variables to it, it would generate errors. Now I would like to share a few concepts for the valid data types in JSON and what they are and how you should use them in your own JSON data files.

JSON data types

JSON data types are the valid values that can be used in JSON files. In this section I want to clarify the values that they can hold, how you can use them in your own project data-interchange formats.

JSON Object

At the root of the JSON document, there needs to be either a JSON object or a JSON array. In JavaScript and in many other programming languages an object is denoted by curly braces; “{ }”. JSON uses the same notation for denoting the objects in the JSON file. In JSON files, objects only contain the properties that they have. JSON can use other properties, other data types (including objects) as the value for their properties. How that works, I will explain that later in this course guide, but for now just consider that each of the runtime object is mapped to one JSON object in the data file.

In the case of an object, there are properties and their values that are enclosed inside the opening and closing curly braces. These are in the form of a key/value pair. These key value sets are separated using a colon, “:” and multiple sets are separated using a comma, “,”. An example of the JSON object is as follows:

{
  "name": "Afzaal Ahmad Zeeshan",
  "age": 20
}

Even the simplest of the C#, Java or C++ programmers would understand what type these properties are going to hold. It is clear that the “name” property is of “string” type and the “age” property is of integer type.

There are however a few things that you may need to consider at the moment:

1. An object can contain any number of properties in it.
2. An object can omit the properties; being an empty object.
3. All the property names (keys) are string values. You cannot omit the quotation around the key name. It is required, otherwise JSON would claim that it was expecting a string but found undefined.
4. Key/value sets are separated by a colon character, whereas multiple sets are separated using a comma. You cannot add trailing commas in the JSON format, some of the APIs may through error. For example, JSON.parse(‘[5, ]’); would return an error.

I will demonstrate the errors in a later section because at the moment I want to show you and teach you the basics of JSON. But, I will show you how these things work.

By now the type of the JSON object is clear to you. One thing to keep in mind is that JSON object is not only meant to be used as the root of the JSON document. It is also used as a value for the properties of the object, which allows the JSON document to contain the entire data in the form of relationship with objects; only difference being that the objects are anonymous.

JSON Arrays

Like JavaScript, JSON also supports storing the objects in a sequence, series or list; what-ever you would like to put it as. Arrays are not complex structures in JSON document. They are:

1. Simple.
2. Start with a square bracket, and end on the same.
3. Can contain values in a sequence.
4. Each value is separated by a comma (not a colon).
5. Value can be of any type.

A sample JSON array would look something like this,

[ "Value 1", "Value 2" ]

You can store any type of value in the array, unlike other programming language such as C# or C++. The type of the values is not mandatory to be similar. That is something that pure C# or C++ programmers cannot fathom in the first look. But, guys, this is JavaScript. I used JSONLint service to verify this, later I will show you how it works in JavaScript.

Figure 2: JSONLint being used for verification of JSON validity.

In JavaScript, the type doesn’t need to be matched of the arrays. So, for example you can do the following thing and get away with it without anything complaining about type of the objects.

var arr = [ "Hello", 55, {} ];

So, JSON being a JavaScript-derived document format, follows the same convention. JSON leaves the idea of type casting to the programmer, because this is performed only in the context of strongly typed programming languages such as C++, C# etc. JavaScript, being weakly typed doesn’t care about the stuff at all. So, it can take any type in an array as long as it doesn’t violate other rules.

Upcoming data types are similar to what other programming languages have, such as strings, integers and boolean values. So, I will try to not-explain them as much as I have had explained these two.

JSON Strings

String typed values are the values which contain the character-type values. In many programming environments, strings are called, arrays of characters. In JavaScript, you can use either single quotes or double quotes to wrap the string values. But, in JSON specification you should always consider using double quotation. Using single quotation may work and should work in JavaScript environment but in the cases when you have to share the data over the network to a type-safe programming environment such as where C++ or C# may be used as the programming language. Then your single quotes may cause a runtime error when their parsers would try to read a string starting as a character.

In JSON, strings are similar and you have been watching strings in the previous code samples. A few common examples of string values in JSON are as following:

// Normal string
"Afzaal Ahmad Zeeshan"

// Same as above, but do not use in JSON
'Afzaal Ahmad Zeeshan'

// Escaping characters, outputs: "\"
"\"\\\"" 

// Unicode characters
"\u0123"

In the above example, you see that we can use many characters in our data. We can:

1. Build normal strings such as C# or C++ strings.
   • JSON standard forbids you from using the single quotation because you may be sending the data over to other platforms.
2. Escaping the characters is required in strings. Otherwise, the string would result in undefined behavior. You can use the similar string escaping provided in other languages such as:
   • \”
   • \\
   • \/
   • \b
   • \f
   • \n
   • \r
   • \t
   • \u-4-hex-numbers
3. Unicode characters (as specified in the last element of above list) are also supported in JSON, you can specify the Unicode character code here.

One thing to consider is that your objects’ attributes (properties) are also keyed using a string value.

{
    "key": 1234
}

The value of a property can be anything, but the key must always be a string. The strings in JSON, JavaScript, C++, C# and Java are all alike and have the same value for each of the sentence. Unicode characters are supported and need not to be escaped. For original JSON website, I got this image,

Figure 3: JSON string structure.

Thus, the strings are similar in JSON and other frameworks (or languages).

JSON Integers

Just like strings, integers are also the literal values in the JSON document that are of numeric type. They are not wrapped in quotations, if they are then they are not numeric types, instead they are of string type.

A few examples of integer values are:

// Simple one
1234

// Fractional
12.34

// Exponential
12e34

You can combine fractional and exponential too. You can also append the sign of the number (negative – or positive +) with the number itself. In JSON these types can also be used as the values. If you take a look at the example above in a few sections above, you can see that I had used the age as an integer value for my property. A few things that you should consider while working with JSON data is:

1. In exponential form, “e” and “E” are similar.
2. It must never end with “e”.
3. Number cannot be a NaN.
4. Number encoding and variable size should be considered. JavaScript and other language may differ in encoding the variable size for the numberics and may cause an overflow.

JSON Boolean

Boolean values indicate the results of a conditional operation on an expression. Such as, “let him in, if he is adult”. JSON supports storing values in their literal boolean notation. They are similar to what other programming languages have in common. They must also not be wrapped in quotation as they are literals. If a boolean value is wrapped in quotation then it is not a boolean value but instead it is a string value.

// Represents a true result
true

// Represents a false result
false

These must be written as they are because JavaScript is case-sensitive and so is JSON. You can use these values to denote the cases where other types cannot make much sense compared to what this can make, sense. For example, you can specify the gender of the object.

{
    "name": "Afzaal Ahmad Zeeshan",
    "age": 20, 
    "gender": true
}

I didn’t use “male”, instead I used “true”. On the other side I can then translate this condition to another type such as,

if(obj.gender) {
    // Male
} else {
    // Female
}

This way, other than strings and numeric values we can store boolean values. These would help us structure the document in a much simpler, cleaner and programmer-readable format.

JSON null

C based programmers understand what a null is. I have been programming in programming languages such as, C, C++, C#, Java, JavaScript and I have used this keywords where the objects do not exist. There are other programming languages such as Haskell, where this doesn’t make much sense. But, since we are just talking about JavaScript and languages like it, we know what null is. Null just represents when an object doesn’t exist in the memory. In JavaScript, this means the “intentional absence” of the object. So in JavaScript environment a null object does exist but has no value. In other languages it is the other way around; it doesn’t even exist.

It just has a single notation,

null

It is a keyword and must be typed as it is. Otherwise, JavaScript-like error would pop up, “undefined“. This can help you in sending the data which doesn’t exist currently. For example, in C# we can use this to pass the values from database who are nullable. There are nullable types in C#, which we can map to this one.  For example, the following JSON document would be mapped to the following C# object:

{
    "name": "Afzaal Ahmad Zeeshan",
    "age": null
}

C# object structure (class)

class Person {
    public string Name { get; set; }
    public int? Age { get; set; }      // Nullable integer.
}

And in the database if the field is set to be nullable, we can set it to that database record. This way, JSON can be used to notably denote the runtime objects in a plain-string-text format for data-interchange.

Examples of use

I don’t want to stretch this one any longer. JSON has been widely accepted by many companies even Microsoft. Microsoft was using the web.config file in XML format for configuration purposes of the application. However, since a while they have upgraded their systems to parse and use the settings provided in a much JSON way. JSON is very simpler and easier to handle.

Microsoft started to use JSON format to handle the settings for their Visual Studio Code product. JSON allows extension of the settings, which helps users to add their own modifications and settings to the product.

I have been publishing many articles about JSON data sources and I think, if I started to use JSON then it was a sign of success of JSON over XML. 🙂

1. Creating a “customizable” personal blog using ASP.NET
2. Understanding ASP.NET MVC using real world example, for beginners and intermediate

There are many other uses of JSON and my personal recommendation is with JSON if you can use JSON over XML. However, if you are interested in XML or are supposed to use XML such as when using SOAP protocol. Otherwise, consider using JSON.

Errors in JSON

No, these are not errors in the JSON itself, but a few errors that you may make while writing the JSON documents yourself. This is why, always consider using a library.

Trailing commas

As already mentioned above, the trailing commas in the JSON objects or arrays cause a problem. The parser may think that there is another property to come but unexpectedly hits a terminating square or curly bracket. For example the following are invalid JSON documents:

{ "k": "v",  }    // Ending at a comma

[ 123, "", ]      // Ending at a comma

These can be overcame if you:

1. First of all, write your own parsers.
2. Make them intelligent enough to know that if there is no property, they can ignore adding a property, simply.
3. If there is no more value in the array after the comma, it means the array ended at the previous token.

However, present parsers are not guaranteed to be intelligent enough so my recommendation is to ignore this.

Ending with an “e” or “E”

If you end your numbers in exponential form with a e, you are likely to get an error of undefined. You know what that means, don’t you? It is always better to end it is a proper format following the specification.

Undefined

Each property name must be a string token. In JavaScript you can do the both of the following:

var obj = { "name": "Afzaal Ahmad Zeeshan" };

// OR
var obj = { name: "Afzaal Ahmad Zeeshan" };

But in JSON you are required to follow the string-based-key-names method of creating and defining the object properties. In JSON, if you do the following you will get error,

{ 
   name: "Afzaal Ahmad Zeeshan"
}

Because, name is undefined. Parser may consider it to be a variable somewhere but JSON documents cannot be executed so there is no purpose of JavaScript variables to be there. Some libraries may render the results for your documents even if you leave your property names un-stringed. But, don’t consider everything to be server always follow the specifications.

C# side of article

To this point I hope that JSON is as simple as 1… 2… 3. for you! If not, please let me know so that I can make it even more clear. But, in this section I want to talk about using JSON in your C# projects. In this section I am going to talk about the libraries that are available in C#, or more specifically I am going to talk about JSON.NET library. I will use this library to explain how JSON can be used to save the state of the objects. How you can create a JSON file, how you can parse it to create objects on runtime and how serialization and deserialization works.

This section will be a real world section covering the methods and practices that you can use to use JSON in your own applications. I will cover most of the C# programming part in this section so that you can understand and learn how to program JSON in your .NET environment.

JSON.NET library

I am specifically just going to walk you through JSON.NET library. JSON.NET is a widely used JSON parser for .NET framework. I have been using this library for a very long time and I personally this is one of the best APIs out there for JSON parsing.

Figure 4: Json.NET comparison with other popular JSON serializers.

I will use the objects provided in this library just to demonstrate how you can parse JSON files to runtime objects, and how you can create JSON strings (serialize the objects) using the objects provided to the serializer. By the end of this post you will be able to create your own JSON-oriented-and-backed applications in .NET framework (or any framework that supports C# programming).

Creating the object for this guide

In C#, we create classes to work around with real-world objects. We can then use this library to convert the runtime structure of that object to a storable JSON document that can be used to:

1. Send over the network.
2. Save on the disk.
3. Save for loading the object in that state later.

Many other uses. The counterpart of this process is the deserialization of the objects in runtime structures from their JSON notation. First of all, I will create a sample class that we are going to use to convert to JSON format and from the JSON format.

class Person
{
    public int ID { get; set; }
    public string Name { get; set; }
    public bool Gender { get; set; }
    public DateTime DateOfBirth { get; set; }
}

This object has the following diagram.

Figure 5: Person class diagram.

Frankly speaking, this object can be created in C++, it can be created in Java and it can be created in JavaScript too. If we use JSON for serializing this object, or the number of objects that can be transmitted over the network to the peers on the networks. Since we have stringified the data in JSON notation, we now can parse the string data in other languages too. Every other programming language has a JSON parser library.

We can redefine the structures in other programming languages and then use a JSON parser library to convert this string over the network in those machines too. I am going to cover C# part of programming only.

A few things that you might want to know here before we move forward. I have used the datatype of “DateTime” because I wanted to show how derived types are converted to when they are being serialized to JSON notation. So, let’s begin the C# programming to understand the relative stuff in their C# counterparts.

Serializing the objects

In programming, serialization is the process of converting the runtime objects to a plain-text string format. In other words, it converts the object structure from memory to a format that can be stored on the disk. Serialization just translates the state of the objects, which is that it just translates the properties of the object to the format that can be used to store them for later use. You can think of it as synchronization process, where you store the current state of the objects on the disk so that you can load the data later and start your work from the state where you left it instead of starting from scratch again.

Since we are talking about JSON here, we are interested in the conversion of objects in their JSON notation for storage (serialization) and then in the upcoming section to convert the JSON document into runtime objects and data structures (deserialization). Simply, we are going to see how to convert the JSON into objects and vice versa.

To serialize the object, you need an object that holds the data in itself. The object would have a state in the application. We then call the library functions to serialize the objects in their JSON notation. Like this,

// Create the person
Person myself = new Person { 
                    ID = 123, 
                    Name = "Afzaal Ahmad Zeeshan", 
                    Gender = true, 
                    DateOfBirth = new DateTime(1995, 08, 29) 
                };

// Serialize it.
 string serializedJson = JsonConvert.SerializeObject(myself);

// Print on the screen.
 Console.WriteLine(serializedJson);

The function is called to serialize the object which (as clearly seen) return a string object. This object holds the JSON notation for the object. The output returned was like this, (yes, I formatted the JSON document for readability)

{
    "ID": 123,
    "Name": "Afzaal Ahmad Zeeshan",
    "Gender": true,
    "DateOfBirth": "1995-08-29T00:00:00"
}

We create store the data in a file, send it on the network or do what we have to. I am not going to cover that part because I think (and believe) that this is totally relative to your application design and how it is expected to work. Now, we need to understand how it happened.

The ID, Name and Gender are the types that you have already seen. However the last field was actually of type DateTime which got translated to string type in JSON. Why? The answer is simple, JSON doesn’t provide a native DateTime object to store the date and time values. Instead, they use string notation to store the date value. The string value is very much self-explanatory as to what the year is, what month and what value date has. The time part is also clearly visible.

One thing to note here is that C# and JSON can agree on using the “null” value for objects too. Thus if the name is set to a null value, JSON can support the same value of null in its own document format. In the next section, we will study how JSON is mapped to the objects.

Deserializing the JSON

In data-interchange, this is the counterpart of the serialization process. In this process, we take the JSON document and parse it the runtime object (collection). There are many libraries available that can be used for parsing purposes however I am going to talk about the same one that I had been using to demonstrate the usage in C# programming environment. The method is very simple in this case too, However, I am going to use a JSON formatted string variable to use to parse it to the object.

Note: You can use values from files, networks, web APIs and other resources from where you can get the JSON formatted document. Just for the sake of simplicity I am going to use a string variable to hold the values.

The sample JSON data can be like the following,

string data = "{\"ID\": 123,\"Name\": 
               \"Afzaal Ahmad Zeeshan\",\"Gender\": 
               true,\"DateOfBirth\": \"1995-08-29T00:00:00\"}";

I used the following code to deserialize the JSON document.

// Serialize it.
Person obj = JsonConvert.DeserializeObject<Person>(data);

// Print on the screen.
Console.WriteLine(obj.ID);

Now notice one thing here. This “DeserializeObject” function has two versions.

1. A plain non-generic version.
2. A generic version.

If you use the non-generic version, then in C# you are going to use the dynamic object creation in C# and then we will be using the properties. For example, like the code below:

dynamic obj = JsonConvert.DeserializeObject(data);

Console.WriteLine(obj.ID);

Using that dynamic keyword would allow you to bypass the compile time check and allow you to get the “ID” property at a later time. This can be handy when you don’t want to create a class and deserialize against.

However, the version that I am using at the moment is different. It uses a type-parameter that is passed as a generic parameter; angled brackets, and Json.NET deserializes the JSON document and fills up our objects. We can also have array of objects, this way instead of “convincing” the program to iterate over the collection. We can first of all have the JSON parsed as an array of objects and so on. This would help us shorten the code and to check the stuff at all.

var listOfObjects = JsonConvert.DeserializeObject<List<Person>>(data);

Notice that we are passing a “List<>” object. Library would convert the stuff into the list of the objects and we can then use the collection for iterative purposes.

Some errors

There are a few errors that I would like to raise here, which might help you in understanding how JSON works. I will update this section later as I collect more data on this topic.

Type mismatch

If you try to deserialize the JSON of one type (such as, an object) into a type where it cannot be converted to (such as, an array). Library will raise an error. So do the following:

1. Either make sure which type to convert to. Or
2. Do not convert to a generically passed type, instead use dynamic keyword to deserialize the object and then check its type later on runtime. That still doesn’t guarantee it to work.

My recommendations

Finally, I want to give you a few of my own personal experience tips. In my experience I started to work with data on a database system; SQL Server CE I remember. But later I had to create applications which required a bit complex structures and were not going to last another weak. So in such conditions, using a database table was not a good idea. Instead, I had to use a sample and temporary data source. During those days, XML was a popular framework as per my peers. JSON was something that most didn’t understand. So, in my own humble opinion, you should go with JSON, where:

1. Data needs to be shared cross-platform, cross-browser and cross-server. Databases may be helpful, but even they need serialization and stuff like that.
2. You just need to test the stuff. You can target your Model to the JSON parsers and then in release mode change them to the actual data sources.

That is not it, the size of JSON is “amazingly” compact as compared to XML. For example, have a look here:

// JSON
{
 "name": "Afzaal Ahmad Zeeshan",
 "age": 20,
 "emptyObj": { }
}

// XML
<?xml version="1.0" encoding="UTF-8" ?>
<name>Afzaal Ahmad Zeeshan</name>
<age>20</age>
<emptyObj />

Even in the cases where JSON has nothing in it, XML is bound to have that declaration line. Then other problems come around, such as sending an array, or sending out a native type object. In JSON you can do this,

true

In XML, you don’t have any “true” type. So, you are bound to send something extra. Which can cause to be a bottleneck in the networking transmission. I have been writing many articles, blogs and guides and most of them are based on JSON if not on SQL Server.

Why to use C# and when to prefer other languages?!

Introduction and Background

Either it is Quora, or is it C# Corner or is it CodeProject, beginners and novice users are always asking questions like, “Which one to use, C++ or C#?”, and many more similar questions. It is harder to provide an answer to such questions on multiple platforms and to multiple questions. That is why, I thought, why not post a blog post to cover most of the aspects of the question. In this post I am going to cover a few of the concepts that you may want to understand to chose either language from the most widely used languages:

1. C or C++
2. Java
3. C# (or .NET framework itself)

Basically, my own preference in many cases is C#, but that depends on what I am going to build. I have been using C, C++, Java and C# in many applications depending on their needs, depending on how they allow me to write the programs and depending on whether it is the suitable programming language for this type of project and application architecture.

The way, I do that, is just a trick. Which, I am going to share with you, in this blog post. Among these a few of the very basic things to consider are:

1. How simple and easy it would be to use this language in the program?
2. What is the productivity of that language in your scenario!
3. Difficulty level and how many people know the language!

I will be talking about these things points in this post, so to make it clear where to use which programming language. But my major concern in this post would be to cover the aspects of C# programming language.

Productivity of language

First thing to always consider about the language is the productivity that a programming language can provide your team with. Productivity of the language depends on many factors, such as:

1. How programs are built in that language?
2. How fast and reliable is it to build the project regularly?
3. Is the program’s source code readable for other members on the team?
4. Is the language itself suitable for the case that we are going to use it in.

Productivity of the language, in my opinion, is the first thing to consider as the valid candidate to always discuss in the team and not just talk about in a black room. You should manage to get your teams up in a conference room, and then talk about a language. There may be many aspects where one language may fall short and other may get well. There would be many factors that most of the programmers don’t know but talking about them one of the geek would stand up and raise another important point that may guide your team to walk on the correct paths to build greater applications.

Let’s talk a bit graph.

Figure 1: Productivity graph of most widely used programming languages.

In this chart we can see that C is the most productive programming language, of which we are interested in; C, C++, Java and C#. C++ and C# are competing with each other, whereas Java is a bit behind than C# and so on.

In the above graph, it is clear that C# is an average programming language. The average doesn’t mean it is below the requirement. But it means that it can be used in any case, and its performance won’t fall as the data increases. The successful run graph shows that C# programs are much successful in many cases. That is why, in many cases, C# proves to be the valid candidate in many cases, since it is a general purpose programming language.

Then the question arises, “Productive in which sense?”

That is the most important part here. Now, this topic may take a bit more of the time to explain how productive a language is. For that, I have dedicated the topic, “Choosing the right language for the right task“. The right programming language for the right task would always help you to elevate the speed of the programming of your team! But among other aspects, the most important ones are:

1. What sort of project this is?
   • Of course you don’t want to use knife to unscrew a screw.
2. What are the IDE and compilation tools present?
   • Even a program written in C can go wrong if compile is buggy or inefficient.
3. How your team would like to manage the projects?
   • Does the language support good software engineering concepts?
   • Can it be used to generate good diagrams: Use-case, activity, class and other diagrams.

Thus, you should always consider thinking about the productivity of your development team while guessing which language to be used.

Choosing the right language for the right task

It is always stated to use the best tool for the best jobs! Then, why not use the best programming language for your projects, to get the best possible results? Before I continue any further, there is one thing I want to mentioned… “There is no best programming language ever built.” Every time a programming language is built for a purpose, another group of programmers jump in to create a new programming language, for the sake of fixing the errors in the previous language. What do you think motivated Bjarne to create C++ when there was C language and Scala already in the market?

In this section, there are many things to consider, from the performance and benefits to the clients, to the perk packages for the employees to the efficiencies of the project repositories and the tools provided for that programming languages.

C# was created by Microsoft and therefore, in my opinion, has, by far, the most efficient tools for programming. I mean, Visual Studio, alone is the beast in this game.

Figure 2: Visual Studio logo.

I am a huge fan of Visual Studio, and i would doubt someone who isn’t a fan of Visual Studio. C# has a better support and benefit of using the best IDE out there. Java has also a number of IDE, so does C++ and many of the C programs are written in minimal environments, like a small program to manage and compile the C programs; no offence geeks!

Figure 3: Graph of performance to safety ratio.

Now, if you look at this graph, it’s pretty much clear as to what it is trying to guide you with. Of course, as I had mentioned in the starting paragraph here, that there is no best programming language.

In many cases, C# and Java rule over C++ (and C) and in many cases, they rule over C# and Java. There are many factors, like the programming paradigms, performance of the code that is generated; Just-in-time compilation, memory-management delay and so on. While C# and Java may provide the best environment to build “managed” programs in, there are many cases where C# and java don’t work well, like writing a low-level program. Java developers wanted to build a Java OS, but they had to give up because something’s aren’t meant to be done in Java. 🙂

Always consider to search before making the final call. There are many companies working in the similar field that you are going to work in. There would be many packages and languages built for your own field that may help you to get started in no time!

Figure 4: Top 10 programming languages.

But, I think these are a bit backwards. I think, C is on the top because it causes a lot of trouble to beginners, so everyone is searching for “How to do {this} in C” on Google, raising the rankings. 😉

Selecting the best framework

I don’t totally agree with people when it comes to talk about frameworks like, Java, Qt (which I do like in many cases; like Ubuntu programming), and other programming frameworks available for programming applications to be run despite the architecture of the machine. In this case, my recommendation and personal views for .NET framework are very positive. As, already mentioned, I have programmed on Qt framework for Android, Ubuntu and Linux itself. It was a really very powerful framework to build applications on. But the downside was it was tough to learn, their compilers were modified, their C++ was tinkered.

While selecting the best framework for application development by choices are below:

1. How much flexible a framework is?
2. What language does it support?
   • Some frameworks support multiple languages, like .NET framework, it supports C#, VB.NET, Visual C++, JavaScript applications.
3. Is it cross-platform?
4. If not cross-platform, then does it support multiple architectures, at least?

Java framework is cross-platform, and entirely framework oriented. You simply have to target the framework despite the operating system or architecture being used. .NET framework on the other hand is a very beautiful framework to write applications on. It uses C#, VB.NET and C++ (no Java!) to write the applications, and then the compiled binaries can be executed on many machines that can support .NET framework. This provides an excellent cross-architecture support.

C# however, does not support Mac OS X, at the moment. Microsoft has started to roll out cross-platform binaries for C# programs. .NET Core has been a great success and once it gets released to a public version, I am sure most of the companies would start to target it. That is not going to happen, in a near future. In which case, Java and C++ are better than C#.

If you are interested in C# programming on multiple platforms, consider using Mono Project instead. You can read about that, on my blog here: Using C# for cross-platform development.

Figure 5: Top languages and their platforms of usage.

Java may be supported 100% in the rankings, but C# is also supporting multiple platforms and is rapidly growing making the language better than the rest. With the release of C# 6, Microsoft has proved that the language is much better than the rest in the race. There are many features that I like C# 6:

1. String interpolation
2. Getter-only auto-properties as lambdas
3. Improvements to lambdas

There are a few things Java still doesn’t have. For example, one statement code to write the data to the files and to extract the data. You have to get messy in the streams, or you have to write an entirely non-intuitive code with Files object and then to get the data from there… Yuk!

Performance of the compiled code

Writing the source code may be different in many ways:

1. Syntax of the programming language.
2. The way their objects and procedures are imported in the source code.
3. How clean the source code looks. Many programming languages are just nightmares.

But the major concern comes to mind when we are going to execute the programs. In many cases, or should I say in all the cases, the language which are bytecoded languages, lag behind than the languages that are compiled to native codes or Assembly codes. For example, C or C++ codes are faster, because they are not compiled to a bytecode instead they are generated as machine codes for a platform or architecture. C# or Java programs are compiled down to a bytecode which causes a JIT to occur when the programs are executed. This takes time.

However, you can see the following charts from https://attractivechaos.github.io/plb/ and see for yourself, the way bytecoded languages are similar and how much compiled languages are different, see for yourself.

Figure 6: Mathematical calculations.

Figure 7: Pattern matching and machine learning.

Which makes it pretty much clear, how much compiled language are faster than bytecoded, and then come the ones that are interpreted, like Ruby.

In many cases, there are other factors too, which cause bad performance:

1. Bad compiler.
2. A lot of resources being allocated.
3. Slow hardware resources; bad combination of CPU, RAM and other peripherals.
4. Bad programmer and bad code being used.
5. Bad practices of programming.
6. Keeping CPU halted for most of the times.

Much more are a valid candidates for the halting processes.

Finally… Final words

As I have already mentioned that there is no best programming language out there. One language is best in one case, other is best in another case and so on and so forth. In such cases, it is always better to communicate with your development team and then ask them questions and ask for their feedbacks. Choosing the good tools for your projects is always a good approach and good step in the process of programming.

If your software engineer or software architect are trying to find a good solution, ask them to work on the following questions:

1. What are the teams and developers qualified for?
   • Asking a team of C++ programmers to leave C++ and join Java or C# programming teams is not a good idea!
   • Always consider the best approach.
   • Time is money — Manage it with care.
   • Recruit more programmers with skills.
2. Is the programming language long lived, or a minor one?
3. Is programming language capable of making your application work?
   • I have used many programming languages, and thus I can decide which language to use. This is the job of your software architect to decide which languages to select.

If you follow these rules, you will save yourself from many of the future questions that cause a lot of problems. Many times developers ask questions like, “I have an application in Java, how to migrate it to C#?” Many web developers ask questions like, “I have a PHP application, how to convert PHP code to ASP.NET?” These questions have only answer. “Re-write the applications”.

There are many things that you should consider before designing the applications. Facebook is stuck with PHP, because it was written in PHP. Even if they wanted to migrate to ASP.NET, they won’t. Instead, they have found a work around the PHP bugs and downsides.

This is why, you should always consider using a conference or meeting to decide how to start the project, which programming language to use, what frameworks to target, who would lead the team and much more. These few days of discussion and designing would save you a lot of money and time in future.

Guide for building C# apps on Ubuntu: Graphical applications using Windows Forms

Introduction and Background

I took more than necessary break in posting the content and articles for Ubuntu programming in C#. Anyways, I am continuing from the same place where I left and, as already taught that we were at the final stages of sharing the guide for programming C# on Ubuntu; which can be thought of as a Linux environment. The previous posts can be found easily on my blog and on some of the networks that I support.

Previously, we had already talked about NuGet gallery packages, cryptographic helpers and much more. Whereas, in this post I am going to walk you people through using Windows Forms framework on Mono framework.

Windows Forms framework

Now, who doesn’t know Windows Forms framework in today’s world? If you have ever wanted to or have developed the C# programs or .NET applications. Then you are already familiar with Windows Forms application. Windows Forms is an old framework with graphical capabilities, and has been in the game for a more than a decade by now! It has started to get replaced by Windows Presentation Foundation, but nonetheless, it is still very popular and is being used widely by many software developers and many software development companies are still relying on it.

There are many benefits of using Windows Forms in your regular development teams,

1. It supports graphics, not just the CPU and RAM processing.
2. It can be used with resources for localization support is excellent.
3. Provides a better way for drawing graphics on canvas.
4. Event handling, delegate generation.
5. Asynchronous programming patterns.
6. Good data binding support provided.

I am going to provide you with some good references that you can use to learn more about Windows Forms, if sadly, you have no idea about the Windows Forms framework. However, one thing is for granted. Using Windows Forms is one of the easiest ways of building the graphical applications in ,NET environment.

References

Follow the following links and learn more about Windows Forms:

1. Windows Forms
2. Getting Started with Windows Forms
3. Windows Forms Overview

Graphical applications in Mono Project

We have until now, discussed and learnt how to build small programs and some very common applications that use special kind of algorithms, such as cryptographic helpers which can be used to encrypt and decrypt the data in Ubuntu using C#. Now, until this we haven’t covered graphical applications development in Mono, because that is where this framework lags behind.  So, in this post we would like to learn how to build applications with graphical capabilities too. But, first, let’s talk about the frameworks provided in Mono Project itself.

1. GTK#
   • Which is a similar one to the GTK+ that C++ programmers have. This is a graphical toolkit that compiles down to the native code generation. It supports the native look and feel and can be used. But, it is somewhat difficult to learn!
     
     Figure 1: GTK# control application example.
2. Windows Forms
   • This is the topic that we are going to cover in this post.
3. Other tools?
   • Not yet, Mono Project is not ready to implement other frameworks yet.

The thing is, Mono Project doesn’t have an excellent UI designer as we have in Visual Studio.

Figure 2: Visual Studio UI Designer.

In Mono Project and Xamarin Studio, you are not provided with the similar tools until now. However, the designer is just the wrapper around the back-end code available. Xamarin Studio does have a good designer, but that works with GTK# tools and controls only. Not in the case of Windows Forms.

Applying a quick hack!

If you have ever programmed for Windows Forms, then you would know that Windows Forms is actually a bunch of objects with many fields and properties, which run and work to render the graphics on the screen. The same is applicable here. We would be using the codes to render the stuff on the screen. Basically, everything that you have on the screen is a field in the backend class, such as “Button”, “TextBox”, “Label” etc. These are all going to be used, but, we are going to write the codes for this, instead of having a designer build them up for us.

Building the UI with Windows Forms

So, I hope using the hack is clear to you, after all, it is not a hack it is the actual way in which Windows Forms applications are constructed, built and executed. Only difference is that on Windows we also get to use the UI designer. In case of Mono Project, we would have to craft the UI with our own codes and then re-implement it if there is a changing to be performed on the screen later. Thus, putting it simply, we are going to implement it the hard way since there is no, “Drag-and-drop” method here.

To get started, you need to understand that a Windows Forms application is a C# application too. So, only thing to understand is C# language itself and the .NET framework. We are going to use the same concepts of .NET framework and then implement the same concepts to Mono to get our graphical applications ready.

Create project — Any type

I had chosen to build this application on the top of Console application. You can select other types too. But, my recommendation is using the Console application.

Figure 3: Selecting the console project as the type.

Enter the names and details and create the project.

Figure 4: Entering the details for the project.

At this moment, you will be at the same stage where you were in the beginning of this module, and the previous ones. You will have an empty project, that only renders, “Hello world”. That is the start, from here we will continue to build the larger and complex stuff.

Figure 5: Hello world!

This program is the default program that every time we were shown. Now, we need to add the graphics to the console. That’s simple. All we need to do is… Read the next section. 😉

Adding graphics to the console

Adding the graphics to the console is pretty much simple, you just need to do the trick as:

1. Include the System.Windows.Forms namespace to the project.
2. Include the System.Drawing namespace to the project.
3. Import the packages to your source code.
4. Write the code yourself; since we do not have the designer.
5. Run the program, and you will see the program start up.

But, I am going to show you how to do that in a minute or two. But first, let us understand why Windows Forms can be build using the code itself. The thing is, the Windows Forms applications are started on a thread, the thread gets the graphics objects and bitmaps which are rendered on the screen later. The objects are simply instances of the classes, for instance of Button class. These are all passed to the Application object, and they are executed, upon execution they render the graphics on the screen.

Another thing to understand and note is that Windows Forms uses System.Drawing to draw the native code in Mono. Mono targets the objects using the assemblies provided in System.Drawing namespace, and then renders the objects on the screen. At the moment, Mono supports on Win32 theme for the objects. In the end of this post, you will see how your objects are going to look. Remember, the objects are instances… 🙂

Open the references and add the references to System.Windows.Forms and System.Drawing namespaces,

Figure 6: Initially references are like this.

Figure 7: Adding the references to the namespaces. 

Now that we have everything set up, we can now continue to create a new Windows Form. This method is not similar to what we had in the previous IDEs, like Visual Studio. Instead, we are going to just mimic having a Windows Form.

Adding the Windows Form to your project

First thing to note is that there is no way of creating the form by itself in Mono Project. So, we are going to create a new object, and then we are going to turn it into the form and then render it using the main function. That’s just similar to what happens in Visual Studio too. You create the form, whose graphics are rendered separately in a designer, and the codefile is generated separately. Visual Studio maintains everything for you, which is why you do not feel anything different.

Step 1:

Create a new class, name it what you like, I chose MyForm and then write the following code to it.

using System;
using System.Windows.Forms;

namespace GraphicalApp
{
    public class MyForm : Form
    {
        // No properties.

        public MyForm ()
        {
            // Default constructor
        }

        // No functions.
    }
}

This is it. This is out, Windows Form now.

Step 2:

Before running the program, you also need to make sure that the main function now calls this form to be executed in the application too.

// In the references
using System.Windows.Forms;

// In the main function
Application.Run(new MyForm());

Now, run the project and you will (should!) see the following window with no controls, but with a graphical notation and rendering.

Figure 8: Sample empty Windows Form application.

This shows that our project is ready to accept the objects for graphical components. We can now write the code for the objects that we need to render. For example and for the sake of simplicity I would like to create a sample form that renders the form, which would ask me about my name and then would greet me once I click on the button.

All of these are core C# programming concepts and this has nothing to do with the Windows Forms or any other fundamental concept. Instead, these are very simple and yet easy features of C# programming language itself.

Step 3:

Anyways, to update, we can just update the MyForm class and write the code that we would need to have in order to render the form.

using System;
using System.Windows.Forms;
using System.Drawing;

namespace GraphicalApp
{
    public class MyForm : Form
    {
        // Properties.
        private Label label;
        private TextBox myName;
        private Button btn;

        public MyForm ()
        {
            // Call the function to render the objects.
            Text = "Windows Forms app";

            this.Size = new Size(300, 350);
            render();
        }

        private void render() {
            label = new Label { Text = "Your name: ", Location = new Point(10, 35) };
            myName = new TextBox { Location = new Point(10, 60), Width = 150 };
            btn = new Button { Text = "Submit", Location = new Point(10, 100) };
            btn.Click += Btn_Click; // Handle the event.

            // Attach these objects to the graphics window.
            this.Controls.Add(label);
            this.Controls.Add(myName);
            this.Controls.Add(btn);
        }

        // Handler
        void Btn_Click (object sender, EventArgs e)
        {
            MessageBox.Show ("Hello, " + myName.Text + "!");
        }
    }
}

Now again run the program, and you will see the following graphical application being rendered on the screen for you!

Figure 9: This is the Windows Forms application on Ubuntu. 

Figure 10: Entering the data and seeing that it works. 

Now, if you have been an old geek for Microsoft and Windows, then you would know that this style existed for decades in Windows environment. This style was typically adopted for Windows programming with C++, especially Win32 and then later C# was introduced and they had a different style; create a WPF app and look for yourself!

This is how Mono does the trick for Windows Forms. It does support Windows Forms and can use the same power of .NET framework to provide the similar ways to build the graphical applications for Linux environment. The benefit is that, you can now execute, build and run these graphical applications on Windows, Linux (every distro that supports Mono runtime) and Mac OS X. What more could you ask for? 🙂

Points of Interest

In this post, i have walked you through different stages of building the graphical applications on Ubuntu using C# in Mono Project. The benefit of using graphical applications is that you can do more in less area, because “A picture worth a thousand words!”. Windows Forms is a framework that has been widely used by programmers of C# language and is still being used. If you can port your applications of Windows Forms to other platforms, it would be much better.

In this post, I have shown you how to do that. You can port your Windows Forms application, by porting the code for that application project, and then building it under Mono compilers.

The Mono runtime however, only supports Win32 theme for controls and however, provides a versatile amount of features, incredibly, they support all the new features of Windows Forms too. Which means, you can work around with:

1. Graphics
2. Multimedia
3. Content management
4. Data binding
5. Event handling
6. Asynchronous programming

And much more. There are more posts about Mono framework to come, but we are getting closer to having the guide completed and to be ready as a complete guide for “Programming C# on Linux”; or Ubuntu, what-ever you prefer. 🙂

What Windows Runtime can teach .NET developers?

Introduction and Background

C# programming language has evolved too much in these years and many frameworks and platforms have been created and developed that support C# language as their primary programming language. Indeed, C# was release with .NET framework but has grown out to support Windows Runtime applications, ASP.NET applications, many .NET framework platforms such as WPF, WinForms etc. I have programmed for all of these frameworks, taught beginners in these frameworks and also wrote a lot of articles for these frameworks. However, the framework that appealed my interests the most was Windows Runtime. Windows Runtime is the new kid on the block with an object-oriented design and performance factor much similar to that of C++ applications.

At a higher-level it seems very simple, easy and straight-forward application development framework. At its core, it has great amount of validations and check points and most of the times, it is pain in somewhere censored. I remember the days when I was developing applications for .NET framework. WPF, WinForms, ASP.NET and other similar ones. I did have a few problems learning and starting, but there was one thing: Underlying framework was a very patient one. They never showed hatred for beginners or newbies. But when I started to write applications for Windows Runtime, I found out that it had no patience in it, at all. It was like, do this or it’s not gonna work.

Figure 1: Windows kernel services and how it branches into different frameworks. 

In this post, I am going to collectively talk about a few things that Windows Runtime may teach C# programmers, for a better overview of the applications that they are going to develop.

1. As a framework

Windows Runtime came into existence way after .NET framework itself and the child frameworks of .NET framework. But one thing that I find in Windows Runtime is that it is very much based on asynchronous patterns for programming. Microsoft never wanted to provide a good UI and UX but to leave out the performance factors.

One of the things that I find in Windows Runtime is that it still uses the same philosophy of C# programming language. But, adds the asynchronous pattern, too much. Not too much in a bad way, but in a positive way. The benefit is that you get to perform many things at the same time and let the framework handle stuff. So a few of the things that it teaches are, that you should always consider having tasks when there is a chance of latency.

1. Network
2. File I/O
3. Long running tasks

These are the bottlenecks in the performance. Windows Runtime allows you to overcome these. .NET framework also uses the same mechanism, but developers typically leave out that part and go for the non-async functions. Bad practice!

References

For more on asynchronous programming, please refer to:

1. Diving deep with WinRT and await
2. Asynchronous Programming with Async and Await

2. Modularity

C++ programmers have been using modular programming, developing small snippets of codes and then using them here and there. Basically, modularity provides you with an efficient way of reusing the code in many areas of the application. Windows Runtime has a great modularity philosophy.

The foundation has been laid down on categories, and under those categories there are namespaces that contain the objects that communicate and bring an outstanding experience for the developers.

C# is an object-oriented programming, which means that even if you’re forcing yourself to have a single source file. You are still going to have multiple objects, working collectively for each of the purpose of that application.

Yet, it is recommended that you keep things where they belong.

Figure 2: Modules can contain the functionality in them, through which user can communicate with the underlying objects and data sources.

References

1. Windows API reference for Windows Runtime apps
2. Modularity

3. Simplicity of the development

I don’t want to lie here, Windows Runtime is simple, it takes times to understand its simplicity. 😉

When I started to write applications for Windows Runtime framework, I did not understand the framework or how to develop the application. That is because, I was fond of straight-forward small programs. Windows Runtime is a beast, a humungousaur, with its handles hanging down to the developers through the interfaces of C# language.

Windows Runtime has everything already set up in different areas. Like, the views, source code, capabilities, properties, resources and much more.

Visual Studio brings a way more simpler mean of development. I mean, Visual Studio handled everything,

1. Managing the source code.
2. Managing the output directories and how binaries are generated.
3. Managing the visual items; the image assets may be difficult to add, Visual Studio makes it really very easy to add the assets of different sizes.
4. The properties and manifest of the application is also written in XML. But Visual Studio makes really very simple to edit and update the manifest of the application.

While building applications for other platforms and frameworks, like WPF, we can use the same philosophy of Windows Runtime to build a great project and package directory. The settings and configuration files can be kep separate to make it simpler to build the development process.

4. Keep all architectures in mind

.NET framework developers don’t have to worry about the architecture that they are going to target. That made them forget the way that application would be targeted on multiple devices and environments. Windows Runtime is not like that. Windows Runtime generates multiple binaries for multiple environments, multiple architectures and devices.

1. x86
2. x64
3. ARM

These are a few of the configurations for which binaries are generated and since the code that gets generated in a native one. The code must match the architecture, otherwise, the results are undefined.

However implementing the multiple architecture pattern would also require more manpower, more time for testing and implementing the patterns. Windows Runtime in Visual Studio has all of that already supported, but thing is, you need your men ready for any new framework to be included and tested on.

5. You may want to test it again!

Before, Windows Runtime, I thought, if everything works correctly. It is going to work anyways. But, ever since I had started to write applications for Windows Runtime and Windows Store I forgot that mind set and wanted to ensure that it passed all of the tests that it must undergo. That all started when I was about to upload my application, “Note It! App” to Windows Store. Application was passing all of the tests in Debug mode. Yet, when it was tested in the Release mode, it failed many of the tests.

Note: I am not talking about the Windows App Certification Tests.

The thing is, the code in the Debug mode has a debugger attached, which knows when something is going wrong and tells the developers about it and we can fix it. In Release mode, it is not the same. The error checks, the memory segmentation and other stuff in Windows Runtime is not same as it is in .NET framework. .NET framework uses Just-in-time compilation and performs many checks. However, in Windows Runtime, that is not the case. Everything is pre-compiled to overcome the JIT latency; delay.

That is exactly why, you should build the application in debug mode. However, always test the applications in Release mode. If you test the application in debug mode, you will skip a few of the key points in your application where it needs to be checked against.

Also, at the end, the App Cert Kit would be found useful to test if other tests, like resources, binaries and signature packaging is all well.

Figure 3: App Certification Kit.

References

For more about it, read these:

1. Release IS NOT Debug: 64bit Optimizations and C# Method Inlining in Release Build Call Stacks
2. Debugging Release Mode Problems

Points of Interest

No developer wants to publish their buggy and faulty application on the Internet. I try, not to publish the application until it has passed every possible condition of test. However, no software is 100% bug-free and perfect solution.

In this post, I didn’t mean to target Windows Runtime as an ideal case for solution building, instead I wanted to just share a few of the great cards it has up its sleeves. .NET framework is simple, easy and agile to build on. But agility may drive you insane someday sooner.

Always keep these things on mind, and write applications by keeping these things in mind.

Earning revenue through in-app purchases on Windows Store

Introduction and Background

A small overview of in-app purchases in Windows Store platform, in this post I will only cover the short summaries of quickly editing the small modules that you have recently created and to enable users to purchase them to support your development environments. Building applications is a tough task, and programmers need to be given what they deserve. Sometimes, respect is just not enough. Sometimes, the module you created is a tough one and you have full rights to ask for some money in a repay. It is your choice to select a price that users have to pay before they can consume the service.

Windows Store allows you to simply create a block of code, around the service, feature or application itself. That code is capable of managing the payment information, client information and other required stuff to make sure the user pays you before they can access the information and the service you are providing them with. Windows Store holds information for users too, it knows if a user has already made the purchase. If so, Windows Store won’t bother the users again to make the purchase and will hold the information for that license, user has acquired.

App monetization methods

On Windows Store you are offered with many methods and ways to earn money and to get support for your development environments and stuff! A few of them are:

1. Ads display in your application.
   • The ads are of both types, static images or videos.
2. Providing paid services in your applications.
3. Asking for a pre-use purchase of your application. Paid apps.

You can ask for an upfront payment by your users. Many application developers use this method to support their development scenarios. This allows them to have an upfront payment to continue their programming and to support any of the updates to their clients. Not just this, the clients are also able to get free updates to the application later one.

But sometimes you want to allow your users to download and install the applications for free! This allows you to allow your users to try out your application. Users like free stuff, specially the stuff that is not available currently in their device’s marketplace. You can develop an application and start to offer a trial-period to allow users to use your service. If they like it, you can then ask them to purchase the license.

Otherwise, you can add a service separately that needs users to purchase it. You can add the price for it and allow users to purchase it. This method is very simple, helpful and handy! Your users can try out the application that they want to, and you can get the revenue for the features that were difficult to build and deploy. In this post, I will discuss and talk about the monetization methods by “in-app purchases” in Windows Store applications.

In-app purchases in Windows Store apps

In-app purchases requires you to have a Windows Store developer account and that you have published your application! In-app purchases are edited (and published) from the WIndows Store dashboard. You create a new in-app purchase in the dashboard, you edit the details and then update the application’s code to call those in-app purchases and provide the users with a service.

If you do not have a Windows Store developer account, you can still edit the application, you can test the license information but you won’t be able to publish the application, you won’t be able to ask your users (if any!) to purchase the services. So, first step would be to create a new developer account. Register as a developer.

If you are all set up for publishing a new application, continue with the sections and by the end you will be able to include in-app purchases for earning some revenue for your development tasks!

Creating a new app

Although, for development purposes you can test the application for performing the purchases without an online application, or a developer account. For that, you can use CurrentAppSimulator object, instead of CurrentApp object from Windows Store API. CurrentAppSimulator allows you to perform actions without having to call the active Windows Store APIs, and to just test the code in your application. This lets you test many things in your application and how user interacts with your application.

However, if you do not like to waste time, you can just head over to the “hard core” stuff. Where you publish an application, create a new in-app and start consuming it and allowing the users to purchase it. First of all, head over to the dashboard (provided: You have a developer account!) and create a new application. Publish it to the store.

Note: Developing application, uploading the source code and getting it to be published after verification takes time. My application took 16+ hours. Yours should have to go through the same procedure so be patient. I assume that you are having an application ready.

Once your application is created, continue to the next section and start creating and developing for an in-app purchase.

Creating the in-app product

The in-app product first needs to be defined in the Windows Store and the team then needs to approve the service. Once the product service has been approved by the team, you can use the product ID of that service to program your application. The product ID is used to check the license information for the application and if user owns the license to use the service or not.

License Information

LicenseInformation object of the application holds the information about the license. License can be checked for,

1. ExpirationDate
2. IsActive
3. IsTrial
4. ProductLicenses

These properties can be checked to determine the information about license of the application (if your application is a paid application), otherwise you can check for licenses of the in-app products. The in-app products also have a license and they also have properties set up, like active, trial etc. You can check against them!

An example of this license information is something like this,

var license = CurrentApp.LicenseInformation;

if(license.IsActive) {
    // License is active
    // Allow user to use the service.
} else {
    // Allow the users to purchase the service.
}

The same applies to in-app products! You would use the same method, the code for in-apps is in a later section so continue to read.

Create a product in Windows Store

You will be able to create a new in-app product online, on your application’s dashboard! Head over there and find the following option.

Figure 1: Windows Store showing IAPs option.

Click on this option and it would take you a new page where you can create a new IAP! Click on, “Create a new IAP” and enter a new product ID.

Figure 2: Enter a new product ID here and click on “Create IAP”.

You may have read that you need to be sure of the name. You won’t be able to update or delete it once you publish it.

Editing the in-app product

You will then be able to update the properties for that product in Windows Store. This is when your updates and properties would need to be verified. You will get the following three properties, that you can edit to make your product a bit “understandable”!

1. Properties
   • Type of the purchase:
     • Consumables are those services that can be consumed. Like, 500 gold coins! Users can use them and re-purchase them.
     • Durables are those who have a lifetime. Like a premium service of 30 days.
   • Content type
   • Keywords
   • Tag
2. Pricing and availability
   • Base price
   • A few other settings like Markets to sell the product in.
3. Descriptions
   • Language
   • Description and title for the purchase. This is shown in the Windows Store.

You can edit the properties there, and then continue to submit it to the store. The team there would read the information and would approve it if there aren’t any problems with it. Chances are, it gets approved within an hour. Then you would continue to write the code to handle the products.

Remember: It takes at least one day to make the changes on the system. So, even if you upload the package along with the products, it would take one day for Windows Store to be able to start selling your products.

Writing the application to provide services

The Windows Store side is a very short process that you can perform in within less than 30 minutes. The longer part is to write the source code to handle the user’s license and to allow or request the user to purchase the license and service. The code is very short, intuitive and simple! I will explain the entire process here, so that it is very easy for you to get started earning revenues from Windows Store applications that you build.

Create a module

I wonder why this section even exists. Just create a module, a function or a service that performs some actions in your application. Suppose, you want to earn something from it. You can create it as a function, so that you can wrap the function within another code block that checks for a license. License information would be used to either allow the user to consume the service or to reject the request and to ask the user to purchase the service from Windows Store.

Add the license check-up!

I shared a code above, to determine the license for the application, you would do the same in case of in-app product too. You would see if a user has the license or not. The following code would do the thing for you:

// Remember the license object we created above?
if(license.ProductLicenses["productId"].IsActive) {
   // productId that you created while creating the in-app product

   // The user owns the license to use it.
} else {
   // Ask the user to get a licence.
}

You can use the CurrentApp.RequestProductPurchaseAsync(“productId”) function to allow the user to purchase the product from Windows Store. Windows Store would open a new window for the user to make a purchase. You can then (as its result) check if the user made the purchase or not. If he made the purchase, then allow him to use the service otherwise just end the request.

The common example for this would be like this:

// Get the license for the user
var license = CurrentApp.LicenseInformation;

// License for the in-app
var iapLicense = license.ProductLicenses["productId"];

// Apply a condition for the in-app product license
if(iapLicense.IsActive) {
   // User has bought the service; provide service
   provideService();
} else {
   // Allow user to purchase it
   await var resultOfPurchase = CurrentApp.RequestProductPurchaseAsync("productId");
   if(resultOfPurchase.Status == ProductPurchaseStatus.Succeeded) {
      // User has bought the service now
   } else {
      // Show the error message; for try again.
   }
}

This way, user would be able to purchase the item from Windows Store. The process is mostly similar to this one:

Figure 3: Windows Store purchase window is loading up.

Figure 4: Windows Store shows the details for the purchase the user is about to make. Also allows them to add a payment method to their account.

Figure 5: Windows Store shows the following methods (or any other, or less; depending on the country of users) to allow them to make the purchase. 

This would then allow the users to make a payment and then it would update their licenses to be able to consume the service later. It would update the “IsActive” property of their license information.

Points of Interest

This is it for this post, in this post you were taught how to earn revenue from your Windows Store applications. MSDN documentation has a lot of great resources available for developers to learn more about in-app purchases and services provided to developers to ensure that users pay for their services and for the users, to allow developers that they have indeed made the purchase and you should allow them to use the service.

There are many other topics that you should consider reading, such as:

1. Allowing consuming of services like tokens.
2. Managing the services from Windows Store.
3. Adding more in-app products.
4. Using receipts to verify the purchase status.
5. Validating the receipts of services.

As a further read, you should consider reading “Enable in-app product purchases” guide on MSDN. I hope I have helped you with this post, and I think this is the last post for 2015, catch you in the next year!

Happy New Year! 🙂

Tackling text-to-speech and audio file in Windows Store applications

Introduction and Background

I was adding a few more features to the Windows Store application that I have, “Speak It!“, and while doing so it became much more complex task as I dig deeper into streams. Remember, streams provided by Windows Runtime are not as much simpler as .NET has. So, in this post I will talk about a few of those hazards that you may come across. This post consists of two sections, first one is to talk about the “Text-to-speech” API in Windows Store, sorry, Universal Windows Platform and the second one would talk about the saving the generated speech stream to an audio file.

I have already shared most of the concept in another article of mine, which covers the basic concepts, prerequisites and other basic stuff to be understood to build a Text-to-speech application. Unfortunately, that was .NET oriented whereas this article covers the concepts for text-to-speech API in Windows Runtime API set. The article can be read on C# Corner as I did not post it as a blog here, sorry.

App That Reads Out Text For You in WPF

That article is very much similar, because .NET for Windows Store is pretty much similar to what we have as .NET itself! .NET framework (in my opinion!) is very much simple, easy and intuitive as compared to Windows Runtime API set. You can use the same code provided there to get start with the text-to-speech portion, however there are a few differences that I must warn you about. That article also talks about the audio file generation, in this article post I will discuss the development stages in Windows Runtime too. So, follow up with me and learn how to do that!

1. Building text-to-speech part of the application

First section would be to build the basic foundation of the application. I am not going to talk about the UI or UX guidelines at all, instead I will move on to C# code to share how to actually build the application on the backend, so that it actually does some work instead of just showing up its belly. 🙂

I don’t know why, but Windows development team would like to add speech APIs to media technologies and thus they have provided the objects (classes) under Windows.Media.SpeechSynthesis namespace. Please understand this fact, text-to-speech in Windows API is very simple and intuitive task, you don’t even have to do anything to perform a function to generate speech for text. Windows manages everything itself. So, I am going to show you the C# code, simple C# code, that can generate the audio results for the text that you enter in the application.

Initializing the synthesizer

The synthesizer is defined in the above mentioned namespace, you can use it by calling a constructor and passing a language (or using the default languages provided by the Windows operating system; which are installed by the user). In most cases you don’t have to set up the engines, you can get them already set up. But if you would want to change the engines up and down, you can still manipulate the object that you create.

// Namespace addition
using Windows.Media.SpeechSynthesis;

// Create the object here...
var synthesizer = new SpeechSynthesizer();

// You can update the properties, such as voice engine being used.

The next step is just to execute the “Synthesize…” function! This function would return the stream, based on what you pass. You can pass text and SSML; which I will not cover, then engine would return the stream for audio speech based on the parameter.

Modifying the properties

Before the final stage, I want to discuss the properties that you may want to update in your engine to provide a better experience to your users and target a wide variety of audience.

Voices and other stuff

First of all, you should consider that an engine would always require a voice to be installed on the system. Each and every voice that you want to use, must be there on the system before your application can think about using it in your application! That is why, I would recommend that you first of all, consider which language have been installed. I use English language, my family members also do, but my friends don’t. Some prefer French whereas some have Urdu or Hindi languages installed. So, if you would hard code anything in the application it may cause a runtime exception when application won’t be able to build an engine with specified language. In such cases, you can loop through the available languages (voices!)

// Object created above
var voices = synthesizer.AllVoices;

Now you can loop over each language voice and then provide the users an interface to select a language from each one installed on the machine. Also, allow users to install more languages so that they can render the text in audio streams in many more voices. Voices are also based on genders, geographic location, pitch and age. So you can also find out if a specific language is installed or not.

Then each of the item in this array would target the Voice object. This object is another type, VoiceInformation, which holds the information about the voice that gets used to render the text into. The voice (as already mentioned!) can hold information about language it speaks, age and gender based information. You can also select a language based on these parameters if you want to select a language and don’t know which language is installed or don’t want to hard code the language name in your application.

You can then change the voice of the synthesizer to the one you want to use. For example,

// Assume you collected a voice information from the AllVoices list
synthesizer.Voice = voiceFromList;

Then you can continue to the next stage, where you get the stream!

Getting and loading the stream of speech

In Windows 10, you do not get an audio from this API, instead you get a stream of data, audio data, you then need a player to play that stream. Windows 10 has a control named, MediaElement. You can use that player to render the stream for you. Easy way, I would say! The thing is, MediaElement would handle most of the headache for you and you wouldn’t have to work around with the codecs and other byte-management concepts, you just send it as a resource to the media element and it would then preview it.

Even the code to do that is pretty much simple and straight-forward, you only have to specify the stream and the content-type so that MediaElement can render the media correctly. Have a look at the two-line code below:

// Generate the stream
var stream = await synthesizer.SynthesizeTextToStreamAsync(message);

// Set it as a source
mediaElement.SetSource(stream, stream.ContentType);

MediaElement would then render the controls, seek bar and other stuff that it requires.

Figure 1: Application showing controls and resources for text-to-speech

In the above image, it is clear that MediaElement displays the controls, renders the stream and allows the users to pause or play the content and even seek it through the audio stream. This makes it better for story-reader applications.

So, this was it for the text-to-stream section. Rest of the stuff is just “extra cheese topping” that I don’t want to talk about, I want to focus on generating the audio content to be saved as a file on the machine. So, head over to the next section.

2. Generating audio files for audio speech streams

This part was tough one and I had to work on it for like 1 and a half hour to get it to work! Actually, there is a bit of confusion between the Stream object in .NET and the .NET for Windows Store. That caused me a lot of trouble, but anyways I want to share the achievement with you so that you don’t have to pull your hairs off your head.

Selecting a file

In Windows Runtime (or, Windows Store applications), you cannot just move from here to there like you could in .NET environment. You are abstracted by permission set and thus it is better to allow the user to select and set up a location for you to work. This way, Windows won’t intervene and would allow your application to have permissions as if user were doing them himself.

The following code does that and the object being used is FileSavePicker, which allows user to select a file where your application would save the data. You can specify the type of file, extension and (optionally) the name of the file.

// Create the object
var picker = new FileSavePicker();

// Set up a few settings
picker.DefaultFileExtension = ".wav";
picker.CommitButtonText = "Save";
picker.FileTypeChoices.Add("Audio", new List<string>() { ".wav" });

// Let the user select a file now; and a location
var file = await picker.PickSaveFileAsync();

Then you can use the file selected and load the data in it. The conceptual point comes after this. If the user has selected the file, you now need to:

1. Open a stream to that file, with read/write permissions.
2. Create a byte-array for the stream you have.
   1. For this, you would need to use MemoryStream.
3. Write those byte-array values to the file.
4. File type would be .wav file so make sure it is that one.
5. Commit the changes to the file system and you’re done!

Now, implementing the above logic is also very similar part. Have a look at the following code, FileIO object provided by Windows Runtime is a great object to lets us work around with Input/output across the files. So, using the same object I am going to write a block that does what I want it to…

// If user selected a file
if (file != null)
{
    // Create a memory stream
    using (var mem = new MemoryStream())
    {
        // Get the stream object; Stream of .NET
        var strm = stream.AsStream();
        strm.Position = 0;                  // Change the location index to copy from
        await strm.CopyToAsync(mem);
       
        // Convert to array of bytes
        var array = mem.ToArray();
        // Write the byte-array to the file.
        await FileIO.WriteBytesAsync(file, array);
    }
}

Just the above code is required! We’re done. The code when I refactored it, amazed me and I was very much shocked as to why did I not get it in the first place. The code is simple and it does what it is intended to do, so if I convert the above speech stream to audio file, it would be like this.

Figure 2: FileSavePicker showing the interface to select a file to save the data to.

Figure 3: Windows File Manager showing the “MyAudio” file just created using the above mentioned application for Windows 10!

So, this way we can store the data in audio file.

Points of Interest

Windows 10 is new, Windows Runtime is also new… Most of the C# programmers are still fond of .NET environment, although Microsoft did provide them with tools to work around in Windows Runtime, but still Windows Runtime API is not as much simple and beautiful as is .NET framework.

This post talks about and shares the information required to build your own text-to-speech application and not just that, it also shares how to convert that audio stream to audio file that can be played later. Of course on this post, I cannot play the file but in real, it does say what I wrote. 🙂

It’s almost end of the month, I may write a new post someday earlier, but anyways, Happy new year folks! 🙂

ASP.NET 5 mixed with Windows 10!

Recently I was amazed by the new things ASP.NET 5 has in the Web API of its and also on the other hand I was looking forward to write an article for Windows 10. I thought why not write an article for them both! It was a great opportunity for me to do so, as I learnt many things while on the way to write the article and while compiling the resources for my article.

The article that I recently published on CodeProject and C# Corner introduces how users can create a Windows 10 application which actually serves as the client for an ASP.NET 5 Web API! ASP.NET 5 introduces many updates to old Web API and this one is as simple as a single controller that you can use to create and set your API, yes a single controller!

I would recommend that you definitely go and read the article on any of the following networks, which ever you prefer.

1. on CodeProject
2. on C# Corner

Do not forget to vote and share your valuable comments or feedback so that I can make the post even better!

You may also get the source code from MSDN galleries. Be sure to download the package and vote for it.

See you next time with something else, helpful for you! 🙂

Windows app development

Well, since the upgrade of Windows 8, developers can now develop apps in HTML and CSS. Windows 8.1 has some other built-in bug fixes too. But this feature came up by the upgrade of OS from Win 7 to Win 8.

Now, we can create a simple and easy HTML software for Windows API. We can stylize it using CSS, and we can work on the events using JavaScript, man please no more JavaScript talk, I am sick of it. jQuery would be used here more oftenly, but still we would need to stick to pure (or native) JavaScript in some places where we would be handling the OS based messages.

So, let us get our selves warmed up for Windows Programming too. It’s just been made easy for us!

For more go to: http://msdn.microsoft.com/en-us/windows/apps/br229512