NullReferenceException is one of the most common and frustrating runtime errors that .NET developers encounter. If you’ve ever seen the message “Object reference not set to an instance of an object,” you’ve experienced this exception firsthand. This comprehensive guide will walk you through everything you need to know about NullReferenceException, from understanding what causes it to implementing robust prevention strategies.

What is NullReferenceException?

A NullReferenceException (often abbreviated as NRE) occurs when your program attempts to access a member (such as a method or property) on a reference variable that currently holds a null reference. In simple terms, you’re trying to use something that doesn’t exist – like asking someone who isn’t there to do something for you.

In .NET, reference types (such as classes, strings, and arrays) store references to objects in memory rather than the actual values. When a reference variable doesn’t point to any object, it contains a null value. The null reference serves as a way to indicate that a variable has no meaningful value or that an object is absent.

When you attempt to dereference a null reference by accessing its members using the dot operator (.), the .NET runtime throws a NullReferenceException.

Common Causes of NullReferenceException

Understanding the root causes of null reference errors is essential for effective debugging and prevention. Here are the most frequent scenarios that lead to NullReferenceException:

1. Uninitialized Object Variables

The most basic cause occurs when you declare a reference variable but forget to initialize it with an actual object:

string message = null;
int length = message.Length; // Throws NullReferenceException

2. Uninitialized Class Fields

Class fields of reference types default to null if not explicitly initialized:

public class Person
{
    private string _name; // Defaults to null
    
    public void DisplayName()
    {
        Console.WriteLine(_name.Length); // NullReferenceException
    }
} 

3. Method Returning Null

When methods return null values and you don’t check before using the result:

public Person FindPerson(int id)
{
    // Returns null if person not found
    return database.FirstOrDefault(p => p.Id == id);
}

var person = FindPerson(123);
Console.WriteLine(person.Name); // Potential NullReferenceException

4. Method Chaining with Null Values

Method chaining becomes dangerous when any link in the chain returns null:

var street = service.GetUser().Address.Street; // Any part could be null

5. Array Elements Containing Null

Arrays can contain null elements, leading to exceptions during iteration:

string[] names = { "Alice", null, "Bob" };
foreach (var name in names)
{
    Console.WriteLine(name.Length); // Throws exception on null element
} 

6. Forgetting Component Assignment (Unity Development)

In Unity development, a common cause is forgetting to assign components in the Inspector:

public class PlayerController : MonoBehaviour
{
    public Transform playerTransform; // Not assigned in Inspector
    
    void Start()
    {
        playerTransform.position = Vector3.zero; // NullReferenceException
    }
} 

How to Fix NullReferenceException

Fixing null reference errors requires systematic debugging and proper null handling. Here’s a step-by-step approach to resolve these issues:

1. Identify the Exact Location

The exception message typically indicates the exact line and method where the error occurred:

NullReferenceException: Object reference not set to an instance of an object
at Example.Start() [0x0000b] in /Unity/projects/nre/Assets/Example.cs:10 

This tells you that line 10 in the Example.cs file is where the problem occurs.

2. Use Debugging Tools

Modern IDEs like Visual Studio provide powerful debugging capabilities:

• Set breakpoints before the problematic line
• Use the debugger to inspect variable values
• Leverage Null Reference Analysis in Visual Studio to identify which specific object is null

3. Implement Null Checks

The most straightforward fix is adding explicit null checks:

public void DisplayUserName(User user)
{
    if (user != null)
    {
        Console.WriteLine(user.Name);
    }
    else
    {
        Console.WriteLine("User is null");
    }
} 

4. Use Safe Navigation Patterns

C# 6.0 introduced null-conditional operators that provide elegant solutions for null safety:

// Using null-conditional operator (?.)
var userName = user?.Name;

// Chaining null-conditional operators
var street = user?.Address?.Street;

// Null-conditional with indexer
var firstItem = collection?[0]; 

5. Provide Default Values

Use the null-coalescing operator (??) to provide fallback values:

string displayName = user?.Name ?? "Unknown User";
var items = collection ?? new List<string>(); 

Advanced Debugging Techniques

1. Using Debug.Assert for Development

Debug.Assert helps catch null references early during development:

public void ProcessUser(User user)
{
    Debug.Assert(user != null, "User should not be null");
    // Process user safely
} 

2. Exception Handling with Try-Catch

While not recommended as a primary solution, try-catch blocks can handle unexpected null references:

try
{
    var result = service.GetData().ProcessValue();
}
catch (NullReferenceException ex)
{
    Logger.LogError("Unexpected null reference: " + ex.Message);
    // Handle gracefully
} 

3. Using Nullable Reference Types

C# 8.0 introduced nullable reference types that help identify potential null reference issues at compile time:

#nullable enable

public class User
{
    public string Name { get; set; } = string.Empty; // Non-nullable
    public string? Email { get; set; } // Nullable
} 

Ways to Prevent NullReferenceException

Prevention is always better than fixing null reference errors after they occur. Here are proven strategies to avoid NullReferenceException:

1. Defensive Programming

Always assume that references might be null and implement appropriate checks:

public decimal CalculateTotal(Order order)
{
    if (order == null)
        throw new ArgumentNullException(nameof(order));
    
    if (order.Items == null)
        return 0;
    
    return order.Items.Sum(item => item?.Price ?? 0);
} 

2. Initialize Variables Properly

Ensure all reference variables are initialized when declared:

public class ShoppingCart
{
    public List<Item> Items { get; set; } = new List<Item>(); // Initialize immediately
    
    public ShoppingCart()
    {
        // Constructor ensures proper initialization
        Items = new List<Item>();
    }
} 

3. Use Constructor Injection

Dependency injection makes dependencies explicit and ensures they’re not null:

public class OrderService
{
    private readonly IRepository _repository;
    
    public OrderService(IRepository repository)
    {
        _repository = repository ?? throw new ArgumentNullException(nameof(repository));
    }
} 

4. Implement Null Object Pattern

Create default objects instead of returning null:

public class NullUser : IUser
{
    public string Name => "Guest";
    public bool IsValid => false;
}

public IUser GetUser(int id)
{
    var user = database.Find(id);
    return user ?? new NullUser(); // Never return null
} 

5. Use Guard Clauses

Implement guard clauses at the beginning of methods:

public void ProcessOrder(Order order)
{
    if (order == null) return; // Early exit
    if (order.Items == null) return;
    
    // Safe to proceed
    foreach (var item in order.Items)
    {
        ProcessItem(item);
    }
} 

6. Enable Nullable Reference Types

Configure your project to use nullable reference types for compile-time null safety:

<PropertyGroup>
    <Nullable>enable</Nullable>
</PropertyGroup> 

7. Use Modern C# Features

Leverage pattern matching and other modern C# features for null safety:

// Pattern matching with null checks
if (user is { Name: not null } validUser)
{
    Console.WriteLine(validUser.Name);
}

// Null-coalescing assignment (C# 8.0)
name ??= "Default Name"; 

Debugging Tools and Techniques

1. Visual Studio Debugging Features

Visual Studio provides excellent tools for debugging null reference exceptions:

• Exception Helper shows detailed information about the exception
• Null Reference Analysis identifies which object is null
• IntelliCode suggestions help prevent common null reference patterns

2. Unity-Specific Debugging

For Unity developers, additional considerations include:

• Use Unity’s Console to track null references in game objects
• Leverage Unity’s Inspector to ensure component assignments
• Implement null checks in MonoBehaviour lifecycle methods

3. Logging and Monitoring

Implement comprehensive logging to track null reference issues in production:

public User GetUser(int id)
{
    try
    {
        var user = _repository.FindUser(id);
        if (user == null)
        {
            _logger.LogWarning($"User with ID {id} not found");
            return null;
        }
        return user;
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, $"Error retrieving user {id}");
        throw ;
    }
} 

Best Practices Summary

To effectively handle null reference exceptions, follow these best practices:

1. Enable nullable reference types in new projects
2. Initialize variables immediately when possible
3. Use null-conditional operators (?.) for safe member access
4. Implement guard clauses at method entry points
5. Prefer exceptions over null returns when appropriate
6. Use dependency injection to manage object lifecycles
7. Write unit tests that cover null scenarios
8. Document null behavior in method contracts

Conclusion

NullReferenceException may be one of the most common errors in .NET development, but it’s entirely preventable with proper techniques and awareness. By understanding what causes null reference errors, implementing robust debugging strategies, and following prevention best practices, you can significantly reduce these exceptions in your applications.

The key to mastering null safety lies in adopting a defensive programming mindset, leveraging modern C# features like nullable reference types and null-conditional operators, and implementing comprehensive null checking throughout your codebase. Remember that preventing null references is always more efficient and reliable than handling them after they occur.

With the techniques and strategies outlined in this guide, you’ll be well-equipped to write more robust, error-free C# applications that gracefully handle null scenarios without compromising functionality or user experience.

Frequently Asked Questions (FAQs)

What does “Object reference not set to an instance of an object” mean?

This error message indicates that you’re trying to use a reference variable that contains null instead of pointing to an actual object. The variable exists, but it doesn’t reference any object in memory.

How do I find which object is null in a method chain?

Break down the method chain into separate lines or use Visual Studio’s Null Reference Analysis feature. You can also use the null-conditional operator (?.) to safely navigate the chain.

Can NullReferenceException be caught and handled?

Yes, you can catch NullReferenceException using try-catch blocks, but this is generally not recommended as a primary solution. It’s better to prevent the exception through proper null checking.

What’s the difference between null-conditional operator and null-coalescing operator?

The null-conditional operator (?.) safely accesses members if the object is not null, while the null-coalescing operator (??) provides a default value when the object is null.

How do nullable reference types help prevent NullReferenceException?

Nullable reference types enable compile-time analysis that warns you about potential null reference issues before your code runs, allowing you to fix problems during development rather than at runtime.

Should I use try-catch to handle all NullReferenceException?

No, try-catch should not be your primary strategy. NullReferenceException typically indicates a programming error that should be fixed through proper null checking and defensive programming practices.

C# .NET Core provides a robust platform for building applications that interact with Excel files making it easy to read Excel sheet’s cell value of any column type. Open XML is an open standard file format for office applications, maintained by the International Organization for Standardization (ISO). It is the default file format for Microsoft Office documents, including Excel (.xlsx) files. Open XML provides a structured way to represent document content, making it possible to interact with the various elements within an Office document programmatically. In this article, we will understand the process of reading Excel cell values using Open XML in a C# .NET Core application.

Step-by-step Guide to Read Excel Spreadsheet Cell Values from OpenXML in C#

For demonstration purposes, we’re going to use a Web API to upload an Excel file. So before we begin, let’s ensure that you have a C# .NET Core project set up. Then, we’ll use the OpenXML package to read Excel sheet & its values in each cell and store them in a DataTable.

Install OpenXml SDK Nuget Package

Install an OpenXML Nuget Package into the Web API project, using either:

Or

PM> Install-Package DocumentFormat.OpenXml -Version 3.0.0

After you install the package, you can include these assembly directives to use OpenXML, in the ‘Controller.cs’ class.

using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Spreadsheet;

Create API to get an Excel file

Create an HTTP POST method in the controller class to receive the uploaded file from the API.

[HttpPost("UploadExcelFile")]
public IActionResult UploadExcelSheet(IFormFile uploadRegistration)
{
	string fileName = uploadRegistration.FileName;

	DataTable dt = ConvertExcelToDataTable(uploadRegistration);

	// write your logic,
	// example insert DataTable result into Database

	return Ok();
}

The API takes IFormFile as a parameter, representing a file sent with the HttpRequest.

Read Data from Excel Sheet using OpenXML – C#

private DataTable ConvertExcelToDataTable(IFormFile uploadRegistration)
{
	//Create a new DataTable.
	DataTable dt = new DataTable();
	dt.Columns.Add("FIRST_NAME", typeof(string));
	dt.Columns.Add("LAST_NAME", typeof(string));
	dt.Columns.Add("PHONE_NUMBER", typeof(int));
	dt.Columns.Add("EMAIL", typeof(string));
	dt.Columns.Add("ADDRESS", typeof(string));

	using (SpreadsheetDocument doc = SpreadsheetDocument.Open(uploadRegistration.OpenReadStream(), false))
	{
		//Read the first Sheet from Excel file.
		Sheet sheet = doc.WorkbookPart.Workbook.Sheets.GetFirstChild<Sheet>();

		//Get the Worksheet instance.
		Worksheet worksheet = (doc.WorkbookPart.GetPartById(sheet.Id.Value) as WorksheetPart).Worksheet;

		//Fetch all the rows present in the Worksheet.
		IEnumerable<Row> rows = worksheet.GetFirstChild<SheetData>().Descendants<Row>();

		//Loop through the Worksheet rows.
		foreach (Row row in rows)
		{
			//If first row is header and you want to use same excel header name in Database column.
			if (row.RowIndex.Value == 1)
			{
				//foreach (Cell cell in row.Descendants<Cell>())
				//{
				//    dt.Columns.Add(GetCellValue(doc, cell));
				//}
			}
			else
			{
				string firstName = GetCellValue(doc, (Cell)row.ElementAt(0));
				string lastName = GetCellValue(doc, (Cell)row.ElementAt(1));

				DataRow dataRow = dt.NewRow();

				// Validate if empty
				if (!string.IsNullOrEmpty(firstName))
				{
					dataRow["FIRST_NAME"] = firstName.Trim();
				}

				if (!string.IsNullOrEmpty(lastName))
				{
					dataRow["LAST_NAME"] = lastName.Trim();
				}

				dataRow["PHONE_NUMBER"] = GetCellValue(doc, (Cell)row.ElementAt(2)).Trim();

				dataRow["EMAIL"] = GetCellValue(doc, (Cell)row.ElementAt(3)).Trim();

				dataRow["ADDRESS"] = GetCellValue(doc, (Cell)row.ElementAt(4)).Trim();

				dt.Rows.Add(dataRow);
			}
		}

	}

	return dt;
}


private string GetCellValue(SpreadsheetDocument doc, Cell cell)
{
	if (cell.CellValue != null)
	{
		string value = cell.CellValue.InnerText;
		if (cell.DataType != null && cell.DataType.Value == CellValues.SharedString)
		{
			// in older version e.g. 2.0, you can use GetItem instead of ElementAt
			return doc.WorkbookPart.SharedStringTablePart.SharedStringTable.ChildElements.ElementAt(int.Parse(value)).InnerText;
		}
		else
		{
			return value;
		}
	}
	return string.Empty;
}

1. We open the Excel file (RegistrationFormTest.xlsx in this case) using the SpreadsheetDocument.Open method.
2. We obtain the WorkbookPart and identify the first sheet in the workbook.
3. For each row in the sheet, we iterate through the cells, using the GetCellValue method to retrieve the cell value.
4. The GetCellValue method takes care of differentiating between shared string values and other types of cell values. It reads Excel Sheet cell value and stores the result in the DataTable.

also read: How to Export DataSet To Excel in C# .Net Core – OpenXml

Testing – Upload & Read Excel file

Let’s consider an example. I have a basic Excel file with the column and row information. Now, let’s attempt to upload and read the file using API, as shown in the screenshots below.

Screenshots:

In this example, we demonstrate how to read Excel spreadsheet cell values and add results to the DataTable. However, you also have the option to save all records to a database. This can be done either through bulk insert or by saving each row individually, passing the values of each row via the property object.

.NET provides a hierarchy of built-in exception classes that are derived from the fundamental Exception base class. However, there may be times when none of the predefined exceptions meet your specific needs or requirements. In such case, you can create your own exception classes by deriving from the Exception class. In this article, we will discuss how to create custom exceptions in .Net Core using ExceptionFilterAttribute and implementing a global exception-handling mechanism in the Web API .Net Core application.

What is ExceptionFilterAttribute?

In .NET Core, ExceptionFilterAttribute is a class that allows developers to create custom exception filters. Exception filters are used to handle exceptions that occur during the execution of ASP.NET Core MVC or Web API actions. These filters can be applied globally to all actions or selectively to specific controllers or actions. When an exception is thrown, an ExceptionFilterAttribute can catch it, perform custom logic (such as logging or generating a specific response), and potentially prevent the exception from propagating to the higher levels of the application. This helps in creating more robust and user-friendly error handling mechanisms in .NET Core applications. In other words, ExceptionFilterAttribute is an attribute used to define exception filters in ASP.NET Web API.

Create an Exception Filter class and override the OnException Method

The implementation for creating a custom Exception Filter is done in the following 3 simple steps.

Step 1: Create Custom Exception Class

To address unhandled exception scenarios, you can create a custom exception filter by defining a class that inherits the ExceptionFilterAttribute abstract class which implements the IExceptionFilter interface internally. In our example, we have given the class name as CustomExceptionAttribute.
Note: End the class name with Arrtibute.

Custom Exception Filter Class

using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.Extensions.Logging;

namespace Product.Web
{
    public class CustomExceptionAttribute : ExceptionFilterAttribute
    {
        private readonly ILogger _logger;

        //constructor
        public CustomExceptionAttribute(ILogger logger)
        {
            _logger = logger;
        }


        // override the OnException Method
        public override void OnException(ExceptionContext ex)
        {
            var controllerActionDescriptor = ((Microsoft.AspNetCore.Mvc.Controllers.ControllerActionDescriptor)ex.ActionDescriptor);

            _logger.LogError("API: " + controllerActionDescriptor.AttributeRouteInfo.Template + "\r\n"
                    + ex.Exception.Message + "\r\n"
                    + ex.Exception.ToString());

            //assigning custom response
            ex.Result = JsonResultDto();

            ex.HttpContext.Response.StatusCode = 400;  
        }


        // override the OnException async Method 
        public override async Task OnExceptionAsync(ExceptionContext ex)
        {
            var controllerActionDescriptor = ((Microsoft.AspNetCore.Mvc.Controllers.ControllerActionDescriptor)ex.ActionDescriptor);
                
            _logger.LogError("API: " + controllerActionDescriptor.AttributeRouteInfo.Template + "\r\n"
                    + ex.Exception.Message + "\r\n"
                    + ex.Exception.ToString());

            await Task.FromResult(0);

            //assigning custom response
            ex.Result = JsonResultDto();

            ex.HttpContext.Response.StatusCode = 400;
        }

        // returning custom Json response
        private JsonResult JsonResultDto()
        {
            return new JsonResult(
                new
                {
                    ErrorMessage = "Internal error occurred.",
                    HasError = true,
                    ResponseCode = 400
                });

        }
    }
} 

In the above code, we have overridden two OnException methods (one for normal and another for async methods). If any exception occurs while executing an API method (or in its internal sub-methods) then the code will hit the custom exception filter class. The OnException method will be invoked depending on whether the call is synchronous or asynchronous.
Here, we are using the ILogger interface to log the error details such as:
1) API Path,
2) Exception message,
3) full error stack trace.

The benefit of an Exception Filter is we can return a user-friendly error message to the front-end application in the response body. In the example, after logging the error, the JsonResultDto() method is called which will return the user-defined Json result to the user.

Step 2: Registering Exception Filter

We need to define the scope and register the custom exception filter globally, inside the ConfigureServices method in the startup.cs file.

Add services.AddScoped<CustomExceptionAttribute>(); line of code as shown below:

public class Startup
{
	public void ConfigureServices(IServiceCollection services)
	{
		//...
		//services.AddControllers();
		//...
		
		//register CustomExceptionAttribute class
		services.AddScoped<CustomExceptionAttribute>();
	}
} 

Step 3: Apply Exception Filter on Controller or Action methods

To use a registered filter, it should be placed or decorated at the top of the Controller or Action as a ServiceType.

You can apply the Exception Filter at:
1) Controller Level, or
2) Action Level (one or more based on your requirement).

The example shows custom exception filter is applied at the Controller level, which means it is applicable to all API methods as well.
The GetProducts() method will throw System.FormatException error when code tries to convert a string variable (object) to an integer.

Add [ServiceFilter(typeof(CustomExceptionAttribute))] line of code above the Controller class, as shown below:

namespace Product.Web
{
    [ServiceFilter(typeof(CustomExceptionAttribute))]
    [ApiController]
    [Route("[controller]")]
    public class ProductController
    {
	
        [HttpGet]
        [Route("GetProducts")]
        public IActionResult GetProducts()
        {
            //example: System.FormatException: 'Input string was not in a correct format.'
            object input = "test";
            int result = Convert.ToInt32(input);

            return Ok();
        }
	}
} 

Testing ExceptionFilterAttribute – Screenshots

That’s it, now we can do a unit test and confirm if it is working as expected.

Swagger API Test

Call & execute API method from Swagger. It will return “400 – Bad Request” with a user-friendly JSON message in the response body, as shown in the below screenshot.

Debug code

The custom exception class will be called whenever an error occurs in the Controller’s Web API method and it will capture & log the following details:
1) on which API error occurred e.g., Path: “Product/GetProducts”
2) error message e.g., “Input string was not in a correct format.”
3) full stack trace

see the debugging screenshot below.

We will understand the difference between ExceptionLogger, ExceptionFilter, and ExceptionHandler which helps to handle exceptions in several ways in .NET Core. In this article, we will explore each of these techniques, discussing when and how to use them with real-world examples.

Difference – Overview

ExceptionLogger

ExceptionLogger allows you to log exceptions that occur during the execution of your application. It provides a way to capture detailed information about exceptions, such as the exception message, stack trace, and other relevant data, and then log this information using a custom logging mechanism.

ExceptionLogger is typically used for auditing and monitoring purposes. It helps developers and administrators track the occurrence of exceptions in an application, enabling them to diagnose issues, identify error patterns, and take corrective actions.

When to use ExceptionLogger:

You might use an ExceptionLogger to log exceptions to a central log database or send alerts to a monitoring system like Application Insights or ELK Stack.
Use ExceptionLogger when you want to log exceptions that occur during the execution of your application. ExceptionLogger allows you to capture detailed information about exceptions, including the exception message, stack trace, and other relevant data.

Purpose: all unhandled exceptions (before they even reach exception filters)
Scope: global

public class CustomExceptionLogger : ExceptionLogger
{
    public override void Log(ExceptionLoggerContext context)
    {
        // Log the exception details using your preferred logging mechanism
        LogHelper.LogException(context.Exception);
    }
}

In this example, we create a custom ExceptionLogger that logs exceptions using a custom logging utility. You can then register this logger in your application’s configuration to handle exception logging.

ExceptionFilter

ExceptionFilter allows you to perform custom actions in response to specific exceptions during the execution of your application. It lets you modify the HTTP response, redirect the user, or execute any other logic based on the exception type or conditions you define.

ExceptionFilters are useful when you need to handle exceptions in a more fine-grained manner. You can use them to implement custom error handling behavior for specific scenarios. For example, you might want to return a user-friendly error message for a particular exception type or redirect the user to a login page if their session has expired.

When to use ExceptionFilter:

You can create an ExceptionFilter to catch and handle authorization-related exceptions by redirecting the user to a login page or returning a 403 Forbidden status code.
ExceptionFilters are useful when you need to perform custom actions in response to specific exceptions. They allow you to modify the HTTP response, redirect the user, or perform any other action based on the exception type or condition.

Purpose: handle (not log) exceptions
Scope: per action, per controller, global

public class CustomExceptionFilter : IExceptionFilter
{
    public void OnException(ExceptionContext context)
    {
        if (context.Exception is CustomNotFoundException)
        {
            // Handle the not found exception by returning a custom response
            context.Result = new NotFoundObjectResult("Resource not found");
            context.ExceptionHandled = true;
        }
    }
}

In this example, a CustomExceptionFilter is used to catch a specific CustomNotFoundException and return a custom response. You can register this filter globally or on specific controllers or action methods as needed.

ExceptionHandler

ExceptionHandler deals with unhandled exceptions that occur during the execution of your application. It provides a way to customize the behavior when an unhandled exception is encountered, such as redirecting the user to an error page, returning a specific response, or performing cleanup tasks.

ExceptionHandler is designed to handle exceptions that propagate beyond the scope of regular exception handling mechanisms like try-catch blocks. It ensures that your application gracefully manages unhandled exceptions, preventing crashes and providing a more user-friendly experience.

When to use ExceptionHandler:

You can configure an ExceptionHandler to catch unhandled exceptions and return a custom error response with a 500 Internal Server Error status code. This helps ensure that users receive a meaningful error message rather than seeing a generic server error page.
ExceptionHandler is suitable for handling unhandled exceptions that occur during the execution of your application. It allows you to customize the behavior when an unhandled exception occurs, such as redirecting the user to an error page or returning a specific response.

Purpose: log and handle unpredictable/unexpected exceptions
Scope: global

public class CustomExceptionHandler : IExceptionHandler
{
    public Task HandleAsync(ExceptionHandlerContext context, CancellationToken cancellationToken)
    {
        // Handle the exception and return a custom response
        context.Result = new ObjectResult("An error occurred")
        {
            StatusCode = StatusCodes.Status500InternalServerError
        };
        return Task.CompletedTask;
    }
}

In this example, a CustomExceptionHandler is used to catch unhandled exceptions and return a custom response with a 500 Internal Server Error status code. You can configure the ExceptionHandler in your application’s startup code to define how unhandled exceptions should be handled.

Conclusion
Exception handling is a crucial part of any application’s development, and in .NET Core, you have several options to tailor your approach to your specific needs. ExceptionLogger, ExceptionFilter, and ExceptionHandler each serve distinct purposes, allowing you to log, filter, and handle exceptions effectively.

reference: web-api-global-error-handling

To validate a JSON Web Token (JWT) issued by Azure Active Directory B2C (Azure AD B2C) in a .NET Core Web API, you need to configure the authentication middleware to validate the JWT tokens.

Steps to Validate Azure AD B2C Jwt Bearer

Create Web API project in .NET Core

Install Required NuGet Packages

Install the necessary JwtBearer NuGet packages to work with JWT authentication and Azure AD B2C.

Configure Azure B2C JWT Authentication.

In your Startup.cs file, configure JWT authentication in the ConfigureServices and Configure methods:

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using System.Text;

// ...

public void ConfigureServices(IServiceCollection services)
{
	// Add authentication services
    services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
        .AddJwtBearer(options =>
        {
			options.Authority = "AzureAdB2C:IssuerOrAuthorizationUrl";
			options.Audience = "AzureAdB2C:Audience";
			options.Events = new JwtBearerEvents
			{
				//OnAuthenticationFailed = AuthenticationFailed
			};
			
			/* Note:Authority and audience are enough to validate AD B2C Authentication but if your requirement is to validate the Token issuer & SigninKey also then include the below code as well.*/
            options.TokenValidationParameters = new TokenValidationParameters
            {
                ValidateIssuer = true,
                ValidateAudience = true,
                //ValidateLifetime = true,
                ValidateIssuerSigningKey = true,
                ValidIssuer = "AzureAdB2C:IssuerOrAuthorizationUrl",
                ValidAudience = "AzureAdB2C:Audience",
                IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(Configuration["AzureAdB2C:JwtKey"]))
            };
        });

    // Other ConfigureServices configuration...
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // Use authentication middleware
    app.UseAuthentication();

    // Other Configure configuration...
} 

{
  "AzureAdB2C": {
    "IssuerOrAuthorizationUrl": "https://<your-tenant-name>.b2clogin.com/<your-tenant-name>.onmicrosoft.com/<your-policy-name>/v2.0/",
    "Audience": "ecjud59-Your-ClientId-or-AudienceId-e0d02e",
    "JwtKey": "my_secret_key_12345"
  }
}

Authorize API Endpoints

You can now protect your API endpoints by applying the [Authorize] attribute to the controllers or actions you want to secure:

using Microsoft.AspNetCore.Authorization;

[Authorize]
[ApiController]
[Route("api/[controller]")]
public class MyController : ControllerBase
{
    // Controller actions...
}

Your .NET Core rest API is now configured to validate JWT tokens issued by Azure AD B2C.

Testing Azure AD B2C Jwt Bearer

To test the JWT Bearer token authentication, include the JWT token in the Authorization header of your HTTP requests. The header should look like:

Authorization: Bearer <your-JWT-token>

If validation is successful then it will execute the API method else app will throw an exception.

Make sure you have the correct Azure AD B2C configuration values in your application, and ensure that your B2C policies and user flows are set up to issue tokens with the required audience and issuer values.

Handle Claims: You can access user claims (e.g., user’s email, name, etc.) using User.Claims within your API controller actions.

Swagger is a powerful tool for documenting and testing APIs in a user-friendly and interactive way. It allows developers to create interactive API documentation, making it easier for both developers and consumers to understand and interact with the API. While there are tools and packages that automate Swagger integration in .NET Core, sometimes you may want to implement it manually for more control over the configuration and customization. In this article, we will guide you through the manual implementation of Swagger in a .NET Core application.

Swagger implementation in .NET Core Web API Project

The following steps describe the configuration of Swagger docs in the Web API project.

Step 1: Install Required Packages

To begin, open your .NET Core project in Visual Studio or Visual Studio Code and install the necessary NuGet packages for Swagger integration. You need Swashbuckle.AspNetCore package. You can install these packages using the NuGet Package Manager or Package Manager Console:

option 1) Console Command

dotnet add package Swashbuckle.AspNetCore

Note: This command will add all packages available under Swashbuckle.AspNetCore.
Recommendation – Install only necessary packages from Nuget Manager

option 2) Nuget Package manager recommended

You can install only the required packages needed for Swagger Web API documentation from Nuget Package Manager

Step 2: Configure Swagger in Startup.cs

Open your project’s Startup.cs file, where you configure your application’s services and middleware. Add the following code to configure Swagger:

using Microsoft.OpenApi.Models;
using System;
using System.IO;
using System.Reflection;


public void ConfigureServices(IServiceCollection services)
{
	// ...

	services.AddSwaggerGen(swagger =>
	{
		//This is to generate the Default UI of Swagger Documentation  
		swagger.SwaggerDoc("v1", new OpenApiInfo
		{
			Version = "v1",
			Title = "My App",
			Description = "About Application"
		});

		// Set the comments path for the Swagger JSON and UI.
		var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
		var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
		swagger.IncludeXmlComments(xmlPath);                
	});
}


public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
	// ...

	// Enable middleware to serve generated Swagger as a JSON endpoint.
	app.UseSwagger();

	// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
	// specifying the Swagger JSON endpoint.
	app.UseSwaggerUI(c =>
	{
		c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name v1");
	});
} 

In the code above, you are configuring Swagger in the ConfigureServices and Configure methods of your Startup.cs file. Make sure to replace “Your API Name” with the actual name of your API.

Step 3: Define API Documentation

Now, let’s add documentation to your API endpoints. Decorate your controllers and actions with XML comments that Swagger will use to generate documentation. For example:

/// <summary>
/// This is a sample controller for managing products.
/// </summary>
[ApiController]
[Route("api/[controller]")]
public class WeatherForecastController : ControllerBase
{
    /// <summary>
    /// Gets a list of all WeatherForecast.
    /// </summary>
    /// <returns>A list of WeatherForecast.</returns>
    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        // Your action code here
    }
    // Add similar XML comments for other actions
} 

After adding descriptions to the APIs, go to the Swagger URL and check the documentation.

Step 4: Generate Swagger Documentation

With the configuration and documentation in place, you can now generate Swagger documentation by running your application. Build and run your .NET Core application, and navigate to URL https://localhost:<port>/swagger or https://localhost:<port>/swagger/index.html in your browser. You should see the Swagger UI, where you can interactively explore and test your API.

If you want to launch the Swagger URL by default then change the value of launchUrl in launchSettings.json file, See the screenshot below:

Troubleshooting

You might get System.IO.FileNotFoundException error – “Could not find file ‘filePath/appfilename.xml‘” as shown in the below screenshot.

XML comments file could not be found – Swagger

In such case, you can enable DocumentationFile property, manually. There are two ways to do it:

Option 1) Go to .csproj project file and add the GenerateDocumentationFile tag within PropertyGroup:

<PropertyGroup>
	<GenerateDocumentationFile>true</GenerateDocumentationFile> 
</PropertyGroup>

Option 2) If you want to avoid editing the .csproj manually then right-click on app >> click on Properties >> Select Build and tick XML documentation file checkbox under the output section. See the screenshot below:

It will add the DocumentationFile tag in PropertyGroup automatically.

Create Calendar Invite Content – C# code

1) Just “copy & paste” the below code and modify – Start & End meeting datetime, meeting link/ location, body content, subject text, sender & attendee email ids.

StringBuilder strInvite = new StringBuilder();

strInvite.AppendLine("BEGIN:VCALENDAR");
strInvite.AppendLine("PRODID:-//Microsoft Corporation//Outlook 12.0 MIMEDIR//EN");
strInvite.AppendLine("VERSION:2.0");
strInvite.AppendLine(string.Format("METHOD:{0}", (isCancel ? "CANCEL" : "REQUEST")));
strInvite.AppendLine("METHOD:REQUEST");
strInvite.AppendLine("BEGIN:VEVENT");

strInvite.AppendLine(string.Format("CREATED:{0:yyyyMMddTHHmmssZ}", DateTime.Now.ToUniversalTime()));

// Meeting Start DateTime
strInvite.AppendLine(string.Format("DTSTART:{0}", DateTime.Now.ToUniversalTime().ToString("yyyyMMddTHHmmssZ")));

strInvite.AppendLine(string.Format("DTSTAMP:{0:yyyyMMddTHHmmss}", DateTime.Now.ToUniversalTime()));

// Meeting End DateTime
strInvite.AppendLine(string.Format("DTEND:{0:}", DateTime.Now.AddHours(1).ToUniversalTime().ToString("yyyyMMddTHHmmssZ")));

strInvite.AppendLine(string.Format("LAST-MODIFIED:{0:yyyyMMddTHHmmssZ}", DateTime.Now.ToUniversalTime()));

// web meeting link
strInvite.AppendLine(string.Format("LOCATION: {0}", eventUrlLink));
//or
//strInvite.AppendLine(string.Format("LOCATION: {0}", eventLocationLink));

strInvite.AppendLine("PRIORITY: 5");
strInvite.AppendLine("SEQUENCE: 0");

strInvite.AppendLine(string.Format("UID:{0}", (eventID.HasValue ? "EventId" + eventID : Guid.NewGuid().Tostring())));

// meeting realted message body content
strInvite.AppendLine(string.Format("DESCRIPTION:{0}", strMessageBody.Replace("\n", "
")));
strInvite.AppendLine(string.Format("X-ALT-DESC;FMTTYPE=text/html:{0}", strMessageBody.Replace("\n", "
")));

// meeging subject text
strInvite.AppendLine(string.Format("SUMMARY:{0}", subjectText));
strInvite.AppendLine("STATUS:CONFIRMED"); 

// sender email id
strInvite.AppendLine(string.Format("ORGANIZER;CN={0}:MAILTO:{1}", strMailFrom, strMailFrom));

// attendee email ids for meeting
strInvite.AppendLine(string.Format("ATTENDEE;CN={0};RSVP=TRUE:mailto:{1}", string.Join(",", strAttendeeMailTo), string.Join(",", strAttendeeMailTo)));

strInvite.AppendLine("BEGIN:VALARM");
strInvite.AppendLine("TRIGGER:-PT15M");
strInvite.AppendLine("ACTION:DISPLAY");
strInvite.AppendLine("DESCRIPTION:Reminder");
strInvite.AppendLine("END:VALARM");
strInvite.AppendLine("END:VEVENT");
strInvite.AppendLine("END:VCALENDAR");

2) Attach created Calendar invite to mail as (.ics) attachment

// create instance of MailMessage object
MailMessage mailMessage = new MailMessage
{
	// fill normal mail body content
	From = new MailAddress(strMailFrom, strSenderName),
	Subject = strSubject,
	Body = strBodyContent,
	IsBodyHtml = true
};

// attach meeting request calendar invite .ics file
byte[] byteArray = Encoding.ASCII.GetBytes(strInvite);
MemoryStream stream = new MemoryStream(byteArray);
Attachment attach = new Attachment(stream, "event-meeting.ics");
mailMessage.Attachments.Add(attach);

// send mail
SmtpClient smtpClient = new SmtpClient
{
	// your credentials
};

smtpClient.Send(mailMessage);

Sending emails with attachments is a common task in many applications, whether it’s for sharing documents, images, or other files with recipients. In this article, we will explore how to send an email with a file attachment including inserting an image as a footer after the HTML body content, as well as creating a meeting invitation through ‘.ICS’ file attachment using C# code, making use of the built-in .NET framework classes.

The below screenshot shows a sample output generated through C# code which covers all the methods & logic required for sending an email via the SMTP server.

For sending emails, we need:

• Email settings (SMTP server, port number, sender email credentials, recipient email addresses).
• HTML Message/ body content.
• File for Attachment.
• File (Image) for adding logo in the footer section (using LinkedResource & AlternateView Classes).
• Calendar invitations (.ics) file for a meeting request or Calendar invite. (Calendar Appointment As Email Attachment)

Let’s start implementing sending-email functionality in the .Net project using C# code, step-by-step.

Set Up Your Project

First, create a new C# application project in your preferred development environment.

For demo purposes, we will implement this code in the Web API project. The folder and file structure of the solution project is shown below.

Configuring Email Settings

To send an email, you need a valid SMTP (Simple Mail Transfer Protocol) server address, a valid email address for the sender, and the recipient’s email address.

We will use Gmail as SMTP server in our example. Ensure you have access to this basic information before proceeding.

1) smtp server = "smtp.gmail.com";
2) port = 587; // Change if your SMTP server uses a different port
3) sender email e.g., "sender_email@gmail.com";
4) sender app password e.g., "sender_app_password";
5) recipient email e.g., "recipient@outlook.com"; 

Note:

Gmail Authentication is required for sending emails. Make sure you have enabled SSL security in your Gmail Settings so that application(code) can access your mailbox.
If the connection is not established through a secure channel (2-Step Verification) then you will get an authentication failed error message – “The SMTP server requires a secure connection or the client was not authenticated. The server response was: 5.5.1 Authentication Required.”

Sending Email With Content, Attachments & calendar invite – C# code

Next, we’ll create separate classes and methods that send an email with attachments. In this example, we’ll send a simple text email with a single attachment, footer logo image & meeting request(.ics file) but you can customize it to suit your needs.

Step 1: Create {get set} email property class

Create a property class (MailTemplateProperty.cs) that will serve and get all the essential details for sending an email, such as the SMTP server address, valid email addresses for both the sender and recipient, as well as any attachments such as files, footers, and calendar invite/appointment information.

public class MailTemplateProperty
{
	// "SMTP Configuration/Credential"
	public string SmtpClientHost { get; set; }
	public int SmtpClientPort { get; set; }
	public bool SmtpClientEnableSSL { get; set; }
	public string CredentialUserName { get; set; }
	public string CredentialPass { get; set; }

	// "Compose Email"
	public string SenderName { get; set; }
	public string MailFrom { get; set; }
	public string MailTo { get; set; }
	public string MailCC { get; set; }
	public string Subject { get; set; }
	public string Body { get; set; }


	/* ===== Optional Setting ===== */

	// "File attachments"
	public Attachment Attachment { get; set; } = null;

	// "Adding logo/image on footer"
	public string Footer { get; set; } = null;

	// Attach Calendar or meeting properties
	public string StartDateTime { get; set; }
	public string EndDateTime { get; set; }
	public string EventLink { get; set; }
	public string EventLocation { get; set; }
	public string Attendee { get; set; }
} 

Step 2: Create a Class & methods to send mail

It is a good practice to keep all email-sending related functionalities in a separate Class. We create a class called ‘Mail.cs‘ with a function called ‘Send()‘ inside. This function sends an email using the details you provide.

We need to implement all mail-related logic and code implementation in this class, such as:

a) File attachment

Use the Attachment Class from ‘System.Net.Mail’ Namespace. In this example, the code shows that you can pass a file as a parameter either by passing ‘file as MemoryStream with the name’ or mentioning the full physical path & name of the file.

b) Attaching Logo Image as footer note(inline)

We need to use LinkedResource & AlternateView Classes in the mail code to display embedded image(s) in the footer section. How to work with Alternate view – To add an alternate view to a MailMessage object, create an Attachment for the view, and then add it to the collection returned by AlternateViews. Use the Body property to specify the text version and use the AlternateViews collection to specify views with other MIME types.

c) Calendar Appointment As Email Attachment (.ics)

Calendar invitation or ‘. ics’ file is a calendar file saved in a universal calendar format used by several email and calendar programs, including Google Calendar, Microsoft Outlook, and Apple Calendar. It allows adding a calendar link in an email message and users to share the event information on the web and over email which will alert/ remind recipients prior to scheduled meeting time.

d) Common logic

• accepting mail body (plain text or HTML as string) and subject text
• Getting mandatory credential info so that mail can be sent without any failure

All of these functionalities & logic have been incorporated in the code provided below.

Mail.cs – full code – just copy & paste

Ensure you have added the necessary namespace for email functionality.

using System.Net;
using System.Net.Mail;
using System.Net.Mime;
using System.Text; 

public class Mail
{
	
// Main method for sending mail
	public static bool Send(MailTemplateProperty mailTemplate)
	{
		string meetingMessageBody = mailTemplate.Body;

		mailTemplate.MailFrom = mailTemplate.MailFrom.Trim(',').Trim(';');

		if (string.IsNullOrEmpty(mailTemplate.MailFrom))
			return false;
		try
		{
			MailMessage mailMessage = new MailMessage
			{
				From = new MailAddress(mailTemplate.MailFrom,
								string.IsNullOrEmpty(mailTemplate.SenderName) ? mailTemplate.MailFrom : mailTemplate.SenderName),
				Subject = mailTemplate.Subject,
				Body = mailTemplate.Body,
				IsBodyHtml = true
			};

			
// Adding File Attachment
			if (null != mailTemplate.Attachment)
				mailMessage.Attachments.Add(mailTemplate.Attachment);

// Adding To & CC email addresses, 
			mailTemplate.MailTo = mailTemplate.MailTo.Trim();
			mailMessage.To.Add(mailTemplate.MailTo);
			if (!string.IsNullOrEmpty(mailTemplate.MailCC) && mailTemplate.MailCC.Length > 0)
				mailMessage.CC.Add(mailTemplate.MailCC);

// Adding logo-Image as Footer
			if (mailTemplate.Footer != null)
			{
				LinkedResource res = new LinkedResource(mailTemplate.Footer)
				{
					ContentId = Guid.NewGuid().ToString()
				};
				mailTemplate.Body += @"<img src='cid:" + res.ContentId + @"'/>";
				AlternateView avHtml = AlternateView.CreateAlternateViewFromString(mailTemplate.Body, null, MediaTypeNames.Text.Html);
				avHtml.LinkedResources.Add(res);
				mailMessage.AlternateViews.Add(avHtml);
			}

// Adding Meeting Request
			byte[] byteArray = Encoding.ASCII.GetBytes(MeetingRequestString(mailTemplate.Subject, meetingMessageBody, mailTemplate));
			MemoryStream stream = new MemoryStream(byteArray);
			Attachment attach = new Attachment(stream, "event-meeting.ics");
			mailMessage.Attachments.Add(attach);

// Finally, sending mail via Gmail, SMTP client info with credentials.
			SmtpClient smtpClient = new SmtpClient
			{
				Host = mailTemplate.SmtpClientHost,
				Port = mailTemplate.SmtpClientPort,
				EnableSsl = mailTemplate.SmtpClientEnableSSL,
				Credentials = new NetworkCredential(mailTemplate.CredentialUserName, mailTemplate.CredentialPass),
			};

// Send mail by SMTP.
			smtpClient.Send(mailMessage);

			return true;
		}
		catch (SmtpFailedRecipientException ex)
		{
			// LogError(ex.ToString());
			return false;
			//throw new Exception();
		}
		catch (SmtpException ex)
		{
			// LogError(ex.ToString());
			return false;
			//throw new Exception();
		}
		catch (Exception ex)
		{
			// LogError(ex.ToString());
			return false;
			//throw new Exception();
		}
	}


// Email Meeting Request- ics meeting/ Calendar invite Code
// Attaching calendar appointment
	private static string MeetingRequestString(string subject, string messageBody, MailTemplateProperty mailTemplate, int? eventID = null, bool isCancel = false)
	{
		StringBuilder str = new StringBuilder();

		str.AppendLine("BEGIN:VCALENDAR");
		str.AppendLine("PRODID:-//Microsoft Corporation//Outlook 12.0 MIMEDIR//EN");
		str.AppendLine("VERSION:2.0");
		str.AppendLine(string.Format("METHOD:{0}", (isCancel ? "CANCEL" : "REQUEST")));
		str.AppendLine("METHOD:REQUEST");
		str.AppendLine("BEGIN:VEVENT");

		str.AppendLine(string.Format("CREATED:{0:yyyyMMddTHHmmssZ}", DateTime.Now.ToUniversalTime()));

		// Date format - yyyyMMddTHHmmssZ
		str.AppendLine(string.Format("DTSTART:{0}", mailTemplate.StartDateTime));
		str.AppendLine(string.Format("DTSTAMP:{0:yyyyMMddTHHmmss}", DateTime.Now.ToUniversalTime()));
		str.AppendLine(string.Format("DTEND:{0:}", mailTemplate.EndDateTime));

		str.AppendLine(string.Format("LAST-MODIFIED:{0:yyyyMMddTHHmmssZ}", DateTime.Now.ToUniversalTime()));

		// web meeting link
		str.AppendLine(string.Format("LOCATION: {0}", mailTemplate.EventLink));
		//or
		//str.AppendLine(string.Format("LOCATION: {0}", mailTemplate.EventLocation));

		str.AppendLine("PRIORITY: 5");
		str.AppendLine("SEQUENCE: 0");

		str.AppendLine(string.Format("UID:{0}", (eventID.HasValue ? "EventId" + eventID : Guid.NewGuid().ToString())));
		str.AppendLine(string.Format("DESCRIPTION:{0}", messageBody.Replace("\n", "<br>")));
		str.AppendLine(string.Format("X-ALT-DESC;FMTTYPE=text/html:{0}", messageBody.Replace("\n", "<br>")));
		str.AppendLine(string.Format("SUMMARY:{0}", subject));
		str.AppendLine("STATUS:CONFIRMED"); 
		str.AppendLine(string.Format("ORGANIZER;CN={0}:MAILTO:{1}", mailTemplate.MailFrom, mailTemplate.MailFrom));
		str.AppendLine(string.Format("ATTENDEE;CN={0};RSVP=TRUE:mailto:{1}", string.Join(",", mailTemplate.Attendee), string.Join(",", mailTemplate.Attendee)));

		str.AppendLine("BEGIN:VALARM");
		str.AppendLine("TRIGGER:-PT15M");
		str.AppendLine("ACTION:DISPLAY");
		str.AppendLine("DESCRIPTION:Reminder");
		str.AppendLine("END:VALARM");
		str.AppendLine("END:VEVENT");
		str.AppendLine("END:VCALENDAR");

		return str.ToString();
	}
} 

Step 3: Call & execute Mail.Send() Method

Common C# code for sending email via SMTP is completed. Now we can call & execute this Mail.Send() method from Controller (SendEmails.cs) or another code page in two steps:

a) Set all Property values

Before calling the Mail.Send() method, set all necessary property values (get all input & assign its values), see the sample below.

MailTemplateProperty mailTemplate = new MailTemplateProperty
{
	// "Gmail SMTP Configuration/Credential"
	SmtpClientHost = "smtp.gmail.com",
	SmtpClientPort = 587,
	SmtpClientEnableSSL = true,
	CredentialUserName = "sender_emailId@example.com",
	CredentialPass = "google_app_password",

	// "Compose Email"
	SenderName = "Admin",
	MailFrom = "sender_emailId@gmail.com",
	MailTo = "recipient_emailId@outlook.com",
	MailCC = string.Empty,
	Subject = "Next Team Meeting",
	Body = "This is a test mail from admin.",

	// "File attachments"
	//Attachment = new System.Net.Mail.Attachment(mailAttachmentFile.OpenReadStream(), "Meeging.pdf"),
	// or
	Attachment = new System.Net.Mail.Attachment(Path.GetDirectoryName(Assembly.GetEntryAssembly().Location) + "/Files/Meeting.pdf"),

	// "Adding logo/image on footer"
	Footer = Path.GetDirectoryName(Assembly.GetEntryAssembly().Location) + "/Images/MailFooterLogo.png",

	// Attach Calendar or meeting properties
	StartDateTime = DateTime.Now.ToUniversalTime().ToString("yyyyMMddTHHmmssZ"),
	EndDateTime = DateTime.Now.AddHours(1).ToUniversalTime().ToString("yyyyMMddTHHmmssZ"),
	// MS Teams or Skype or webex meeting link
	EventLink = "https://www.webex.com/test-meeting.html",
	EventLocation = "Online",
	Attendee = "recipient_emailId@outlook.com"
};

b) Finally, Call Mail.Send() Method

Now, call Mail.Send() method by passing ‘mailTemplate‘ object as a parameter.

Mail.Send(mailTemplate); 

That’s it, test the code. if sending mail is successful then the recipient(s) will receive the email in a few seconds. In case of failure, it will return false status as a bool value.
But you can also log an error or throw an exception based on your requirement.

Method 1:

You can get the file attachment from Azure blob storage but in this example, the Meeting.pdf file is attached from the Root folder, see the below screenshot.

Method 2:

You can use IFormFile to receive a file as input from the front-end application and send it as an attachment, please see the implementation in the screenshot.

Download Source Code and try it yourself (open sample project using Visual Studio 2022)

In this post, we will discuss how to use MailChimp in the .Net Core application, which Nuget Package needs to be used, how to create or add Audience, Subscribers, Email Template, Campaign, and generate reports using C# code. We will be using the MailChimp.Net.V3 Nuget package developed by Brandon Seydel. It is a .Net Wrapper for Mail Chimp API and easy to implement with a few lines of code.

First, let’s understand MailChimp and how to use it.

What is MailChimp?

Mailchimp is an Email Service Provider (ESP) and one of the most famous email marketing software or platforms in today’s world. It is used to develop & manage newsletters, and send automated emails to the customers (list of users). Assume you have a mailing list and want to send a weekly newsletter to every individual. This process can be automated with MailChimp service and you can reach out to your client, customer, and other interested parties to grow your business.

Free to use

It is free to use up to 2000 contacts with a limit of 10,000 emails per month with a daily limit of 2,000

A free plan is also available which allows you to add 2000 contacts and send 10,000 emails per month with a daily limit of 2,000.

How to send marketing emails via MailChimp?

Below are the basic steps to send emails to target users (subscribers).

1) Create an Audience – it is just like a group name, for example, the Audience Name could be named as WeeklyNewsGrp. In code, we will be using Audience ID.
2) Add subscribers – adding email addresses to an Audience.
3) Create Template – HTML content with text, images, URL, and other stuff
4) Create Campaign – final step where you must select:
    a. To address – targeted audience name
    b. From address
    c. Subject – short text
    d. Content – this is your template

Once all the above steps are done, either you can send it immediately or schedule it for a future date. Later, you can also generate the Campaign Report to know each subscriber’s status & activities.

Using MailChimp in .Net code – C#

To use MailChimp in .Net Core project you need to install the MailChimp.Net.V3 package, developed by Brandon Seydel. It is licensed under the MIT license. You can see more about it here

Install this package in your project, for example – Business Layer.

Installing from package manager console – Install-Package MailChimp.Net.V3

Get the API Key for development

Before you start implementing the code you should have a MailChimp API Key handy. You need to pass this API Key whenever you are performing any action via code like creating an audience, adding members, getting reports, or any other request.

1) Login into your account (you can register with a free plan for development purposes)

2) Click on Account (left-hand side below) >> click on Account & billing. It will open the account page.

3) Click on Extras >> API Keys. It will open the API Key page.

4) you can see API Key as shown in the below screenshot.

Let’s start coding in C# – Mail Chimp – Step-by-Step

Create a .Net application and install the MailChimp.Net.V3 NuGet package in your project.

Configure API Key in appsettings.json

"MailChimp": {
    "ApiKey": "60exxxx-Your-API-KEY-xxxxxxxxb8-us20"
  }

1. Create an Audience

First, the audience name needs to be created to add the email addresses.

Consider “Audience” as a group name where you need to add a list of subscribers’ email Ids.

Note: AudienceID is known as listId in code.

I have written all MailChimp related code in a separate static class so that any method can be called by just passing the necessary parameters. Create a .cs file and name it as MailChimpHelper.cs. Below is the code to add an Audience.

using MailChimp.Net;
using MailChimp.Net.Interfaces;
using MailChimp.Net.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using System.Web;


public static class MailChimpHelper
{
    public static async Task<string> AudienceAddAsync(string apiKey, string audienceName, Dictionary<string, string> config)
    {
        string newAudienceId = string.Empty;

        IMailChimpManager mc = new MailChimpManager(apiKey);

        try
        {
            /*All inputs are mandatory.
			 Store these default values in some config file or database*/
            var audience = await mc.Lists.AddOrUpdateAsync(new List
            {
                Name = audienceName,
                PermissionReminder = config["PermissionReminder"], //You are receiving this email because you opted in via our website.
                Contact = new Contact
                {
                    Company = config["Company"],
                    Address1 = config["Address1"],
                    City = config["City"],
                    Country = config["Country"],
                    State = config["State"],
                    Zip = config["Zip"]
                },

                CampaignDefaults = new CampaignDefaults
                {
                    FromEmail = config["DefaultFromEmail"], //Registered emaild id
                    FromName = config["DefaultFromName"],
                    Language = config["DefaultLanguage"], //"en"
                    Subject = ""
                }

            });

            newAudienceId = audience.Id;

        }
        catch (Exception ex)
        {
        }

        return newAudienceId;

    }
}

Call this static method from business class or wherever you prefer. See the sample code below.

public class Business
{
    private readonly IConfiguration configuration;

    public Business(IConfiguration _configuration)
    {
        configuration = _configuration;
    }

    public async Task CreateAudience()
    {
        //get the MailChimp API Key from appsettings.json
        string apiKey = configuration.GetSection("MailChimp:ApiKey").Value;

        //Get Audience Configuration details from database or config file.
        Dictionary<string, string> audienceConfig = GetAudienceConfig();

        string newAudienceName = "WeeklyNewsGrp";
        string newAudienceId = await MailChimpHelper.AudienceAddAsync(apiKey, newAudienceName, audienceConfig);

        //save newly created Audience Id in DB
        SaveNewAudienceId(newAudienceId); 
    }
}

Debug – Code will return the newly created “audience.Id” which is also known as “listId”.

The below image confirms Audience has been created via code and the same can be seen in the MailChimp portal.

To see Audience Id – On the same page, scroll down and click on Setting >> Audience name and defaults. It will navigate to another page and there you can see the newly created audience name & id, see the below screenshots.

2. Add Subscribers

The Next step is to add subscribers to an audience.

Note: Subscriber or Member or email id – all are the same.

The below code shows how to add a member’s emailId, first & last name. Add it to MailChimpHelper class and call this method from the business class.

public static async Task<Member> MemberAddOrUpdateAsync(string apiKey, string listId, SubscribeProperty subscribe)
{
    //To add email address
    var member = new Member { EmailAddress = HttpUtility.HtmlEncode(subscribe.Email.ToLower()), Status = Status.Subscribed };
    await new MailChimpManager(apiKey).Members.AddOrUpdateAsync(listId, member);

    //To update First & Last Name
    if (!string.IsNullOrWhiteSpace(subscribe.FirstName))
    {
        member.MergeFields.Add("FNAME", HttpUtility.HtmlEncode(subscribe.FirstName));
    }
    if (!string.IsNullOrWhiteSpace(subscribe.LastName))
    {
        member.MergeFields.Add("LNAME", HttpUtility.HtmlEncode(subscribe.LastName));
    }

    return await new MailChimpManager(apiKey).Members.AddOrUpdateAsync(listId, member);
}

The below code shows adding more than one subscriber by using foreach loop, in business class.

public async Task AddUpdateMembers()
{
	//Get newly registered users from database
	var newUsers = GetNewUsers();

	var existingAudienceId = "7f7cb00b8f";

	foreach (var user in newUsers)
	{
		SubscribeProperty subscribe = new SubscribeProperty
		{
			Email = user.subscribers_id,
			FirstName = user.first_name,
			LastName = user.last_name
		};

		await MailChimpHelper.MemberAddOrUpdateAsync(apiKey, existingAudienceId, subscribe);
	}
}

The below screenshot confirms the added or updated email address, first and last name via code can be seen in the portal as well.

Additionally, you can specify one or more tags to an email address, below are the lines of code to add tags.

Tags tags = new Tags();
tags.MemberTags.Add(new Tag() { Name = "Promo", Status = "active" });
await new MailChimpManager(apiKey).Members.AddTagsAsync(listId, "abc@gmail.com", tags);

Code – To delete a Member

public static async Task MemberDeleteAsync(string apiKey, string listId, string emailId)
{
	IMailChimpManager mc = new MailChimpManager(apiKey);
	await mc.Members.DeleteAsync(listId, emailId);
}

Code – To get all Member lists based on ListId(AudienceId)

public static List<string> GetMembersAsync(string apiKey, string listId)
{
    var members = new MailChimpManager(apiKey).Members.GetAllAsync(listId).Result;
    return members.Select(s => s.EmailAddress).ToList();
}

3. Create a Template

A template is required to create any Campaign. Add the below code in MailChimpHelper class which will return the newly created template Id. It is better to save the template Id in the database, for later use.

public static async Task<int> TemplateCreateAsync(string apiKey, string templateName, string UnlayerContent)
{
    var template = await new MailChimpManager(apiKey).Templates.CreateAsync(templateName, string.Empty, UnlayerContent);
    return template.Id;
}

Important – You need to pass full Html content as a string that contains all text, images, buttons, links, and other inputs. Third-party control needs to be integrated if you want to generate such content from your application.

To check created Template in the portal – Go to Campaigns >> Click on Email template, as shown in the below screenshot.

4. Create a Campaign

The final step is to create a Campaign and send emails with the Template(body content) to all the subscribers for an Audience. Add the below code and call it from business class.

public static async Task<string> CampaignAddAsync(string apiKey, string audienceId, int templateId, string issueTitle, string fromName)
{
    MailChimpManager mc = new MailChimpManager(apiKey);

    var replyTo = await mc.Lists.GetAsync(audienceId);

    Campaign cp = new Campaign
    {
        Recipients = new Recipient { ListId = audienceId },
        Settings = new Setting
        {
            TemplateId = templateId,
            FromName = fromName,
            SubjectLine = issueTitle,
            Title = issueTitle,
            ReplyTo = replyTo.CampaignDefaults.FromEmail,

        },
        Type = CampaignType.Regular,
    };

    var campaign = await mc.Campaigns.AddOrUpdateAsync(cp);

    await mc.Campaigns.SendAsync(campaign.Id); 

    return campaign.Id;
}

To check it in the portal – Go to Campaigns >> click on All campaigns and check the status of the newly created Campaign, as shown in the below screenshot.

That’s it, we have seen how to send newsletters or marketing emails by using the MailChimp package in .Net code. Points to remember – we need an Audience Id, a list of email addresses, and a template Id to create a Campaign.

MailChimp Campaign Report

Once the campaign is sent you can track and check the report to know the total number of emails sent, success or failure delivery, opened, subscriber clicks, send time, Unsubscribe & its reason, and more.

I usually use the below lines of code to get the Campaign report, but there are different types of reports available that you can explore.

// To get sent report
IEnumerable<SentTo> sendResults = new MailChimpManager(apiKey).Reports.GetSentToRecipientsAsync(campaignId).Result.Where(w => w.Status == "sent");

// To get report of each email and its activities
var emailActivities = await new MailChimpManager(apiKey).Reports.GetEmailActivitiesAsync(campaignId);                

Debug – Report screenshots

Thanks

• Validate JSON, Format & Beautify JSON
• SSN Extractor
• UUID/GUID Extractor
• URL Extractor
• MAC Address Extractor