While programming, if you find yourself writing the same statements over and over again, then turn those statements into a function. Functions are like tiny programs that complete one small task. For example, you might write a function to calculate sales tax and then reuse that function in many places in a financial application.

Like programs, functions usually have inputs and outputs. They are sometimes described as black boxes, where you feed some raw materials in one end, and a manufactured item emerges at the other. Once created, you don't need to think about how they work.

Times table example

1 x 12 = 12
2 x 12 = 24
...
12 x 12 = 144

You previously learned about the for statement earlier in this book, so you know that it can be used to generate repeated lines of output when there is a regular pattern, such as the 12 times table, as shown in the following code:

for (int row = 1; row <= 12; row++)
{
  Console.WriteLine($"{row} x 12 = {row * 12}");
}

Writing a times table function

Writing a function that returns a value

Let's implement a function to calculate taxes in various regions around the world:

Converting numbers from cardinal to ordinal

Calculating factorials with recursion

Factorials are written like this: 5!, where the exclamation mark is read as bang, so 5! = 120, that is, five bang equals one hundred and twenty. Bang is a good name for factorials because they increase in size very rapidly, just like an explosion.

We will write a function named Factorial; this will calculate the factorial for an int passed to it as a parameter. We will use a clever technique called recursion, which means a function that calls itself within its implementation, either directly or indirectly:

Do you remember what we can do to be notified of a numeric overflow?

What should you do to get notified when an overflow happens? Of course, we could solve the problem for 13! and 14! by using a long (64-bit integer) instead of an int (32-bit integer), but we will quickly hit the overflow limit again.

The point of this section is to understand that numbers can overflow and how to show that rather than ignore it, not specifically how to calculate factorials higher than 12!.

Documenting functions with XML comments

Figure 4.1: A tooltip showing the default simple method signature

Let's improve the tooltip by adding extra information:

Figure 4.2: A tooltip showing the more detailed method signature

Using lambdas in function implementations

Some of the important attributes of functional languages are defined in the following list:

0 1 1 2 3 5 8 13 21 34 55 ...

The next term in the sequence would be 34 + 55, which is 89.

We will use the Fibonacci sequence to illustrate the difference between an imperative and declarative function implementation:

Debugging during development

1. Use your preferred coding tool to add a new Console Application to the Chapter04 workspace/solution named Debugging.
2. In Visual Studio Code, select Debugging as the active OmniSharp project. When you see the pop-up warning message saying that required assets are missing, click Yes to add them.
3. In Visual Studio, set the startup project for the solution to the current selection.
4. In Program.cs, add a function with a deliberate bug, as shown in the following code:

   static double Add(double a, double b)
   {
     return a * b; // deliberate bug!
   }
   

5. Below the Add function, write statements to declare and set some variables and then add them together using the buggy function, as shown in the following code:

   double a = 4.5;
   double b = 2.5;
   double answer = Add(a, b); 
   WriteLine($"{a} + {b} = {answer}");
   WriteLine("Press ENTER to end the app.");
   ReadLine(); // wait for user to press ENTER
   

6. Run the console application and view the result, as shown in the following partial output:

   4.5 + 2.5 = 11.25
   

But wait, there's a bug! 4.5 added to 2.5 should be 7, not 11.25!

Setting a breakpoint and start debugging

Breakpoints allow us to mark a line of code that we want to pause at to inspect the program state and find bugs.

Using Visual Studio 2022

1. Click in the statement that declares the variable named a.
2. Navigate to Debug | Toggle Breakpoint or press F9. A red circle will then appear in the margin bar on the left-hand side and the statement will be highlighted in red to indicate that a breakpoint has been set, as shown in Figure 4.3:

   

   Figure 4.3: Toggling breakpoints using Visual Studio 2022

   Breakpoints can be toggled off with the same action. You can also left-click in the margin to toggle a breakpoint on and off, or right-click a breakpoint to see more options, such as delete, disable, or edit conditions or actions for an existing breakpoint.

3. Navigate to Debug | Start Debugging or press F5. Visual Studio starts the console application and then pauses when it hits the breakpoint. This is known as break mode. Extra windows titled Locals (showing current values of local variables), Watch 1 (showing any watch expressions you have defined), Call Stack, Exception Settings, and Immediate Window appear. The Debugging toolbar appears. The line that will be executed next is highlighted in yellow, and a yellow arrow points at the line from the margin bar, as shown in Figure 4.4:

   

Figure 4.4: Break mode in Visual Studio 2022

Using Visual Studio Code

Navigating with the debugging toolbar

Both are shown in Figure 4.8 and as described in the following list:

Figure 4.8: Debugging toolbars in Visual Studio 2022 and Visual Studio Code

Debugging windows

The most useful windows are described in the following list:

• VARIABLES, including Locals, which shows the name, value, and type for any local variables automatically. Keep an eye on this window while you step through your code.
• WATCH, or Watch 1, which shows the value of variables and expressions that you manually enter.
• CALL STACK, which shows the stack of function calls.
• BREAKPOINTS, which shows all your breakpoints and allows finer control over them.

When in break mode, there is also a useful window at the bottom of the edit area:

• DEBUG CONSOLE or Immediate Window enables live interaction with your code. You can interrogate the program state, for example, by entering the name of a variable. For example, you can ask a question such as, "What is 1+2?" by typing 1+2 and pressing Enter, as shown in Figure 4.9:

  

Figure 4.9: Interrogating the program state

Stepping through code

Customizing breakpoints

1. If you are still debugging, click the Stop button in the debugging toolbar, or navigate to Run/Debug | Stop Debugging, or press Shift + F5.
2. Navigate to Run | Remove All Breakpoints or Debug | Delete All Breakpoints.
3. Click on the WriteLine statement that outputs the answer.
4. Set a breakpoint by pressing F9 or navigating to Run/Debug | Toggle Breakpoint.
5. In Visual Studio Code, right-click the breakpoint and choose Edit Breakpoint..., and then enter an expression, such as the answer variable must be greater than 9, and note the expression must evaluate to true for the breakpoint to activate, as shown in Figure 4.12:

   

   Figure 4.12: Customizing a breakpoint with an expression using Visual Studio Code

6. In Visual Studio, right-click the breakpoint and choose Conditions..., and then enter an expression, such as the answer variable must be greater than 9, and note the expression must evaluate to true for the breakpoint to activate.
7. Start debugging and note the breakpoint is not hit.
8. Stop debugging.
9. Edit the breakpoint or its conditions and change its expression to less than 9.
10. Start debugging and note the breakpoint is hit.
11. Stop debugging.
12. Edit the breakpoint or its conditions, (in Visual Studio click Add condition) and select Hit Count, then enter a number such as 3, meaning that you would have to hit the breakpoint three times before it activates, as shown in Figure 4.13:

    

    Figure 4.13: Customizing a breakpoint with an expression and hot count using Visual Studio 2022

13. Hover your mouse over the breakpoint's red circle to see a summary, as shown in Figure 4.14:

    

    Figure 4.14: A summary of a customized breakpoint in Visual Studio Code

Logging during development and runtime

End users are notoriously bad at remembering, admitting to, and then accurately describing what they were doing when an error occurred, so you should not rely on them accurately providing useful information to reproduce the problem to understand what caused the problem and then fix it. Instead, you can instrument your code, which means logging events of interest.

Understanding logging options

• Apache log4net
• NLog
• Serilog

Instrumenting with Debug and Trace

Before we delve into them in more detail, let's look at a quick overview of each one:

• The Debug class is used to add logging that gets written only during development.
• The Trace class is used to add logging that gets written during both development and runtime.

You have seen the use of the Console type and its WriteLine method write out to the console window. There is also a pair of types named Debug and Trace that have more flexibility in where they write out to.

The Debug and Trace classes write to any trace listener. A trace listener is a type that can be configured to write output anywhere you like when the WriteLine method is called. There are several trace listeners provided by .NET, including one that outputs to the console, and you can even make your own by inheriting from the TraceListener type.

Writing to the default trace listener

Let's see trace listeners in action:

Configuring trace listeners

Switching trace levels

The value of a trace switch can be set using a number or a word. For example, the number 3 can be replaced with the word Info, as shown in the following table:

Adding packages to a project in Visual Studio Code

1. Navigate to the TERMINAL window for the Instrumenting project.
2. Enter the following command:

   dotnet add package Microsoft.Extensions.Configuration
   

3. Enter the following command:

   dotnet add package Microsoft.Extensions.Configuration.Binder
   

4. Enter the following command:

   dotnet add package Microsoft.Extensions.Configuration.Json
   

5. Enter the following command:

   dotnet add package Microsoft.Extensions.Configuration.FileExtensions
   

   dotnet add package adds a reference to a NuGet package to your project file. It will be downloaded during the build process. dotnet add reference adds a project-to-project reference to your project file. The referenced project will be compiled if needed during the build process.

Adding packages to a project in Visual Studio 2022

1. In Solution Explorer, right-click the Instrumenting project and select Manage NuGet Packages.
2. Select the Browse tab.
3. In the search box, enter Microsoft.Extensions.Configuration.
4. Select each of these NuGet packages and click the Install button, as shown in Figure 4.18:
   1. Microsoft.Extensions.Configuration
   2. Microsoft.Extensions.Configuration.Binder
   3. Microsoft.Extensions.Configuration.Json
   4. Microsoft.Extensions.Configuration.FileExtensions

   

   Figure 4.18: Installing NuGet packages using Visual Studio 2022

Reviewing project packages

Unit testing

Understanding types of testing

Creating a class library that needs testing

Writing unit tests

• Arrange: This part will declare and instantiate variables for input and output.
• Act: This part will execute the unit that you are testing. In our case, that means calling the method that we want to test.
• Assert: This part will make one or more assertions about the output. An assertion is a belief that, if not true, indicates a failed test. For example, when adding 2 and 2, we would expect the result to be 4.

Now, we will write some unit tests for the Calculator class:

1. Rename the file UnitTest1.cs to CalculatorUnitTests.cs and then open it.
2. In Visual Studio Code, rename the class to CalculatorUnitTests. (Visual Studio prompts you to rename the class when you rename the file.)
3. Import the Packt namespace.
4. Modify the CalculatorUnitTests class to have two test methods for adding 2 and 2, and adding 2 and 3, as shown in the following code:

   using Packt; 
   using Xunit;
   namespace CalculatorLibUnitTests
   {
     public class CalculatorUnitTests
     {
       [Fact]
       public void TestAdding2And2()
       {
         // arrange 
         double a = 2; 
         double b = 2;
         double expected = 4;
         Calculator calc = new();
         // act
         double actual = calc.Add(a, b);
         // assert
         Assert.Equal(expected, actual);
       }
       [Fact]
       public void TestAdding2And3()
       {
         // arrange 
         double a = 2; 
         double b = 3;
         double expected = 5;
         Calculator calc = new();
         // act
         double actual = calc.Add(a, b);
         // assert
         Assert.Equal(expected, actual);
       }
     }
   }
   

Running unit tests using Visual Studio Code

1. In the CalculatorLibUnitTest project's TERMINAL window, run the tests, as shown in the following command:

   dotnet test
   

2. Note that the results indicate that two tests ran, one test passed, and one test failed, as shown in Figure 4.21:

   

   Figure 4.21: The unit test results in Visual Studio Code's TERMINAL

Running unit tests using Visual Studio

1. Navigate to Test | Run All Tests.
2. In Test Explorer, note that the results indicate that two tests ran, one test passed, and one test failed, as shown in Figure 4.22:

   

Figure 4.22: The unit test results in Visual Studio 2022's Test Explorer

Fix the bug

Now you can fix the bug:

1. Fix the bug in the Add method.
2. Run the unit tests again to see that the bug has now been fixed and both tests pass.

Throwing and catching exceptions in functions

Understanding usage errors and execution errors

Commonly thrown exceptions in functions

When defining your own functions with parameters, your code should check the parameter values and throw exceptions if they have values that will prevent your function from properly functioning.

For example, if a parameter should not be null, throw ArgumentNullException. For other problems, throw ArgumentException, NotSupportedException, or InvalidOperationException. For any exception, include a message that describes the problem for whoever will have to read it (typically a developer audience for class libraries and functions, or end users if it is at the highest level of a GUI app), as shown in the following code:

static void Withdraw(string accountName, decimal amount)
{
  if (accountName is null)
  {
    throw new ArgumentNullException(paramName: nameof(accountName));
  }
  if (amount < 0)
  {
    throw new ArgumentException(
      message: $"{nameof(amount)} cannot be less than zero.");
  }
  // process parameters
}

Understanding the call stack

The Main method will call other methods, that call other methods, and so on, and these methods could be in the current project or in referenced projects and NuGet packages, as shown in Figure 4.23:

Figure 4.23: A chain of method calls that create a call stack

Note the following:

Where to catch exceptions

Rethrowing exceptions

1. To throw the caught exception with its original call stack, call throw.
2. To throw the caught exception as if it was thrown at the current level in the call stack, call throw with the caught exception, for example, throw ex. This is usually poor practice because you have lost some potentially useful information for debugging.
3. To wrap the caught exception in another exception that can include more information in a message that might help the caller understand the problem, throw a new exception and pass the caught exception as the innerException parameter.

try
{
  Gamma();
}
catch (IOException ex)
{
  LogException(ex);
  // throw the caught exception as if it happened here
  // this will lose the original call stack
  throw ex;
  // rethrow the caught exception and retain its original call stack
  throw;
  // throw a new exception with the caught exception nested within it
  throw new InvalidOperationException(
    message: "Calculation had invalid values. See inner exception for why.",
    innerException: ex);
}

Let's see this in action with our call stack example:

Implementing the tester-doer pattern

.NET implements this pattern itself. For example, before adding an item to a collection by calling the Add method, you can test to see if it is read-only, which would cause Add to fail and therefore throw an exception.

For example, before withdrawing money from a bank account, you might test that the account is not overdrawn, as shown in the following code:

if (!bankAccount.IsOverdrawn())
{
  bankAccount.Withdraw(amount);
}

Problems with the tester-doer pattern

Another problem with the tester-doer pattern occurs when you are using multiple threads. In this scenario, one thread could call the test function and it returns okay. But then another thread executes that changes the state. Then the original thread continues executing assuming everything is fine, but it is not fine. This is called a race condition. We will see how we could handle it in Chapter 12, Improving Performance and Scalability Using Multitasking.

If you implement your own try pattern function and it fails, remember to set the out parameter to the default value of its type and then return false, as shown in the following code:

static bool TryParse(string? input, out Person value)
{
  if (someFailure)
  {
    value = default(Person);
    return false;
  }
  // successfully parsed the string into a Person
  value = new Person() { ... };
  return true;
}

Practicing and exploring

Test your knowledge and understanding by answering some questions, get some hands-on practice, and explore with deeper research into the topics covered in this chapter.

Exercise 4.1 – Test your knowledge

Answer the following questions. If you get stuck, try Googling the answers if necessary, while remembering that if you get totally stuck, the answers are in the Appendix:

1. What does the C# keyword void mean?
2. What are some differences between imperative and functional programming styles?
3. In Visual Studio Code or Visual Studio, what is the difference between pressing F5, Ctrl or Cmd + F5, Shift + F5, and Ctrl or Cmd + Shift + F5?
4. Where does the Trace.WriteLine method write its output to?
5. What are the five trace levels?
6. What is the difference between the Debug and Trace classes?
7. When writing a unit test, what are the three "A"s?
8. When writing a unit test using xUnit, what attribute must you decorate the test methods with?
9. What dotnet command executes xUnit tests?
10. What statement should you use to rethrow a caught exception named ex without losing the stack trace?

Exercise 4.2 – Practice writing functions with debugging and unit testing

Prime factors are the combination of the smallest prime numbers that, when multiplied together, will produce the original number. Consider the following example:

• Prime factors of 4 are: 2 x 2
• Prime factors of 7 are: 7
• Prime factors of 30 are: 5 x 3 x 2
• Prime factors of 40 are: 5 x 2 x 2 x 2
• Prime factors of 50 are: 5 x 5 x 2

Create a workspace/solution named PrimeFactors to contain three projects: a class library with a method named PrimeFactors that, when passed an int variable as a parameter, returns a string showing its prime factors; a unit tests project; and a console application to use it.

To keep it simple, you can assume that the largest number entered will be 1,000.

Use the debugging tools and write unit tests to ensure that your function works correctly with multiple inputs and returns the correct output.

Exercise 4.3 – Explore topics

Use the links on the following page to learn more detail about the topics covered in this chapter: