Marking Methods “Obsolete” In C# Class Library

Note: For my all articles on C#.Net / Visual Studio, please visit here.

The following are the objectives of this article:

  • What’s an obsolete method?
  • Why & when should a method be marked as obsolete?
  • Available options in C#

What’s an obsolete method?

A method in a class library which is old or out-of-use and some other method instead of this is suggested to be used.

Generally, when you are introducing some new functionality in your class library but still want to keep an old method intact for some time until the next big release then it’s better to mark that old method as “Obsolete” and offer new functionality in a new method.

Why & when should a method be marked as obsolete?

You are introducing some changes in your class library, and replacing a method with a new one with some added features, at that time it is a good idea to not suddenly remove that method from your class library because it may break some code. But if you mark that method as obsolete then it is an indication that this method is already out-of-use and something else should be used in its place.

Available options in C#

Let’s now see what options are available in C# to mark a method as obsolete.

Open Visual Studio 2015 or 2017 and create a C# class library project named “TestClassLibrary”:

C#

Add a new static class in that project names “TestClass”. Add the following method in that class,

public static string ToUpper(string input) {  
    return input.ToUpper();  
}

Now right click on solution and add a new console application project named “TestConsoleApplication”.

C#

Add reference of class library project in console application project,

C#

Go to the Program.cs class and add following “using” statement at top,

using TestClassLibrary;

Go to the “Main” method and add following code

Console.WriteLine(TestClass.ToUpper("test input"));  

Console.ReadKey();

Build the solution by pressing F6 and it should build fine without any error or warning.

Now, let’s go to the TestClass and mark the ToUpper method as obsolete. For that just add “[Obsolete()]” attribute above the ToUpper method.

The whole TestClass.cs will look like this,

C#

What have we done here?

We have marked the method with “Obsolete” attribute indicating its users that this method is now deprecated and will be removed in future release. So, it’s advisable not to use it.

If you go to the console application, then you will see a green line below the code where this method is called, if you move your mouse over that green line you will see the warning message,

C#

If you build the project and then see error list window, you will see a warning,

C#

Note here the warning code CS0612. It’s a compiler warning code. If you click on the link CS0612, then you will see Microsoft documentation for this code will open in your browser,

C#

But this does not look like a good direction to the programmers on what to use if not this method.

Let’s add one more method to class library.

Go to TestClass.cs in class library project and add following method which has better error handling and its culture-neutral.

public static string MakeUpperCase(string input) {  
    if (String.IsNullOrEmpty(input)) throw new ArgumentNullException(nameof(input));  

    return input.ToUpperInvariant();
}

Now we want to indicate to the programmers that instead of “ToUpper” method, they should use “MakeUpperCase” method. Add a message inside “Obsolete” attribute on top of “ToUpper” method:

[Obsolete("This method should not be used, Use MakeUpperCase instead.")]

The whole method will look like,

C#

What have we done here?

We have marked the method with “Obsolete” attribute and added a message to be shown to the user which can work as an indicator to use some other replacement method.

If you now build the project and go to the Main method, you will see a warning with the above message,

C#

Now this looks like a good direction to a programmer who is going to use your class library.

Later, if you think that you have given enough warning and time to programmers using your class library that they should not use this method, and you want to raise an error if they do, then you can convert this warning into error by passing “true” Boolean value after the message:

[Obsolete("This method should not be used, Use MakeUpperCase instead.", true)]

The whole method will look like this,

C#

What have we done here?

We have marked the method with “Obsolete” attribute and added a flag indicating compiler should raise an error if this method is used somewhere.

If you build your project now, it will throw an error,

C#

Use this error flag in your class library when you want to introduce breaking changes in code.

In summary, we have seen the following three overloads of “Obsolete” attribute,

C#

I have attached a sample project with this article, downloaded it and built it one by one by un-commenting only one “Obsolete” attribute at a time,

C#

Note: This article was originally published by me on C# Corner website here.

C# Digit Separator

Note: For all my articles on C#.Net / Visual Studio, please visit here.

 

Sometimes, when you want to represent a big integer or long literal in C# code, it becomes less readable and there are chances to misspell a digit too.

Consider the following example of a C# constant,

const int assumedPopulation = 1122339654;
You will find the one line code is neat and clean, but the numeric value/literal is not so readable.

It would be better if there was some digit separator like we have in Excel for numbers. Then, the number would be easy to read, like below.

1,122,339,654

With C# 7, Microsoft has introduced a digit separator. While it’s not the regular digit separator “comma” which we use everywhere, it’s underscore.

In C# 7, the same line of code can be written as,

const int assumedPopulation = 1_122_339_654;
Doesn’t it make the number quite easily readable?
And this digit separator does not affect its display on UI.

Write the following code in a C# 7 console app (With VS 2017), and check the output on the console. The digit separator will not be printed on console.

static void Main(string[] args)  
{  
   const int assumedPopulation = 1_122_339_654;  

   Console.WriteLine(assumedPopulation);  

   Console.ReadKey();  
}

The C# 7 digit separator can be used with long, ulong, decimal, int, uint, short, ushort, double, byte, float data types.

Note: This article was originally published by me on C# Corner website here.

Data Type Suffixes In C#

Note: For all my blogs on Visual Studio / C# / .NET, please see here.

The objectives of this article are:

  • What is a data type suffix?
  • Why is a data type suffix required?
  • How and when to use a data type suffix?

What is a data type suffix?

In C#, while specifying any value of a variable or literal, a literal is a source code representation of a value and you can append some specific character after the value/literal, which is called a data type suffix. e.g.

  1. var myVal2 = 4294967296L;
  2. var myMoney = 300.5m;
  3. var myRadius = 3.145f;

As shown in the above examples, the L, m and f suffixed after the literals are data type suffixes.

For the scope of this article, I will cover the two types of literals given below to which data type suffixes can be applied:

  • integer-literal
  • real-literal

Why is a data type suffix required?

The data type suffix helps the compiler to unambiguously identify the data type of any value/literal. It also helps C# programmer to explicitly state the data type of the value/literal.

In the cases when a variable is declared, using one of the “var”, “dynamic” or “object” keywords, use the data type suffix to explicitly state the data type of the value.

In case of integer literals, if you don’t specify any suffix, then the integer values are evaluated to a data type, as per the sequence given below.

  • int
  • uint
  • long
  • ulong

In case of real- value literals (those with decimal points or fractions e.g. 3.14), if you don’t specify any suffix, then a real- value literal is evaluated to a data type, as per the sequence given below.

  • double
  • float/decimal (based on suffix)

In short, without any data type suffix, an integer literal will be evaluated to int and real literal will be evaluated to double.

There are data type suffixes given below.

  • L or l for long
    • (l in small letters should be avoided as it confuses you with digit 1)
  • D or d for double
  • F or f for float
  • M or m for decimal
    • (D is already taken for double, so M is best representation for decimal)
  • U or u for unsigned integer
  • UL or ul for unsigned long

There are no data type suffixes for int, byte, sbyte, short, ushort. Previous versions of C# used to have “Y” and “S” suffixes for byte and short respectively, but they were dropped from C# specification after being found, which are not often used by the programmers.

As a C# programmer, you should be aware of these data type suffixes and make use of them in your programming, so that you won’t have any surprises when your code is executed.

How and when to use a data type suffix?

As stated earlier, you as a programmer do not want C# compiler to decide the data type, as per default specification, then use the data type suffixes.

In the examples given below, I will show the usage in C#. Create a Visual Studio project for C# console Application and in the Program class, create the two methods given below:

public static void TestMethod(int i)
{  
            Console.WriteLine("You called integer version of TestMethod");  
}  

public static void TestMethod(long l)  
{  
            Console.WriteLine("You called long version of TestMethod");  
}

You must have seen the code given above to create two overloaded methods with the same name “TestMethod” but different int and long arguments. There is not much logic in the method except the message to be written on the console to identify which one was called. You can imagine that there is a specific code here to do different operations for int and long data types.

Now, in Main method, write the two lines of code:

TestMethod(5);  

TestMethod(5L);  

Console.ReadKey();

You must have noticed two different integer literals passed as parameters to TestMethod. How does the compiler now decide which method to call?

Press F5 to execute the program. You will see the result given below.

c#

The literal “5” without any suffix got evaluated to int, hence the TestMethod with int parameter was called. The literal “5L” got evaluated to long, hence the TestMethod with long parameter was called.

Now, comment out the above three lines in Main method and write the code given below, followed by clicking F5.

var myVal1 = 429496;  

TestMethod(myVal1);   

var myVal2 = 429496L;  

TestMethod(myVal2);

You will see the same output as in previous case due to the same reason.

Now, add the new overload of TestMethod in Program class given below.

public static void TestMethod(uint i)
{  
 Console.WriteLine("You called UNSIGNED integer version of TestMethod");  
}

In Main method, write the code given below and click F5.

var myVal3 = 429496u;  

TestMethod(myVal3);  

Console.ReadKey();

You will now see the third overloaded method and the one, which you just added will be called.

c#

We will see now the programming in case of real value literals.

Comment out the above 3 lines, which you just added for unsigned int. In the Program class, create the three new overloaded methods given below.

public static void TestMethod(double i)
{ 
 Console.WriteLine("You called double version of TestMethod"); 
}

public static void TestMethod(float i) 
{ 
 Console.WriteLine("You called float version of TestMethod"); 
}

public static void TestMethod(decimal i) 
{ 
 Console.WriteLine("You called decimal version of TestMethod"); 
}

In the Main method, write code given below. Subsequently click F5 for the execution.

var myVal4 = 9.99;  

TestMethod(myVal4);  

var myVal5 = 9999999999999999999999999999m;  

TestMethod(myVal5);  

var myVal6 = 3.145f;  

TestMethod(myVal6);  

Console.ReadKey();

You will see the output given below on the console.

c#

Note here that any real literal (those values with fraction point/decimal) will be evaluated to double by default. Hence, the first call executed the TestMethod with double parameter.

A similar example with dynamic keyword is covered in my attached code, so I am not writing it here.

Let’s see what the compiler says when we use lower case.

Write the line given below in Main method, followed by clicking F6 to build the project.

var longTest = 12345l; 

Go to “Error List” Window and click Warning header to see the warning,

c#
There is no error but it warns us to use capital L to denote long literal because lower case l can be easily confused with the digit 1.

Note: This article was first published by me on C# Corner website here.

Introducing The .NET API Browser

Brief intro of Microsoft Dot Net API Browser

Microsoft has launched .NET API Browser as a part of its effort to provide a unified.NET reference experience on docs.microsoft.com.

It is a way to standardize how the developers can document, discover and navigate .NET APIs at Microsoft website.

.NET API Browser can be viewed here

You can have a first look below:

If you expand “All APIs” lookup, then you can see the list of all Microsoft APIs which you can select from:
allapi.png

At the bottom of the API Browser, there are some mainly used APIs already listed under Quick Filters. You can click any of them to quickly navigate to API’s documentation.

qf

Once you select any APIs name from the drop-down, then you will see another drop-down with further selection for API version.

vers.png

Once you select any API (click on the API name under name” column), you will be shown the documentation of that API with its definition, classes, structs and interfaces.

main

You can change the namespace and API version from the same page, using the drop-downs on the left top side.

api.png

 You can also change the language and theme from the top right side.

ln

There are two theme selections available:

tm

In the months to come, Microsoft is going to add more SDKs to this experience. I am missing Office 365 and Microsoft Graph APIs reference here and I hope, it will be added by Microsoft in near future.

Now go to .NET API Browser and explore some documentation.
Happy learning!!!

Note: This article was published by me at C# Corner here.

Installation Of Visual Studio 2017, A Firsthand Explanation

This article tries to give a firsthand and quick introduction to installing Visual Studio 2017, highlighting some of its new features.

Today, Microsoft has launched Visual Studio 2017, the latest IDE for developing “mostly anything” in the Microsoft platform as well as developing apps and Websites, which target Android, iOS and Linux.

If you have already registered for the Microsoft Visual Studio 2017 launch event, then your mailbox may have an email from Microsoft regarding resources related to VS2017, else you can click here to get started with downloading VS2017.

Moreover, if you download VS2017 by March 14, you will get free 60-day access to Xamarin University, which will help you in a great way to enhance your Xamarin skills.

You can choose to install either community, professional or enterprise editions. This article explains the features of the enterprise edition. If you want to know what’s in the different editions, then you can read more here.

If you want to check the installation requirements, you can read more here.

Once you have clicked on your desired edition, the Browser should prompt you to save the installer file.

Visual Studio 2017

Click Save File button to save this installer file to your download folder.

Also, note that once download starts, your Browser will show a “thank you” page with this message related to “Xamarin University”.

Visual Studio 2017

In this article, we are not going to touch anything related to “Xamarin University” but will concentrate only on VS2017.

Meanwhile your installer file may have been downloaded, click on the file to run it. You will be prompted with the message given below.

Visual Studio 2017

Click Yes to continue. You will be prompted with yet another popup, as shown below.

Visual Studio 2017

Click again to Continue.

This release of Visual Studio will show you a new light weight installation approach, which is quite different from the past versions of IDE.

Clicking on “Continue” in the previous popup will show you the installation launch screen given below.

Visual Studio 2017

This is a new “modular” installation experience, where you can tailor VS to install only the components, as per your needs.

You can maximize the installation screen to see more details.

There are 3 tabs here: “Workloads”, “Individual Components” and “Language packs”.

Workloads

It contains a choice for which type of development work you are going to do with VS2017 e.g. Universal Windows Platform development, Desktop development (with Win Forms, WPF), Web development, Mobile development, Office365 development etc.

If you wish to install a development Workload, you can choose it by clicking on the top right checkbox.

Visual Studio 2017

Individual components

This section contains choices to install some tools, which were previously being installed separately as some “packs”. You can see different versions of .NET Framework here like Azure Cloud Explorer and some other MS Azure related tools like Azure Storage Emulator, Azure Data Lake Tools etc. Some SDKs for Android, Windows 10, Typescript  etc. are also there, where you need to choose the ones in which you are interested in by clicking the checkbox in front of the item.

Visual Studio 2017

Language packs

This section offers some language choices for VS2017. English will be selected by default. Most of you may not need any other language.

Visual Studio 2017
Some more points to be noted here  are given below.

There is no “Select All” feature in this new installation, which I really miss. You must go and manually select the components.

Check the right side of the installation Window and it shows Summary as you go on selecting the features.

Visual Studio 2017

You can expand individual items to see what’s inside that and there are some more choices.

Visual Studio 2017

If you need support of some of these sub-features, you can select them by clicking on the check boxes.

You can change VS2017 location at the bottom of the Window.

Visual Studio 2017

At the bottom-right of the installation Window, you can see the approximate installation size (which changes as per feature selection).

Visual Studio 2017

Once you have explored all 3 tabs and sub-features from the “Summary” section and when you are ready to go, click Install button.

You will be shown the screen, which shows installation progress as VS2017 is getting installed.

Visual Studio 2017
Let the installer do its work. While VS2017 is being installed, go and grab a cup of coffee.

Once the installation finishes, you will be prompted to restart.

Visual Studio 2017
It’s a good idea to restart your PC now, as the installer may have changed many things on your PC. Save your important documents, which may be open, click Restart.

Once restarted, find VS2017 in start menu, or type “Visual Studio 2017” in run prompt. There will not be any shortcut on the desktop.

Once loaded, you will be shown a welcome screen.

Visual Studio 2017

Now, again a prompt is there to choose developer settings and theme.

Visual Studio 2017

Make a selection as per your liking and click Start Visual Studio.

Congratulations.

You have installed Visual Studio 2017.

Visual Studio 2017

If you want to read the release notes for VS2017, click here.

Now, go and install the trial version of VS2017 by yourself, write some code, get your hands dirty!

Check for my next article on some new features in VS2017 here.

Note: This article was published by me on C# Corner website here.

Header Image credit: C# Corner

Visual Studio 2017 New Features

In this article, you will be acquainted with Visual Studio 2017 and its new features

Welcome to another article on VS2017. I’m sure that you have already read my article on installation of VS2017. If not, then read it here.

In this article, I will demonstrate some new features of Visual Studio 2017 IDE, which will help a lot in your day to day development.

Creating new project with VS2017

Open VS2017 and you will be shown a welcome page.

There are two ways to create a new project in VS2017.

You can write the type of project, which you want to create in the textbox below “New Project” header.

You will be shown the type of projects as and when you type in the textbox.

e.g. writing “console”:

When you write WPF:

There is also another way to create a new project. Click More project templates link just below the textbox. You will be shown a familiar dialog box to create new projects.

What’s new in Visual Studio IDE

Let’s start by creating a console Application. I will introduce some of the new features in VS2017.

Improved code navigation

After creating a console Application, go to Solution Explorer and right click on the project to add new class.

Let’s say that we are adding new Customer class given below.


Now, save the Customer.cs file and go to Program.cs.

Write Customer in the Main function, press either Ctrl + T (Control key followed by T key) or Ctrl + , (Control button followed by, key).

On the top right, you will be shown a pop-down dialog, which will help you quickly locate the referenced element. Notice that it will quickly launch the “Customer.cs” file too.

In this way, you can have a look at a referenced class and its properties quickly without the need to open the relevant file in IDE. You can simply press ESC key, the dialog, file and both will close.

“Fuzzy” matching

VS2017 introduces a new feature called “fuzzy matching”, which means when you type a name and even if you misspell it, VS2017 will show you the results, which are based on fuzzy match.

To experience it, let’s go to Program.cs -> Main method again.

Type “Cstomer” and see.

VS2017 will automatically suggest you “Customer” class and highlights it for you


Changes in References window

Write the line given below in Main method.

 

  1. Customer cust = new Customer();

 

Now, place the mouse cursor on “Custmer” word, press “Shift” + “F12” keys.

You will be shown a new “references” Window, which has been modified compared to “Find Symbol Results” Window in VS2015.

Notice in the “references” Window, there are many new things here like Filtering (on left side), Group by, Search, “Keep Results” button, Sorting and Colorization.

Let’s see each of them one by one.

Filtering references

In VS2015, when you find all the references on a class or property, you will be shown all the referenced results with no option to filter them. Now, in VS2017, you have filtering option in references Window.

See on the left side that there is a drop-down and by default Entire Solution is selected.

You can filter the references; based on which area you want to see and VS2017 will only show you the relevant references.

Grouping

With the “Group By” feature, you can change how the references are being displayed. It provides you the options given below, which helps you in quickly navigating to the reference; you are looking for,

Let’s say you select “Definition, Project then Path” option and you will see the references group, as shown below.



Search

On the top right section of “references” Window, you can search inside the “references” results.

Keep results

This is a new interesting feature. Remember in VS2015 when you are already looking at one references result and you want to find another class or property reference too. If you search in another class reference, your previous result will be overwritten. You can see only one reference result at a time.

If you press “Keep Results” button on the references Window and you search for another term, then your original result will be preserved and you will be shown references in a new Window.

Let’s say that you create a new “Order” class and reference it from Main method.

Press “Keep Results” button on the references Window of customer results, go to Order class and press Shift + F12. You will be shown references in another Window.

At the bottom of the Window, you will be able to find a tab for “Customer” references too.

Sorting

You can now click on the results column headers like Code, File, Line, Col and Project to have your references result sorted by these columns, which were missing in VS2015.

Colorization

Notice the references are displayed in different colors to help you in clear understanding of the references.

Structure Guide Lines

A dotted vertical line now runs between the curly braces to identify scope. If you mouse over the dotted line, then you will be shown the current scope.


Code Refactoring enhancements

VS2017 has improved refactoring a lot to make the code more readable.

Let’s consider some new improvements.

Object initialization

If you have written the code step by step to assign the values to an object’s property, VS2017 refactoring will now suggest you to use an object initialization.

Write the code given below in Main method.

Now, place your mouse cursor on Customer and press Cltr + . (Control key followed by .)

VS2017 will give you a message “Object initialization can be simplified”.

Click on the suggestion and your code will be modified, as shown below.


Also, there are some more such enhanced features, which you can try yourself:

Inline Out variable.

Simplify null checks.

Add missing case(s) to a Switch statement.

And much more

There are many more new features of VS2017 but for the scope of this article, I will restrict to above five only.

Go and install Visual Studio 2017 on your PC to find out more by yourself.

Happy coding!!!

Note: This article was published by me on C# Corner website here.

Header Image credit: C# Corner