DEV Community: Neeraj Sharma

Methods and Functions in C#

Neeraj Sharma — Tue, 28 Oct 2025 10:23:14 +0000

Introduction

Methods are reusable blocks of code that perform specific tasks. They are fundamental to organizing code, reducing duplication, and making programs more maintainable. In this topic, we'll explore how to create, call, and effectively use methods in C#.

What is a Method?

A method is a code block that contains a series of statements. Methods are declared within classes and can be called multiple times from different parts of your program. They help in:

Code reusability
Modularity
Maintainability
Testing

Method Declaration Syntax

access-modifier return-type method-name(parameter-list)
{
    // Method body
    // Statements
}

Basic Example

public static void SayHello()
{
    Console.WriteLine("Hello, World!");
}

Method Components

1. Access Modifiers

Control the visibility of methods:

public: Accessible from anywhere
private: Accessible only within the same class (default)
protected: Accessible within the same class and derived classes
internal: Accessible within the same assembly

2. Return Types

Specify what type of value the method returns:

void: No return value
int, string, bool: Specific data types
Custom types: Classes, structs, etc.

3. Method Name

Should follow PascalCase naming convention and be descriptive:

public static int CalculateArea(int width, int height)
{
    return width * height;
}

4. Parameters

Values passed to the method when called:

public static void GreetUser(string name, int age)
{
    Console.WriteLine($"Hello, {name}! You are {age} years old.");
}

Calling Methods

Calling Void Methods

SayHello(); // No return value expected

Calling Methods with Return Values

int area = CalculateArea(10, 5);
Console.WriteLine($"Area: {area}");

Calling Methods with Parameters

GreetUser("John", 25);

Parameter Types

Value Parameters (Default)

Changes to parameters don't affect the original values:

public static void ModifyValue(int number)
{
    number = 100; // This doesn't change the original value
}

int original = 50;
ModifyValue(original);
Console.WriteLine(original); // Still 50

Reference Parameters (ref)

Changes to parameters affect the original values:

public static void ModifyReference(ref int number)
{
    number = 100; // This changes the original value
}

int original = 50;
ModifyReference(ref original);
Console.WriteLine(original); // Now 100

Output Parameters (out)

Used to return multiple values from a method:

public static void GetCoordinates(out int x, out int y)
{
    x = 10;
    y = 20;
}

GetCoordinates(out int xCoord, out int yCoord);
Console.WriteLine($"X: {xCoord}, Y: {yCoord}"); // X: 10, Y: 20

Parameter Arrays (params)

Allows passing a variable number of arguments:

public static int SumNumbers(params int[] numbers)
{
    int sum = 0;
    foreach (int number in numbers)
    {
        sum += number;
    }
    return sum;
}

int total = SumNumbers(1, 2, 3, 4, 5);
Console.WriteLine(total); // 15

Method Overloading

Multiple methods with the same name but different parameters:

public static int Add(int a, int b)
{
    return a + b;
}

public static double Add(double a, double b)
{
    return a + b;
}

public static int Add(int a, int b, int c)
{
    return a + b + c;
}

// Usage
int result1 = Add(5, 3);        // Calls first method
double result2 = Add(5.5, 3.2);  // Calls second method
int result3 = Add(5, 3, 2);      // Calls third method

Optional Parameters and Named Arguments

Optional Parameters

Provide default values for parameters:

public static void CreateFile(string name, string extension = ".txt", bool overwrite = false)
{
    string fileName = $"{name}{extension}";
    Console.WriteLine($"Creating file: {fileName}, Overwrite: {overwrite}");
}

// Usage
CreateFile("document");                    // Uses default values
CreateFile("document", ".pdf");            // Overrides extension
CreateFile("document", ".pdf", true);      // Overrides both

Named Arguments

Specify arguments by name rather than position:

CreateFile(name: "document", overwrite: true);
CreateFile(overwrite: true, name: "document"); // Order doesn't matter

Expression-bodied Methods

Concise syntax for simple methods (C# 6+):

// Traditional syntax
public static int Square(int number)
{
    return number * number;
}

// Expression-bodied syntax
public static int Square(int number) => number * number;

// With void return type
public static void SayHello(string name) => Console.WriteLine($"Hello, {name}!");

Local Functions (C# 7+)

Functions defined within other methods:

public static int CalculateFactorial(int number)
{
    // Local function
    int Factorial(int n)
    {
        if (n <= 1) return 1;
        return n * Factorial(n - 1);
    }

    return Factorial(number);
}

Async Methods

Methods that support asynchronous operations:

public static async Task<string> GetDataAsync()
{
    // Simulate async operation
    await Task.Delay(1000);
    return "Data retrieved";
}

// Calling async method
string data = await GetDataAsync();

Method Design Best Practices

1. Single Responsibility Principle

Each method should have one clear purpose:

// Good
public static double CalculateArea(double radius)
{
    return Math.PI * radius * radius;
}

public static void PrintArea(double area)
{
    Console.WriteLine($"The area is: {area:F2}");
}

// Avoid combining responsibilities
public static void CalculateAndPrintArea(double radius)
{
    double area = Math.PI * radius * radius;
    Console.WriteLine($"The area is: {area:F2}");
}

2. Meaningful Names

// Good
public static bool IsPrimeNumber(int number)
{
    // Implementation
}

// Avoid
public static bool Check(int n)
{
    // Implementation
}

3. Appropriate Method Length

Keep methods short and focused:

// Good - broken into smaller methods
public static void ProcessOrder(Order order)
{
    ValidateOrder(order);
    CalculateTotal(order);
    SaveOrder(order);
    SendConfirmation(order);
}

// Avoid - overly long method
public static void ProcessOrder(Order order)
{
    // 100+ lines of code doing everything
}

4. Minimize Side Effects

Methods should ideally not modify external state:

// Good - pure function
public static int Add(int a, int b)
{
    return a + b; // No side effects
}

// Avoid when possible
public static int AddAndStore(int a, int b)
{
    int result = a + b;
    LastCalculation = result; // Side effect
    return result;
}

Method Documentation

Use XML documentation comments for better code documentation:

/// <summary>
/// Calculates the area of a circle given its radius
/// </summary>
/// <param name="radius">The radius of the circle</param>
/// <returns>The area of the circle</returns>
/// <exception cref="ArgumentException">Thrown when radius is negative</exception>
public static double CalculateCircleArea(double radius)
{
    if (radius < 0)
        throw new ArgumentException("Radius cannot be negative", nameof(radius));

    return Math.PI * radius * radius;
}

Common Method Patterns

1. Factory Methods

public static Person CreatePerson(string name, int age)
{
    return new Person
    {
        Name = name,
        Age = age,
        Id = Guid.NewGuid()
    };
}

2. Validation Methods

public static bool IsValidEmail(string email)
{
    return email.Contains("@") && email.Contains(".");
}

3. Helper Methods

public static string FormatCurrency(decimal amount)
{
    return amount.ToString("C");
}

Error Handling in Methods

Returning Error Information

public static bool TryParseInt(string input, out int result)
{
    return int.TryParse(input, out result);
}

// Usage
if (TryParseInt("123", out int number))
{
    Console.WriteLine($"Parsed number: {number}");
}
else
{
    Console.WriteLine("Invalid number format");
}

Exception Handling

public static double Divide(double dividend, double divisor)
{
    if (divisor == 0)
        throw new DivideByZeroException("Divisor cannot be zero");

    return dividend / divisor;
}

Practical Examples

Example 1: Calculator Methods

public class Calculator
{
    public static double Add(double a, double b) => a + b;

    public static double Subtract(double a, double b) => a - b;

    public static double Multiply(double a, double b) => a * b;

    public static double Divide(double a, double b)
    {
        if (b == 0)
            throw new ArgumentException("Cannot divide by zero");
        return a / b;
    }

    public static double Power(double baseNumber, double exponent) => 
        Math.Pow(baseNumber, exponent);
}

Example 2: String Processing Methods

public class StringProcessor
{
    public static string ReverseString(string input)
    {
        if (string.IsNullOrEmpty(input))
            return input;

        char[] chars = input.ToCharArray();
        Array.Reverse(chars);
        return new string(chars);
    }

    public static bool IsPalindrome(string input)
    {
        string cleanInput = input?.ToLower().Replace(" ", "") ?? "";
        string reversed = ReverseString(cleanInput);
        return cleanInput == reversed;
    }

    public static string[] SplitByComma(string input)
    {
        return input?.Split(',', StringSplitOptions.TrimEntries | 
            StringSplitOptions.RemoveEmptyEntries) ?? new string[0];
    }
}

Next Steps

Now that you understand methods, let's explore arrays and collections, which will allow you to work with groups of data efficiently.

Additional Resources

Comprehensive .NET Development Course

Neeraj Sharma — Sun, 26 Oct 2025 14:57:59 +0000

Overview

This course contains a complete learning path for .NET development, structured from beginner to expert levels. The course is organized into 7 main sections with detailed topics, hands-on projects, and examples in each section.

Whether you're a complete beginner or an experienced developer looking to expand your .NET skills, this course provides a structured approach to mastering .NET development technologies.

Note: This course is regularly updated with new content, improvements, and additional resources. Check back frequently for the latest materials.

Course Structure

Section 0: Introduction - Completed

Course overview and learning approach
Development environment setup guide
Prerequisites and system requirements

Section 1: C# Fundamentals (6-8 weeks) - Completed

Foundational C# programming skills needed for all .NET development:

Variables, data types, and operators
Control flow statements
Object-oriented programming
Exception handling
LINQ and collections
Asynchronous programming

Section 2: ASP.NET Web API (6-8 weeks) - Completed

Building RESTful services and APIs:

REST principles and HTTP protocols
Controllers and routing
Data transfer objects
Entity Framework Core integration
Authentication and authorization

Section 3: ASP.NET MVC (6-8 weeks) - Coming Soon

Traditional web applications with server-side rendering:

MVC architecture pattern
Razor view engine
Model binding and validation
Authentication in MVC
Client-side integration

Section 4: Razor Pages (4-6 weeks) - Coming Soon

Page-centric web development approach:

Page models and handlers
Data binding and validation
Security implementation
AJAX integration

Section 5: Blazor (8-10 weeks) - Coming Soon

Component-based web UI development:

Component architecture
Blazor Server vs WebAssembly
State management
JavaScript interop
Authentication in Blazor

Section 6: Additional Resources (2 weeks) - Coming Soon

Modern development practices:

Git and version control
Testing strategies
Cloud deployment
Containerization with Docker
Microservices architecture

Section 7: Conclusion - Completed

Next steps in your .NET journey
Certification paths
Professional development resources

Folder Structure

dotnet-course/
├── 00-introduction/
├── 01-csharp-fundamentals/
│   ├── topics/
│   ├── projects/
│   └── examples/
├── 02-aspnet-web-api/
│   ├── topics/
│   ├── projects/
│   └── examples/
├── 03-aspnet-mvc/
│   ├── topics/
│   ├── projects/
│   └── examples/
├── 04-razor-pages/
│   ├── topics/
│   ├── projects/
│   └── examples/
├── 05-blazor/
│   ├── topics/
│   ├── projects/
│   └── examples/
├── 06-additional-resources/
│   ├── topics/
│   └── resources.md
└── 07-conclusion/

Each section contains:

topics/: Individual markdown files for each learning topic
projects/: Hands-on project guides with step-by-step instructions
examples/: Code examples and best practices demonstrations

How to Use This Course

For Complete Beginners

Start with Section 0: Introduction
Proceed sequentially through Section 1: C# Fundamentals
Continue through each section in order
Complete all hands-on projects
Review examples to understand best practices

For Experienced Developers

Assess your current knowledge using the prerequisites guide
Skip sections you're already proficient in
Focus on new technologies (Blazor, advanced MVC, etc.)
Complete projects in areas where you need practice

For Educators/Trainers

Use the structured curriculum as a foundation
Adapt timelines based on your students' pace
Supplement with additional exercises as needed
Use projects as assessment tools

Prerequisites

Basic computer literacy
Willingness to learn programming concepts
A computer with at least 4GB RAM and 10GB free disk space
Windows, macOS, or Linux operating system

Required Software

.NET SDK (latest LTS version)
Visual Studio Code or Visual Studio
Git for version control
Web browser for testing applications

Time Commitment

The complete course requires approximately 35-45 weeks (8-11 months) to complete thoroughly:

3-6 hours per week recommended
Each section includes estimated completion times
Projects may require additional time for exploration

Learning Approach

This course follows a hands-on, practical approach:

Read First: Go through topic explanations before attempting projects
Code Along: Type out examples rather than copying and pasting
Practice: Modify examples to test your understanding
Build Projects: Complete all hands-on projects thoroughly
Review: Revisit topics and projects as needed

Getting Started

Download this course
Read the introduction section
Set up your development environment
Begin with Section 1: C# Fundamentals
Follow the sequential structure for best results

Accessing the Course with Obsidian

This course is designed to work seamlessly with Obsidian, a powerful knowledge management tool. To access the course using Obsidian:

Install Obsidian from obsidian.md
Open Obsidian and select "Open folder as vault"
Choose the dotnet-course directory from this course
The course content will be organized as a graph of interconnected notes
Use Obsidian's features like backlinks, tags, and canvas for enhanced learning

Support

If you need help during the course, here’s how to get support:

📖 Start with the course documentation

Most common questions are already explained in detail.
🛠 Review the examples and project guides

Walk through the provided code samples before reaching out.
🌐 Join the .NET community

Explore forums (Stack Overflow, Reddit, official .NET Discord/Slack) and social media groups for peer discussions.
📧 Contact me directly

For course‑specific questions, feedback, or clarifications, email me at:

neerajshdev@gmail.com

💡 Tip: Please check the documentation and examples first before emailing, so we can keep communication focused and efficient.

Happy coding! 🚀

C# Type System

Neeraj Sharma — Sun, 26 Oct 2025 12:07:20 +0000

C# is a strongly-typed language with two categories of types: value types and reference types. Understanding this distinction is crucial for effective programming in C#.

Value Types

Stored directly in memory (stack) and contain their data. When you assign a value type to another variable, a copy of the value is created.

Characteristics of Value Types

Stored on the stack
Memory is allocated when declared
Memory is deallocated when they go out of scope
Assignment creates a copy of the value
Cannot be null (unless nullable)

Common Value Types

Integral Types

int (32-bit signed integer)
long (64-bit signed integer)
short (16-bit signed integer)
byte (8-bit unsigned integer)
sbyte (8-bit signed integer)
uint (32-bit unsigned integer)
ulong (64-bit unsigned integer)
ushort (16-bit unsigned integer)

Floating-Point Types

float (32-bit floating-point)
double (64-bit floating-point)
decimal (128-bit decimal)

Other Value Types

bool (Boolean)
char (Unicode character)
struct (Custom value types)
enum (Enumeration types)

// Value type examples
int age = 25;           // Stored directly on stack
double salary = 50000.50;
bool isActive = true;
char grade = 'A';

// Assignment creates a copy
int original = 10;
int copy = original;     // copy gets its own value
copy = 20;              // original remains 10

Reference Types

Stored as references to memory locations (heap). The variable contains a reference (pointer) to the actual data, not the data itself.

Characteristics of Reference Types

Stored on the heap
Memory managed by garbage collector
Assignment copies the reference, not the data
Can be null
Multiple variables can reference the same object

Common Reference Types

string (immutable sequence of characters)
object (base type for all types)
class (custom reference types)
interface (contracts for classes)
delegate (function pointers)
array (collections of elements)

// Reference type examples
string name = "John";    // Reference to string on heap
int[] numbers = {1, 2, 3}; // Reference to array on heap
object obj = new object();

// Assignment copies the reference
string original = "Hello";
string reference = original;  // Both point to same string
reference = "World";          // original still "Hello"

// But with mutable objects:
int[] array1 = {1, 2, 3};
int[] array2 = array1;        // Both reference same array
array2[0] = 99;               // array1[0] is also 99

Boxing and Unboxing

Boxing

Converting a value type to a reference type (object). This creates a copy of the value on the heap.

int value = 42;
object boxed = value;  // Boxing: int -> object

Unboxing

Converting a reference type back to a value type. Requires explicit casting.

object boxed = 42;
int unboxed = (int)boxed;  // Unboxing: object -> int

Performance Implications

Boxing and unboxing have performance costs:

Memory allocation on heap
Type checking at runtime
Potential for InvalidCastException

// Avoid unnecessary boxing
ArrayList list = new ArrayList();  // Old generic collection
list.Add(42);                       // Boxing occurs here

// Use generic collections instead
List<int> genericList = new List<int>();
genericList.Add(42);                // No boxing

Type Safety

C# is strongly typed, meaning:

Variables must be declared with a type
Type checking occurs at compile time
Invalid operations are caught before runtime
Type conversions must be explicit (when narrowing)

// Compile-time type checking
int number = 42;
// number = "text";  // Compilation error

// Explicit conversion required
double precise = 123.45;
int rounded = (int)precise;  // Explicit cast

The `object` Type

object is the base type for all types in C#. Any type can be assigned to an object variable.

object anything = 42;        // int -> object
anything = "text";           // string -> object
anything = new int[3];       // array -> object

// To use the actual type, cast back
string text = (string)anything;

Dynamic Typing with `dynamic`

C# also supports dynamic typing with the dynamic keyword. Type checking is deferred until runtime.

dynamic flexible = 42;
flexible = "text";           // OK at compile time
flexible = new object();     // OK at compile time

// Runtime type checking
Console.WriteLine(flexible.Length);  // May throw exception

When to Use `dynamic`

Interoperating with dynamic languages
Working with COM objects
Reflection scenarios
When type is unknown at compile time

Nullable Value Types

Value types cannot normally be null, but with nullable types, they can represent missing or undefined values.

int? nullableInt = null;     // Nullable int
double? nullableDouble = 5.5;
bool? nullableBool = null;

// Checking for null
if (nullableInt.HasValue)
{
    int value = nullableInt.Value;
}

// Null coalescing operator
int defaultValue = nullableInt ?? 0;

Type Inference with `var`

C# can infer types from initialization expressions using the var keyword.

var number = 42;         // int
var text = "hello";      // string
var list = new List<int>(); // List<int>

// Still strongly typed
number = "text";         // Compilation error

Best Practices

1. Prefer Value Types for Small, Immutable Data

// Good for value types
public struct Point
{
    public int X { get; }
    public int Y { get; }

    public Point(int x, int y)
    {
        X = x;
        Y = y;
    }
}

2. Use Reference Types for Large or Mutable Data

// Good for reference types
public class Customer
{
    public string Name { get; set; }
    public List<Order> Orders { get; set; }
}

3. Avoid Unnecessary Boxing

// Bad - causes boxing
ArrayList mixed = new ArrayList();
mixed.Add(42);
mixed.Add("text");

// Good - no boxing
List<int> numbers = new List<int>();
List<string> texts = new List<string>();

4. Use `var` When Type is Obvious

// Good uses of var
var result = CalculateTotal();
var query = from c in customers where c.IsActive select c;

// Prefer explicit typing when clarity matters
Dictionary<string, List<int>> data = new();

Common Mistakes

1. Treating Reference Types as Value Types

// Mistake
Point p1 = new Point(1, 2);
Point p2 = p1;        // Copies reference, not value
p2.X = 5;             // Modifies both p1 and p2

2. Ignoring Null Reference Exceptions

string text = null;
int length = text.Length;  // NullReferenceException

3. Unnecessary Boxing in Collections

// Avoid
ArrayList list = new ArrayList();
for (int i = 0; i < 1000; i++)
{
    list.Add(i);  // Boxing occurs 1000 times
}

Summary

Understanding C#'s type system is fundamental to writing efficient and correct code. Value types are stored directly and copied by value, while reference types are stored on the heap and copied by reference. Choose the appropriate type category based on your data's characteristics and usage patterns. Be mindful of boxing/unboxing performance implications and use nullable types when you need to represent missing values for value types.

Variables in C#

Neeraj Sharma — Sun, 26 Oct 2025 11:22:30 +0000

What is a Variable?

A variable is a named storage location in memory that holds a value. In C#, every variable has a specific data type that determines:

What kind of value it can store
How much memory it occupies
What operations can be performed on it

Memory and Variables

When you declare a variable in C#, you're essentially asking the computer to reserve a specific amount of memory space to store a value. The amount of memory reserved depends on the data type:

// This reserves 4 bytes of memory (for int)
int age = 25;

// This reserves 8 bytes of memory (for double)
double salary = 50000.50;

// This reserves memory for a reference (typically 8 bytes on 64-bit systems)
// plus the actual string data
string name = "John";

Variable Characteristics

1. Name (Identifier)

Must start with a letter or underscore
Can contain letters, digits, and underscores
Case-sensitive
Cannot be a C# keyword

// Valid variable names
int age;
string firstName;
double _salary;
int studentCount123;

// Invalid variable names
int 123age;        // Cannot start with digit
string class;      // 'class' is a keyword
int my-age;        // Hyphen not allowed

2. Data Type

Determines the kind of data the variable can hold
Affects memory allocation and operations
Cannot be changed after declaration

3. Value

The actual data stored in the variable
Must match the variable's data type
Can be changed during program execution

4. Scope

The region of code where the variable is accessible
Determined by where it's declared

Variable Lifetime

Variables have different lifetimes depending on where they're declared:

Local Variables

Declared inside methods, constructors, or blocks
Created when the block is entered
Destroyed when the block is exited

public void CalculateTotal()
{
    int sum = 0;  // Created when method starts
    // ... use sum ...
} // sum is destroyed here

Instance Variables (Fields)

Declared in a class but outside methods
Created when the object is instantiated
Exist as long as the object exists

public class Product
{
    private string name;     // Instance variable
    private decimal price;   // Instance variable

    public Product(string productName, decimal productPrice)
    {
        name = productName;
        price = productPrice;
    }
}

Static Variables

Declared with the static keyword
Shared among all instances of the class
Exist for the entire program lifetime

public class Counter
{
    private static int instanceCount = 0;  // Static variable

    public Counter()
    {
        instanceCount++;  // Increments for every new instance
    }
}

Constants vs Variables

While variables can change their values, constants cannot:

// Variable - value can change
int score = 100;
score = 150;  // OK

// Constant - value cannot change
const double PI = 3.14159;
// PI = 3.14;  // Compilation error

Best Practices for Variable Naming

Naming Conventions

Use camelCase for local variables and parameters
Use PascalCase for properties and methods
Use meaningful names that describe the purpose

// Good naming
int studentAge;
string customerName;
decimal accountBalance;
bool isActive;

// Avoid generic names
int x;           // What does x represent?
string str;      // Too vague
decimal d;       // Unclear purpose

Hungarian Notation (Avoid)

// Don't do this (Hungarian notation)
int iAge;        // 'i' for integer
string strName;  // 'str' for string

// Do this instead
int age;
string name;

Variable Initialization

Default Values

C# assigns default values to variables if not explicitly initialized:

int number;      // Default: 0
bool flag;       // Default: false
string text;     // Default: null
double value;    // Default: 0.0

Explicit Initialization

Always initialize variables to avoid unexpected behavior:

// Good practice
int age = 0;
string name = string.Empty;
bool isValid = false;

// Avoid
int age;  // Uninitialized - could cause issues

Common Variable-Related Errors

1. Use of Unassigned Local Variable

int number;
Console.WriteLine(number);  // Error: Use of unassigned local variable

2. Type Mismatch

int age = "25";  // Error: Cannot implicitly convert string to int

3. Scope Issues

if (true)
{
    int x = 10;
}
Console.WriteLine(x);  // Error: x is not in scope

Variable Declaration Patterns

Single Declaration

int age = 25;

Multiple Declarations

int x = 1, y = 2, z = 3;

Declaration without Initialization

int age;
age = 25;  // Initialize later

Inline Declaration (C# 7.0+)

// Before C# 7.0
int result;
if (int.TryParse(input, out result))
{
    // use result
}

// C# 7.0+
if (int.TryParse(input, out int result))
{
    // use result
}

Summary

Variables are the building blocks of any C# program. Understanding how they work in memory, their scope, lifetime, and proper naming conventions is crucial for writing maintainable and bug-free code. Always choose appropriate data types, initialize variables properly, and follow naming conventions to make your code readable and professional.

C# for Beginners: Master the .NET Ecosystem Step by Step

Neeraj Sharma — Sun, 26 Oct 2025 11:18:36 +0000

Introduction to C# and the .NET Ecosystem

What is C#?

C# (pronounced "C Sharp") is a modern, object-oriented programming language developed by Microsoft in 2000. It was designed to be simple, safe, and powerful, combining the best features of C++ and Java while adding new capabilities specific to the .NET platform.

C# is part of the .NET ecosystem and is used to build a wide variety of applications including:

Web applications (ASP.NET Core)
Desktop applications (Windows Forms, WPF, MAUI)
Mobile applications (Xamarin, MAUI)
Cloud and microservices (Azure Functions, Web APIs)
Games (Unity)
IoT applications

The .NET Platform

.NET is a free, open-source development platform that supports multiple programming languages, editors, and operating systems. It provides a runtime environment, class libraries, and development tools for building and running applications.

.NET Evolution

The .NET platform has evolved significantly over the years:

.NET Framework (Windows only) - The original implementation
.NET Core (Cross-platform) - A redesigned, modular version
.NET 5/6/7/8/9 (Unified platform) - The next generation of .NET

As of November 2024, .NET 9 is the latest version, with .NET 8 being the current Long Term Support (LTS) version.

.NET Runtime Components

The .NET runtime consists of:

Common Language Runtime (CLR): Manages execution of code
Base Class Library (BCL): Provides common functionality
Just-in-Time (JIT) Compiler: Compiles Intermediate Language (IL) to machine code

Why Learn C#?

1. Versatility

C# can be used to build virtually any type of application, making it a valuable skill for diverse development opportunities.

2. Strong Job Market

C# developers are in high demand, particularly in enterprise environments and Microsoft technology stacks.

3. Modern Language Features

C# continues to evolve with new features in each version, including pattern matching, records, and improved async support.

4. Excellent Tooling

Visual Studio and Visual Studio Code provide outstanding development experiences with debugging, IntelliSense, and refactoring tools.

5. Strong Ecosystem

Rich libraries, frameworks, and community support make development faster and more efficient.

C# Language Features

Object-Oriented Programming

C# supports core OOP concepts:

Classes and Objects
Inheritance
Polymorphism
Encapsulation
Abstraction

Modern Programming Paradigms

Functional Programming: LINQ, delegates, lambda expressions
Asynchronous Programming: async/await patterns
Memory Management: Automatic garbage collection with manual optimization options

Type Safety

C# is a strongly-typed language that helps prevent many common programming errors at compile time.

Cross-Platform Development

With .NET 5 and later, C# applications can run on Windows, macOS, and Linux.

.NET Application Models

1. .NET Desktop

Windows Forms
WPF (Windows Presentation Foundation)
MAUI (Multi-platform App UI)

2. .NET Web

ASP.NET Core MVC
ASP.NET Core Web API
Razor Pages
Blazor

3. .NET Cloud

Azure Functions
ASP.NET Core microservices
Docker containers

4. Mobile Development

.NET MAUI for cross-platform mobile apps
Xamarin (legacy)

C# Versions and Features

C# has released new versions annually, each adding valuable features:

Version	Release Year	Key Features
C# 1.0	2002	Basic OOP features
C# 2.0	2005	Generics, partial types
C# 3.0	2007	LINQ, lambda expressions
C# 4.0	2010	Dynamic binding, named arguments
C# 5.0	2012	Async/await
C# 6.0	2015	Expression-bodied members
C# 7.0	2017	Tuples, pattern matching
C# 8.0	2019	Nullable reference types, async streams
C# 9.0	2020	Records, init-only properties
C# 10.0	2021	Global using directives, file-scoped namespaces
C# 11.0	2022	Generic attributes, raw string literals
C# 12.0	2023	Primary constructors, collection expressions
C# 13.0	2024	Improved lambda expressions, ref readonly parameters

Development Tools

Visual Studio

The premier IDE for .NET development with comprehensive features for debugging, testing, and deployment.

Visual Studio Code

A lightweight, cross-platform editor with excellent C# extension support.

.NET CLI

Command-line interface for creating, building, and running .NET applications.

Rider

JetBrains' cross-platform .NET IDE with advanced refactoring capabilities.

Getting Started

In this section, we'll cover:

Setting up your development environment
Basic syntax and structure
Variables and data types
Control flow statements
Methods and functions
Object-oriented programming concepts
Collections and LINQ
Exception handling
File I/O operations
Asynchronous programming
Memory management
Debugging techniques

By the end of this section, you'll have a solid foundation in C# programming that will serve as the basis for all your .NET development work.

Best Practices

1. Follow Naming Conventions

Use PascalCase for classes, methods, and public members
Use camelCase for local variables and private members
Use meaningful, descriptive names

2. Write Clean, Readable Code

Keep methods small and focused
Use proper indentation and formatting
Add comments where necessary

3. Embrace Modern C# Features

Use pattern matching
Leverage nullable reference types
Apply async/await appropriately

Next Steps

After completing this section, you'll be ready to move on to building web services with ASP.NET Web API, where you'll apply your C# knowledge to create RESTful APIs.

Let's begin with setting up your development environment in the next topic.

C# by Example – Great for Programmers Switching from Other Languages

Neeraj Sharma — Sat, 25 Oct 2025 06:48:26 +0000

C# Fundamentals Code Samples

Overview

This document contains key code samples from each topic in Section 1: C# Fundamentals. These examples demonstrate best practices and common patterns you'll encounter throughout your C# development journey.

1. Introduction and Environment Setup

Basic Console Application

// Program.cs - Modern minimal template (C# 9+)
Console.WriteLine("Hello, World!");

// Traditional console application structure
using System;

namespace MyFirstApp
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello, World!");
        }
    }
}

Project File Configuration

<!-- MyFirstCSharpApp.csproj -->
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

</Project>

2. Variables, Data Types, and Operators

Variable Declarations

// Basic data types
int age = 25;
string name = "John";
bool isStudent = true;
double salary = 50000.50;
decimal accountBalance = 1250.75m;
char grade = 'A';

// Implicit typing
var count = 100;           // int
var message = "Hello";     // string
var price = 99.99;         // double

// Nullable types
int? nullableAge = null;
double? nullableScore = 85.5;

// String interpolation
string greeting = $"Hello, {name}! You are {age} years old.";

Operators

// Arithmetic operators
int sum = 10 + 5;
int difference = 10 - 5;
int product = 10 * 5;
int quotient = 10 / 5;
int remainder = 10 % 3;

// Assignment operators
int x = 10;
x += 5;  // x = x + 5
x -= 3;  // x = x - 3
x *= 2;  // x = x * 2

// Comparison operators
bool isEqual = (10 == 5);
bool isGreater = (10 > 5);
bool isLessOrEqual = (10 <= 5);

// Logical operators
bool result = (true && false);  // false
bool result2 = (true || false); // true
bool result3 = !true;           // false

3. Control Flow Statements

Conditional Statements

// if-else statement
int score = 85;
if (score >= 90)
{
    Console.WriteLine("Grade: A");
}
else if (score >= 80)
{
    Console.WriteLine("Grade: B");
}
else
{
    Console.WriteLine("Grade: C");
}

// switch statement
int dayOfWeek = 3;
switch (dayOfWeek)
{
    case 1:
        Console.WriteLine("Monday");
        break;
    case 2:
        Console.WriteLine("Tuesday");
        break;
    case 3:
        Console.WriteLine("Wednesday");
        break;
    default:
        Console.WriteLine("Other day");
        break;
}

// Switch expression (C# 8+)
string dayName = dayOfWeek switch
{
    1 => "Monday",
    2 => "Tuesday",
    3 => "Wednesday",
    _ => "Other day"
};

Looping Statements

// for loop
for (int i = 0; i < 10; i++)
{
    Console.WriteLine($"Number: {i}");
}

// foreach loop
string[] fruits = { "Apple", "Banana", "Orange" };
foreach (string fruit in fruits)
{
    Console.WriteLine($"Fruit: {fruit}");
}

// while loop
int counter = 0;
while (counter < 5)
{
    Console.WriteLine($"Count: {counter}");
    counter++;
}

// do-while loop
int number = 0;
do
{
    Console.WriteLine($"Number: {number}");
    number++;
} while (number < 3);

4. Methods and Functions

Method Declaration and Usage

// Method with parameters and return value
public static int Add(int a, int b)
{
    return a + b;
}

// Void method
public static void GreetUser(string name)
{
    Console.WriteLine($"Hello, {name}!");
}

// Method with optional parameters
public static void CreateFile(string name, string extension = ".txt", bool overwrite = false)
{
    string fileName = $"{name}{extension}";
    Console.WriteLine($"Creating file: {fileName}, Overwrite: {overwrite}");
}

// Expression-bodied method (C# 6+)
public static int Square(int number) => number * number;
public static void SayHello(string name) => Console.WriteLine($"Hello, {name}!");

// Method with out parameter
public static bool TryParseInt(string input, out int result)
{
    return int.TryParse(input, out result);
}

// Method with params
public static int SumNumbers(params int[] numbers)
{
    int sum = 0;
    foreach (int number in numbers)
    {
        sum += number;
    }
    return sum;
}

5. Arrays and Collections

Arrays

// Array declaration and initialization
int[] numbers = new int[5];
int[] scores = { 95, 87, 92, 88, 90 };
string[] names = new string[] { "John", "Jane", "Bob" };

// Multi-dimensional arrays
int[,] matrix = new int[3, 3];
int[,] predefinedMatrix = { { 1, 2, 3 }, { 4, 5, 6 }, { 7, 8, 9 } };

// Jagged arrays
int[][] jaggedArray = new int[3][];
jaggedArray[0] = new int[] { 1, 2 };
jaggedArray[1] = new int[] { 3, 4, 5 };
jaggedArray[2] = new int[] { 6 };

Collections

// List<T>
List<string> names = new List<string>();
names.Add("John");
names.Add("Jane");
names.AddRange(new[] { "Bob", "Alice" });

// Dictionary<TKey, TValue>
Dictionary<string, int> ages = new Dictionary<string, int>();
ages["John"] = 25;
ages.Add("Jane", 30);

// HashSet<T>
HashSet<string> uniqueNames = new HashSet<string>();
uniqueNames.Add("John");
uniqueNames.Add("Jane");
uniqueNames.Add("John"); // Won't be added (duplicate)

// Stack<T>
Stack<int> stack = new Stack<int>();
stack.Push(1);
stack.Push(2);
int top = stack.Pop();

// Queue<T>
Queue<string> queue = new Queue<string>();
queue.Enqueue("First");
queue.Enqueue("Second");
string first = queue.Dequeue();

6. Object-Oriented Programming Basics

Classes and Objects

public class Person
{
    // Properties
    public string Name { get; set; }
    public int Age { get; set; }

    // Constructor
    public Person(string name, int age)
    {
        Name = name;
        Age = age;
    }

    // Method
    public void SayHello()
    {
        Console.WriteLine($"Hello, my name is {Name}");
    }
}

// Usage
Person person = new Person("John", 25);
person.SayHello();

Inheritance

// Base class
public class Animal
{
    public string Name { get; set; }

    public virtual void MakeSound()
    {
        Console.WriteLine("The animal makes a sound");
    }
}

// Derived class
public class Dog : Animal
{
    public string Breed { get; set; }

    public override void MakeSound()
    {
        Console.WriteLine($"{Name} barks: Woof! Woof!");
    }
}

Encapsulation

public class BankAccount
{
    private decimal balance;
    private string accountNumber;

    public string AccountNumber => accountNumber;
    public decimal Balance => balance;

    public void Deposit(decimal amount)
    {
        if (amount > 0)
        {
            balance += amount;
        }
    }

    public bool Withdraw(decimal amount)
    {
        if (amount > 0 && amount <= balance)
        {
            balance -= amount;
            return true;
        }
        return false;
    }
}

7. Exception Handling

Basic Exception Handling

try
{
    int result = 10 / 0;
}
catch (DivideByZeroException ex)
{
    Console.WriteLine("Cannot divide by zero!");
}
catch (Exception ex)
{
    Console.WriteLine($"An error occurred: {ex.Message}");
}
finally
{
    Console.WriteLine("This always executes");
}

Custom Exceptions

public class InsufficientFundsException : Exception
{
    public decimal Balance { get; }
    public decimal Amount { get; }

    public InsufficientFundsException(decimal balance, decimal amount)
        : base($"Insufficient funds. Balance: ${balance}, Attempted withdrawal: ${amount}")
    {
        Balance = balance;
        Amount = amount;
    }
}

8. File I/O Operations

Reading Files

// Read all text
string content = await File.ReadAllTextAsync("data.txt");

// Read all lines
string[] lines = await File.ReadAllLinesAsync("data.txt");

// Using StreamReader
using (StreamReader reader = new StreamReader("data.txt"))
{
    string line;
    while ((line = await reader.ReadLineAsync()) != null)
    {
        Console.WriteLine(line);
    }
}

Writing Files

// Write all text
await File.WriteAllTextAsync("output.txt", "Hello, World!");

// Append text
await File.AppendAllTextAsync("output.txt", "\nAppended line");

// Using StreamWriter
using (StreamWriter writer = new StreamWriter("output.txt"))
{
    await writer.WriteLineAsync("First line");
    await writer.WriteLineAsync("Second line");
}

9. LINQ (Language Integrated Query)

Basic LINQ Operations

List<int> numbers = new List<int> { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };

// Filtering
var evenNumbers = numbers.Where(n => n % 2 == 0);

// Projection
var squares = numbers.Select(n => n * n);

// Sorting
var sorted = numbers.OrderByDescending(n => n);

// Aggregation
int sum = numbers.Sum();
double average = numbers.Average();
int max = numbers.Max();

// Complex query
var result = numbers
    .Where(n => n > 5)
    .Select(n => n * 2)
    .OrderBy(n => n)
    .ToList();

Grouping and Joining

// Grouping
var grouped = numbers.GroupBy(n => n % 2 == 0 ? "Even" : "Odd");

// Joining
List<Customer> customers = new List<Customer>();
List<Order> orders = new List<Order>();

var customerOrders = from customer in customers
                     join order in orders on customer.Id equals order.CustomerId
                     select new { CustomerName = customer.Name, OrderAmount = order.Amount };

10. Delegates and Events

Delegates

// Delegate declaration
public delegate void MessageHandler(string message);

// Using built-in delegates
Action<string> action = message => Console.WriteLine(message);
Func<int, int, int> add = (a, b) => a + b;
Predicate<int> isEven = number => number % 2 == 0;

// Multicast delegate
Action<string> multiHandler = message => Console.WriteLine($"Handler 1: {message}");
multiHandler += message => Console.WriteLine($"Handler 2: {message}");

Events

public class Button
{
    public event EventHandler Clicked;

    public void Click()
    {
        Clicked?.Invoke(this, EventArgs.Empty);
    }
}

// Subscribing to events
Button button = new Button();
button.Clicked += (sender, e) => Console.WriteLine("Button clicked!");

11. Generics

Generic Classes and Methods

// Generic class
public class Container<T>
{
    private T value;

    public Container(T initialValue)
    {
        value = initialValue;
    }

    public T GetValue() => value;
    public void SetValue(T newValue) => value = newValue;
}

// Generic method
public static T GetDefault<T>()
{
    return default(T);
}

// Generic constraints
public class Calculator<T> where T : struct, IEquatable<T>, IComparable<T>
{
    public bool AreEqual(T first, T second) => first.Equals(second);
}

12. Asynchronous Programming

Async/Await Pattern

// Async method
public async Task<string> GetDataAsync()
{
    await Task.Delay(1000); // Simulate async work
    return "Data retrieved";
}

// Async method with return value
public async Task<int> GetNumberAsync()
{
    await Task.Delay(500);
    return 42;
}

// Calling async methods
public async Task Example()
{
    string data = await GetDataAsync();
    int number = await GetNumberAsync();
    Console.WriteLine($"Data: {data}, Number: {number}");
}

Concurrent Operations

// Running tasks in parallel
public async Task RunTasksInParallelAsync()
{
    Task<int> task1 = GetNumberAsync();
    Task<int> task2 = GetNumberAsync();
    Task<int> task3 = GetNumberAsync();

    int[] results = await Task.WhenAll(task1, task2, task3);
}

// Processing first completed task
public async Task ProcessFirstCompletedAsync()
{
    Task<string> fastTask = Task.FromResult("Fast result");
    Task<string> slowTask = Task.Run(async () => 
    {
        await Task.Delay(2000);
        return "Slow result";
    });

    Task<string> completedTask = await Task.WhenAny(fastTask, slowTask);
    string result = await completedTask;
}

13. Memory Management

IDisposable Pattern

public class ResourceManager : IDisposable
{
    private bool disposed = false;
    private FileStream fileStream;

    public ResourceManager(string filePath)
    {
        fileStream = new FileStream(filePath, FileMode.Open);
    }

    public void Dispose()
    {
        Dispose(true);
        GC.SuppressFinalize(this);
    }

    protected virtual void Dispose(bool disposing)
    {
        if (!disposed)
        {
            if (disposing)
            {
                fileStream?.Dispose();
            }
            disposed = true;
        }
    }
}

Using Statements

// Traditional using statement
using (var fileStream = new FileStream("data.txt", FileMode.Open))
{
    // Work with fileStream
} // Automatically disposed

// C# 8+ using declaration
using var fileStream = new FileStream("data.txt", FileMode.Open);
// Work with fileStream
// Automatically disposed at end of scope

14. Debugging Techniques

Debugging Attributes

using System.Diagnostics;

[DebuggerDisplay("Person: {Name} (Age: {Age})")]
public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
}

[DebuggerStepThrough]
public static string FormatString(string input)
{
    return input?.Trim().ToUpper();
}

Conditional Compilation

[Conditional("DEBUG")]
public static void Log(string message)
{
    Console.WriteLine($"[DEBUG] {DateTime.Now}: {message}");
}

public void ProcessData()
{
    Log("Starting data processing");
    // Process data
    Log("Data processing completed");
}

Best Practices Demonstrated

Consistent Naming: Use PascalCase for public members, camelCase for private members
Proper Disposal: Always dispose resources using using statements
Async All the Way: Don't mix synchronous and asynchronous code
Exception Handling: Catch specific exceptions before general ones
Null Safety: Check for null values before using objects
LINQ Efficiency: Filter early to reduce dataset size
Generic Constraints: Use appropriate constraints for type safety
Method Organization: Keep methods small and focused on single responsibilities

Next Steps

These code samples provide a foundation for understanding C# fundamentals. As you progress through the course, you'll build upon these concepts to create more complex applications. Refer back to these examples when you need a quick reminder of syntax or patterns.

Additional Resources

Planing Multi-Module Android Project 📝

Neeraj Sharma — Sat, 22 Feb 2025 17:07:57 +0000

Introduction

Hello, fellow developer! 🌟 Are you ready to take your Android projects to the next level? In this guide, we'll dive into the exciting world of multi-module projects in Android Studio, using Gradle and Kotlin. Multi-module projects are a fantastic way to keep your codebase organized and turbocharge your build times. By breaking your project into smaller, independent modules, you can build and test them more efficiently.

Join me on this journey as we explore how to plan your project structure, create modules, and configure dependencies between them. Let's get started and make your development process smoother and more enjoyable!

Before We Begin 🚀

This guide well help you:

✅ Understand why multi-module architecture is matters
✅ Learn how to plan before Modularizing your app
✅ How to use conventional plugin to reduce boilerplate gradle configiuration
✅ Master dependency management between modules
✅ Speed up your build times significantly

Why Multi-Module?

Picture this: You are working on an exciting android project everything in one neat module (just like I did when starting out).
Life seems simple, right? But then comes the testing phase..

The single module chanllenge 🎯

Let me share a real scenario that might sound familiar:

You write a brilliant piece of code 💻
you create a test for it 🧪
you hit the compile button.. and wait.. and wait.. ⌛
The entire project needs to compile just to test that one small component 😅.
Oh, and every tiny issue anywhere in the project needs to be fixed before you can run that test!.

The Multi-Module Approach 🚀

Breaking down your project into modules is like organizing a well-structured library. Each module serves a specific purpose and works together harmoniously, making your codebase cleaner, more maintainable, and easier to test.

Now again come back to the real world scenario

You write a brilliant piece of code 💻
you create a test for it 🧪
you hit the compile button.. and you just wait for the module to build, that contain your test target.
Now you don't need to care of every tiny issue in the other modules.

Common Reasons To Embracing The Multi-Module Architecture

Following are the common reasons to use multi-module projects:

Save build time: Gradle only builds the modules that have changed, which can significantly reduce build times.
Better code organization: Modules help you organize your codebase into logical units, making it easier to understand and maintain.
Separation of concerns: Each module can have its own responsibilities and dependencies, making it easier to test and maintain.
Reusability: Modules can be reused across different projects, reducing duplication and improving consistency.
Modular testing: Each module can be tested independently, making it easier to identify and fix issues.
Scalability: As your project grows, multi-module projects can help you scale your codebase more efficiently.
Collaboration: Multi-module projects can facilitate collaboration among developers by allowing them to work on different modules simultaneously.

Planning Your Project Structure

We must plain our project structure depending on the features and requirements of the application.
This is what where most of the beginner android developers struggle. Even if they are aware of the benefits of multi-module projects, they don't know how to plan their project structure. If you are one of them, Don't worry, I will help you with that. Trust me you are not alone I was also in the same situation too.

Consider a Note taking project with the following features:

Authentication: Users can sign up and log in to the app.
Notes: Users can create, edit, and delete notes.
Search: Users can search for notes by title or content.
Settings: Users can customize app settings.
Notifications: Users can receive notifications for new notes.
Backup and Restore: Users can backup and restore their notes.

Find Reasonable Parameters To Divide Your Project

You must think of reasonable parameters to divide the this example note taking app into modules.

The first parameter we can see is the feature. we can divide the project
by it's feature. For each feature, we would have a module. And an app module which use these feature modules and create a final app.

Furthermore, we can divide the each feature into modules based on the
Architecture layer.

Ui layer
Domain layer / Business Logic layer
Data layer
API layer

You can find valid reasons to divide your real project just give some time to think.

Initially thinking like this will give you a view of the Module Hierarchy
from top to down.

But a better way to think is to start from the bottom and work your way up.

You would definately need to build basic components like data repository and auth-apis before you can start building the Final working features like NoteEditor, LoginPage etc. So, you would need to start with the bottom layer and work your way up.

Thinking in both directions would help you get to a better decision.
In the next section, I will show you how to plan your project structure by visualizing the process
and forcing some dependency rules between modules.

Visualizing The Process Of Modularization

To make thought process easier, I am visualizing the process of modularization in the following diagram. By Stacking the modules in levels of dependency.

In this approach, I've created a stack of empty levels, where each level represents a position in the hierarchy. The key rule here is: each module at a lower level is open to use by modules above it, but not vice versa. This simple rule prevents cyclic dependencies between modules, which is a common issue in multi-module projects.

First we divided the project by features then we divided the features into different layers.
Now we can start filling the empty levels with modules depeding on the dependency among them.

Following is the final structure of the example note taking project.

API: The API module is responsible for making network requests and handling responses. If it becomes too complex, you can split it further into multiple modules as auth-api, note-api, etc. In the diagram, It sits on the bottom level and is available to all the modules above it. It will contain classes for data-transfer objects (DTOs) and network apis.

for example, It can have a NoteApi that makes network requests to the server and returns a list of notes.


interface NoteApi {
    suspend fun getNotes(): List<Note>
    suspend fun getNote(id: String): Note

    // save user note on server
    suspend fun uploadNotes(notes: List<Note>): Boolean
}

class NoteApiImpl(
    private val sessionToken: String,
    private val apiUrl: String,
) : NoteApi {
    ...
}

Data: The data module is responsible for storing and retrieving data.
It can have classes for data models (like Note, User, etc.) and local data storage.

for example, It can have a NoteDao that stores and retrieves notes from a local database.

interface NoteDao {
    @Query("SELECT * FROM notes")
    suspend fun getNotes(): List<Note>

    @Query("SELECT * FROM notes WHERE id = :id")
    suspend fun getNote(id: String): Note

    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertNote(note: Note)

    @Update
    suspend fun updateNote(note: Note)

    @Delete
    suspend fun deleteNote(note: Note)
}

Domain: The domain module is responsible for business logic.
It defines interfaces and classes for the business logic.
You could put UI-data models (like Note, User, etc.) in this module.
It is also responsible for mapping of data entities and network responses to the Ui data models.

For example, It provides a NoteService that provides methods for getting and saving notes locallly and remotely. It acts as a single source of truth for the notes data. It automatically syncs the local and remote data.

interface NoteService: NoteApi { 
    fun getNotes(): Flow<List<Note>>
    fun getNote(id: String): Flow<Note>
    suspend fun insertNote(note: Note)
    suspend fun updateNote(note: Note)
}

class NoteServiceImpl(
    private val mapper: Mapper,
    private val localNoteDao: NoteDao,
    private val remoteNoteApi: NoteApi,
    private val sessionToken: String,
) : NoteService {
    ... 
}

Core Features: This module contain the common components that are used by multiple features. For example, a common Ui component, a common business logic, etc.

You can also create UIKit Module on this level which contains common UI components like NotesCard, NoteEditor, CustomButtons, etc.

Features: Features modules are top-most modules in the hierarchy.
They are responsible for handling the user interactions and drawing the UI.
They can selectively use the modules from the below levels.

APP Module: The app module is the entry point of the application. It contains the main activity and combines all the features.

In this similar way, you can create a multi-module project for your Android application.

Conventional Plugin

Configuration of the Multiple Android Libraries is a very tedious task. Because each library is going to have an
android dsl block and some set of plugins like following.


plugins {
    alias(libs.plugins.android.library)
    alias(libs.kotlin.android)
    alias(libs.plugins.kotlin.serialization)
}

android {
    namespace = "com.example.mylibrary"
    compileSdk = 33
    defaultConfig {
        minSdk = 24
        targetSdk = 33
    }

    buildTypes {
        release {
            isMinifyEnabled = false
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    } 
}

dependencies {
    implementation(libs.kotlinx.serialization.json)
    ...
}

If you are not familiar with the version catalogs file (libs.versions.toml), you can refer to the official documentation here.

By using the conventional plugin, we could have common config logic which can reduce the boilerplate code and make the configuration of the libraries easier.

In the example NoteApp, we have multiple features like auth, notes, note-editor, etc. Let's say each feature is a android library, uses jetpack compose framework,
Jetpack Navigation, and uses kotlin serialization. This is what we found common
in all the features.

So, we can create a feature-lib plugin which can be applied to all the features and applies the common configuration to each sub-project.

Gradle buildSrc

Before writing the convention plugin, we need to be clear about the buildSrc directory in a gradle project.

The buildSrc directory in a Gradle project is a special directory that is used to build and maintain custom build logic, plugins, and dependencies that are used in the main project build. Gradle automatically compiles and includes the code in the buildSrc directory in the build script classpath, making it available to the main build scripts.

Create a new directory buildSrc in the root of your project.

my-project/
├── build.gradle
├── settings.gradle
├── buildSrc/ <-- Create this directory

Create a new Kotlin file build.gradle.kts in the buildSrc directory.

buildSrc is also a gradle project. So, we can create a build.gradle.kts file in the buildSrc directory.

plugins {
    `kotlin-dsl`
}

dependencies { 
    implementation(libs.kotlin.gradle.plugin)
    implementation(libs.android.gradle.plugin)
}

Also create a settings.gradle.kts file in the buildSrc directory.

import java.net.URI

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

dependencyResolutionManagement {

    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

    repositories {
        google()
        mavenCentral()
        mavenLocal()
        maven { url = URI("https://jitpack.io") }
    }

    versionCatalogs {
        create("libs") {
            from(files("../gradle/libs.versions.toml"))
        }
    }
}

Project Version Catalog

Define the following in the root-project/gradle/libs.versions.toml file.


[versions]
agp = "8.0.2" # android gradle plugin
kotlin = "2.0.21"
kotlinxSerializationJson = "1.7.3"
composeBom = "2024.12.01"


[plugins]
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

[libraries]
kotlinxSerializationJson = { 
    group = "org.jetbrains.kotlinx", 
    name = "kotlinx-serialization-json", 
    version.ref = "kotlinxSerializationJson" }
}

# Android Gradle Plugin as a dependency to buildSrc module. 
agp = { 
    group = "com.android.tools.build",
    name = "gradle",
    version.ref = "agp"
}

# Kotlin Gradle Plugin as a dependency to buildSrc module.
kotlinAGP = { 
    group = "org.jetbrains.kotlin.android",
    name = "org.jetbrains.kotlin.android.gradle.plugin",
    version.ref = "kotlin"
}

desugar_jdk_libs = {
 module = "com.android.tools:desugar_jdk_libs", 
 version.ref = "desugar_jdk_libs" 
}

# Compose dependencies
androidx-composeActivity = { module = "androidx.activity:activity-compose", version.ref = "activityCompose" }
androidx-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "ktx" }
androidx-lifecyle = { group = "androidx.lifecycle", name = "lifecycle-runtime-ktx", version.ref = "androidxLifeCycle" }
androidx-lifetimeRuntimeCompose = { module = "androidx.lifecycle:lifecycle-runtime-compose", version.ref = "androidxLifeCycle" }
androidx-composeBom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
androidx-composeUi = { module = "androidx.compose.ui:ui" }
androidx-composeFoundation = { module = "androidx.compose.foundation:foundation" }
androidx-material3 = { module = "androidx.compose.material3:material3", version.ref = "androidx_material3" }
androidx-composeUiToolingPreview = { module = "androidx.compose.ui:ui-tooling-preview" }
androidx-composeUiTooling = { module = "androidx.compose.ui:ui-tooling" }
androidx-compose-uiGraphics = { module = "androidx.compose.ui:ui-graphics" }
androidx-constraintlayout = { module = "androidx.constraintlayout:constraintlayout-compose", version.ref = "constraintlayout_compose" }
androidx-nav-compose = { group = "androidx.navigation", name = "navigation-compose", version = "2.8.5" }
androidx-paging-compose = { module = "androidx.paging:paging-compose", version.ref = "pagingCompose" }
androidx-ui-text-google-fonts = { module = "androidx.compose.ui:ui-text-google-fonts", version.ref = "uiTextGoogleFonts" }

[bundles]
compose-core = [
    "androidx-composeActivity",
    "androidx-composeBom",
    "androidx-composeUi",
    "androidx-composeFoundation",
    "androidx-material3",
    "androidx-compose-uiGraphics",
    "androidx-constraintlayout",
    "androidx-nav-compose",
    "androidx-paging-compose",
    "androidx-ui-text-google-fonts",
    "material-icons-core",
    "material-icons-extended",
]

compose-tooling = [
    "androidx-composeUiTooling",
    "androidx-composeUiToolingPreview"
]

Feature-Lib Plugin

Now it's time to create our feature-lib plugin. Create a new file feature-lib.gradle.kts in the buildSrc/src/main/kotlin directory.

Note: The feature-lib.gradle.kts file is called a Precompiled Gradle Script Plugin, Know more here.

import com.example.*

val libs = extensions.getByType<VersionCatalogsExtension>().named("libs")

// following plugins are applied to each project which uses this convention plugin
apply {
    plugin("android-lib")
    plugin(libs.findPlugin("compose-compiler").get().get().pluginId)
    plugin(libs.findPlugin("kotlinx-serialization").get().get().pluginId)
}

dependencies {
    implementation(libs.findBundle("compose-core").get())
    debugImplementation(libs.findBundle("compose-tooling").get())
}

Note that Code in the buildSrc/src can not use gradle dsl for version catalogs and dependency functions like implementation, api, testImplementation, etc.

The above code snippet clearly shows how to use version catalog in plugin the script.
And It imports the extensions for implementation, debugImplementation from the com.example package,

Also note that the above plugin script applies the another plugin convention plugin android-lib which I will create later.

DependencyHandler Extensions

The following are the DependencyHandler extensions that are used in the plugin-script
dependencies block. file: buildSrc/src/main/kotlin/com/example/DependenciesExt.kt

package com.example

import org.gradle.api.artifacts.dsl.DependencyHandler

fun DependencyHandler.implementation(dependencyNotation: Any) {
    add("implementation", dependencyNotation)
}
// debug implementation
fun DependencyHandler.debugImplementation(dependencyNotation: Any) {
    add("debugImplementation", dependencyNotation)
}

fun DependencyHandler.api(dependencyNotation: Any) {
    add("api", dependencyNotation)
}

fun DependencyHandler.compileOnly(dependencyNotation: Any) {
    add("compileOnly", dependencyNotation)
}

fun DependencyHandler.runtimeOnly(dependencyNotation: Any) {
    add("runtimeOnly", dependencyNotation)
}

fun DependencyHandler.testImplementation(dependencyNotation: Any) {
    add("testImplementation", dependencyNotation)
}

fun DependencyHandler.androidTestImplementation(dependencyNotation: Any) {
    add("androidTestImplementation", dependencyNotation)
}

fun DependencyHandler.kapt(dependencyNotation: Any) {
    add("kapt", dependencyNotation)
}

android-lib Plugin

Now it's time to create our android-lib plugin. Create a new file android-lib.gradle.kts in the buildSrc/src/main/kotlin/ directory.


import com.example.*
import com.android.build.gradle.LibraryExtension
import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

val libs = extensions.getByType<VersionCatalogsExtension>().named("libs")

// following plugins are applied to each project which uses this convention plugin
apply {
    plugin("com.android.library")
    plugin("org.jetbrains.kotlin.android")
}

// same as android block in gradle file
configure<LibraryExtension> {
    namespace = "com.example"
    compileSdk = 34
    defaultConfig {
        minSdk = 24
        lint.targetSdk = 34
    }
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

tasks.withType<KotlinCompile>().configureEach {
    compilerOptions {
        jvmTarget.set(JvmTarget.JVM_17)
    }
}

dependencies {
    coreLibraryDesugaring(libs.findLibrary("desugar_jdk_libs").get()) 
}

All the above code is pretty straightforward. We are applying the com.android.library and org.jetbrains.kotlin.android plugins. And we are configuring the android LibraryExtension. If you wish to create an android-app plugin, then you can use the com.android.application plugin instead of com.android.library. And you can configure the ApplicationExtension instead of LibraryExtension in the build.gradle.kts file.

Now we have common configurations for all the android libraries modules in our project.
According to your project requirements, you can create more plugins following the same pattern.

Using the Convention Plugin

To use the convention plugin, we need to apply the plugin in the build.gradle.kts file of the project.

plugins {
    id("feature-lib")
}

// you can optionally override the default 
// config applied by the feature-lib plugin
android {
    namespace = "com.example.notes"
}

dependencies {
    // you don't need to rewrite compose dependencies here
    // because the feature-lib plugin already applied the compose dependencies

    // only add the additional dependencies like
    implementation(libs.coil.compose)

    // add the dependencies to other modules like
    implementation(project(":auth"))
    implementation(project(":notes"))
}

Share Your Thoughts! 💭

Did this guide help you structure your Android project better? I'd love to hear your thoughts!

Drop a comment below about your experience
Share your own modularization tips and tricks
Let me know which topics you'd like me to cover next
Connect with other developers in our Telegram community

Your feedback helps make these guides even more valuable for the developer community. Let's learn and grow together! 🚀

Follow me on:

Telegram Channel for more Android development tips
GitHub for code examples and projects

This is it. I hope you find this guide helpful. Thanks for reading.
Give a feedback if you have any questions or suggestions.

Support My Work ☕

If you found this guide helpful and want to fuel more developer-focused content, consider buying me a coffee! Your support helps me create more in-depth tutorials and resources for the developer community.

Your coffee powers:

📝 More detailed technical guides
🎥 Tutorial videos
💡 Code examples and templates

How to create Previews of ViewModel-Dependent Composable in Jetpack Compose

Neeraj Sharma — Tue, 28 Jan 2025 12:30:22 +0000

Understanding the Problem

Let's understand the problem we face while creating previews of Viewmodel-dependent Composables.

Previews are lightweight and don't use the whole Android framework to render. Thus, previews have the following limitations

No network access
No file access
Some Context APIs may not be fully available

So the ViewModel that depends on the classes and features that are not available in the preview environment will fail to render with some exceptions.

Real-world scenario where we have a ViewModel-dependent Composable

Let's take an example of a UserProfile screen that fetches user details from a remote server.

ViewModel

The following is a simple ViewModel that fetches user details from a remote server.

class UserViewModel(
    private val userRepository: UserRepository
) : ViewModel() {
    private val _userState = MutableStateFlow<UserState>(UserState.Loading)
    val userState: StateFlow<UserState> = _userState.asStateFlow()

    fun fetchUserDetails(userId: String) {
        viewModelScope.launch {
            try {
                val user = userRepository.getUser(userId)
                _userState.value = UserState.Success(user)
            } catch (e: Exception) {
                _userState.value = UserState.Error(e.message ?: "Unknown error")
            }
        }
    }
}

Composabe that depends on the ViewModel

The following is a simple Composable that displays user details.

@Composable
fun UserProfile(
    viewModel: UserViewModel,
    userId: String
) {
    val userState by viewModel.userState.collectAsState()

    LaunchedEffect(userId) {
        viewModel.fetchUserDetails(userId)
    }

    when (userState) {
        is UserState.Loading -> {
            CircularProgressIndicator()
        }
        is UserState.Success -> {
            val user = (userState as UserState.Success).user
            Column(
                modifier = Modifier
                    .fillMaxWidth()
                    .padding(16.dp)
            ) {
                Text(
                    text = user.name,
                    style = MaterialTheme.typography.h5
                )
                Spacer(modifier = Modifier.height(8.dp))
                Text(
                    text = user.email,
                    style = MaterialTheme.typography.body1
                )
            }
        }
        is UserState.Error -> {
            Text(
                text = (userState as UserState.Error).message,
                color = MaterialTheme.colors.error
            )
        }
    }
}

Preview

The following shows the problem we would have while creating a preview for the above composable.

@Preview
@Composable
private fun UserProfilePreview() {
    UserProfile(
        viewModel = UserViewModel(
            userRepository = UserRepository()
        ), 
        userId = "123"
    )
}

UserRepository uses local and remote sources to fetch user details.
Neither the local nor remote source dependencies are available in the preview environment, so the preview will fail to render.

Solution

To Solve this issue we can mock the ViewModel or its dependencies with the kotlin Mockk library.
Kotlin mockk is a mocking library for kotlin which is used in unit testing. However, we could leverage the Mockk library to mock the Composable dependencies while creating the preview.

Even if ViewModel is a complex class with multiple dependencies, we can mock it easily by using the Mockk library.

Add Mockk to your project

Add the following dependency to your app's build.gradle file:

note: we use the debugImplementation scope to avoid adding the mockk library to the release build.

dependencies {  
  debugImplementation("io.mockk:mockk:1.13.13")  
}

For more details about Mockk library, check out the official documentation.

ProfileScreen Preview with Mocked ViewModel


@Preview
@Composable 
private fun UserProfilePreview() { 
    val mockViewModel = mockk<UserViewModel>()

    // Define what should be returned when the userState property is accessed
    val userState = remember { MutableStateFlow<UserState>(UserState.Loading) }

    every { mockViewModel.userState } returns userState

    // Define what should happen when the fetchUserDetails function is called
    every { mockViewModel.fetchUserDetails(any()) } answers {
        // give some delay to simulate a real API call
        delay(1000)

        // Simulate a successful API call
        userState.value = UserState.Success(User("John Doe", "john.doe@example.com"))
    } 

    UserProfile(
        viewModel = mockViewModel,
        userId = "123"
    )
}

That's it! Now, when you run the preview, the UserProfile composable will use the mocked UserViewModel. We mock the behaviour of the ViewModel to return a specific state and the behaviour of the fetchUserDetails function to simulate a successful API call.

Conclusion

In this post, we learned:

How to handle Jetpack Compose previews when dependencies are not available in the preview environment
Using MockK library to mock ViewModel and its dependencies in Compose previews
Adding MockK dependency specifically for debug builds using debugImplementation
Creating mock behaviours for ViewModel properties and functions
Simulating API calls and state changes in the preview environment

This approach allows us to create realistic previews of our Composables even when they depend on complex ViewModels or repositories, making the development process more efficient and reliable.

How do you open vs code ? 🧐

Neeraj Sharma — Thu, 12 Dec 2024 13:22:35 +0000

When I was a beginner, I used to open VsCode and then open the project by selecting the open folder option. Then, I navigated to the project folder in the file chooser and selected the project.

However as I became more experienced, I started using the terminal to open the project.

This is a small thing but it saves a lot of time and makes you feel like an experienced programmer 😎.

Using a terminal gives me a sense that I have control over my computer and I can do anything with it. It's like I am the boss of my computer 😂.

I know it's a small thing but it's the small things that make a big difference.

In this post, I'll share with you the different ways to open a project in vscode. I use the following ways to open vs code.

Using the terminal
Custom vs code explorer Context menu

Using the terminal

I use this method most of the time. For the terminal, I use Powershell because it's simple and powerful uses object-oriented commands and is cross-platform. Although you can use the built-in Windows PowerShell, the modern PowerShell has become a more focused tool by Microsoft. Know more about it here. You can download it from here

Setting up the terminal

Let's create a shortcut to launch the terminal.
Search the terminal in the start menu and right click on it and select open file location.

You'll find the shortcut to the terminal in the file explorer. Right-click on the shortcut and select properties. and then click on the shortcut key field and press the key you want to use as a shortcut key. I use ctrl + alt + t.

when done, click on apply and then ok.
Now you can open the terminal by pressing ctrl + alt + t.

Optionally you can create an env variable for your projects directory. This will make it easier to navigate to the project directory like so:

$env:Projects = "C:\Users\username\Projects"
code $env:Projects/MyProject

Create a Environment variable

You can create an environment variable for each terminal session by running the following command in the terminal:

[System.Environment]::SetEnvironmentVariable("Projects", "C:\Users\username\Projects", "User")

Custom context menu entry

We can also crete a custom context menu entry in the file explorer to open the project in vscode. This is useful when you want to open the project in vscode without using the terminal.

You might not see the VS Code option in the context menu. You can add it by following these steps:

Open the registry editor by pressing win + r and typing regedit and pressing enter.
Navigate to HKEY_CLASSES_ROOT\Directory\shell.
Right-click on the shell folder and select New > Key.
Name the key VS Code.
Right-click on the VS Code key and select New > Key.
Name the key command.
Right-click on the command key and select Modify.
Right-click on the VS Code and select New > String Value.
Name the string value to Icon and set the value data to "C:\Program Files\Microsoft VS Code\Code.exe".
In the value data field, type "C:\Program Files\Microsoft VS Code\Code.exe" "%1" and click OK.

Now you can open the project directory in vscode by right-clicking on the project directory and selecting VS Code.

The following video shows how to add the VS Code option in the context menu.

Conclusion

I hope you found this post helpful. If you have any questions or suggestions, feel free to comment your thoughts below.

Join Our Community

Stay connected and join our Telegram community for more tips and discussions!

Join the telegram community here and channel here.

Happy coding! 😎🚀

Part 3: Compiling the Protos and Setting up the gRPC server

Neeraj Sharma — Tue, 10 Dec 2024 03:48:16 +0000

Overview

In the previous part, we defined our gRPC service interface using Protocol Buffers. In this part, we'll compile the proto file to generate the service stubs and message types and also use the service reflection to make it easy to testing the service from the postman.

If you don't know about the postman, it is a popular API client that allows you to test APIs by sending requests and viewing responses. You can download it from here. Developers use Postman to test APIs, document APIs, monitor APIs, and share APIs with others. we can also use it to test our gRPC service.

Compiling the Protobuf
- Creating the build script
- Installing the protoc compiler
Integrate compiled gRPC stubs
Setup the server
Conclusion

Compiling the Protobuf

In rust we can write build scripts that are executed before the build process. We can use this to compile the proto file and generate the service stubs and message types. We will use the tonic-build crate to compile the proto file.

In the previous part, we created the proto_stub crate. Now we are going to work on this crate to compile the proto file. First, make sure to add the tonic-build crate to the build-dependencies section of the Cargo.toml file in the proto_stub crate.

file-path: proto_stub/Cargo.toml

[package]
    ...

[dependencies]
tonic.workspace = true
prost-types.workspace = true
prost.workspace = true

[build-dependencies]
tonic-build.workspace = true

In dependencies section, we added the tonic, prost-types, and prost crates and foreach crate we set the workspace flag to true. This flag is used to tell the cargo that the crate is a workspace crate and its version is defined in the workspace Cargo.toml file. Similarly We also added the tonic-build crate to the build-dependencies section.

tonic : The tonic crate is a gRPC library for Rust. It provides a client and server implementation for gRPC services. The tonic crate is built on top of the tokio crate, which is an asynchronous runtime for Rust.

prost-types : The prost-types crate provides the well-known types for the prost crate. The well-known types are the types defined by the protobuf standard. The prost crate is a Rust implementation of the Protocol Buffers serialization format.

prost : The prost crate is a Rust implementation of the Protocol Buffers serialization format. The prost crate is used to generate Rust code from the Protocol Buffers definitions.

Creating the build script

Now we need to create a build script to compile the proto file. Create a new file named build.rs in the proto_stub crate and add the following code to the file.

file-path: proto_stub/build.rs

use std::{error::Error, path::PathBuf};

fn main() -> Result<(), Box<dyn Error>> {
    let out_dir = PathBuf::from(std::env::var("OUT_DIR")?);

    tonic_build::configure()
        // compile_well_known_types will generate code for well known types like google.protobuf.Empty  
        // we can disable this if we use the prost-types crate, because i am using prost-types crate i will kept this disabled.
        // compile_well_known_types(true) 

        // file_descriptor_set_path will generate a file descriptor set in the output directory
        // this file will be used by the server to provide reflection
        .file_descriptor_set_path(out_dir.join("my_descriptor.bin"))
        .compile_protos(
            // the path to the main proto file to compile
            &["proto/authy/protobuf/main.proto"], 
            // the path to the directory containing the proto files dependencies
            // protobuf compiler will look for dependencies in this directory
            &["proto/authy/protobuf"], 
        )?;

    Ok(())
}

In the build script, we first get the output directory path using the std::env::var("OUT_DIR")? function. The output directory is where the generated code will be placed.

Next, we call the tonic_build::configure() function to configure the build process. We can pass various options to the configure() function to customize the build process. In this case, we are using the file_descriptor_set_path() function to generate a file descriptor set in the output directory. The file descriptor set is used by the server to provide reflection.

Finally, we call the compile_protos() function to compile the proto file. The compile_protos() function takes two arguments: the path to the main proto file to compile and the path to the directory containing the proto file dependencies.

Installing the protoc compiler

Now if you run the cargo build -p proto_stub command in the terminal, you will see build errors because we don't have the protoc compiler installed. We need to install the protoc compiler to compile the proto file.

In windows, you can install the protoc compiler by using chocolatey package manager. Run the following command in the terminal to install the protoc compiler.

choco install protoc

In linux, you can install the protoc compiler by running the sudo apt install protobuf-compiler command in the terminal. In mac, you can install the protoc compiler by running the brew install protobuf command in the terminal.

You can also download the protoc compiler from the official protobuf release page and add the path to the protoc compiler to the system environment variable.

After installing the protoc compiler, check the protoc compiler version by running the protoc --version command in the terminal. If the protoc compiler is installed correctly, you will see the protoc compiler version.

Now run the cargo build -p proto_stub command in the terminal. It will run the build script and compile the proto file to generate the service stubs and message types. And then build the proto_stub crate.

If the build is successful, you will see the generated code in the output target directory.
Because we are using cargo workspaces, the generated code will be placed in the target directory of the workspace root.

run this powershell command to find the generated code in the target directory.

Get-ChildItem -Path . -Recurse -Filter authy.protobuf.rs

Including the generated code to the proto_stub crate

Now we have the generated service stubs and message types in the output target directory.
Edit the lib.rs file as shown below to include the generated code.

file-path: proto_stub/src/lib.rs


// we have to define the namespace exactly as the proto file package name 
// in this case the package name is authy.protobuf so we have to define the namespace as authy::protobuf.

pub mod authy {
    pub mod protobuf {
        // include the generated code authy.protobuf.rs
        tonic::include_proto!("authy.protobuf");
        const FILE_DESCRIPTOR_SET : &[u8]= tonic::include_file_descriptor_set!("my_descriptor");
    }
}

In the code above, we define the namespace exactly as the proto file package name. In this case, the package name is authy.protobuf, so we define the namespace as authy::protobuf.

Setup the server

In authy crate, we will edit the main.rs module to setup the server and expose the service.
First add the following dependencies to the Cargo.toml file in the authy crate.

file-path: authy/Cargo.toml

[dependencies]
tokio.workspace = true 
tonic.workspace = true
tonic-reflection.workspace = true
serde.workspace = true

We need tonic::transport::Server::builder() to build the server and a service address to bind the server to a specific address. As service address we will use 0.0.0.0:50051. where 0.0.0.0 is the IP address of the server and 50051 is the port number.

file-path: authy/src/main.rs

// File descriptor set generated by the build script
use proto_stub::authy::protobuf::FILE_DESCRIPTOR_SET;

use std::{error::Error, net::SocketAddr};
use tonic::transport::Server;

// We use the #[tokio::main] attribute to define the main function as an asynchronous function. This allows us to use the tokio runtime to run asynchronous code.
#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // Parse the address from the address string
    let addr: SocketAddr = "0.0.0.0:50051".parse().unwrap();

    /*
    parse() on address string works because the SocketAddr type implements the FromStr trait. The parse() method is used to parse a string into a SocketAddr type and unwrap() is used to get the value from the Result type.
    */

    // Print message to the console
    println!("Running server on {addr}");

    /*
    We create a new server instance using the Server::builder() method. We then add a service to the server using the add_service() method. We configure the reflection service using the tonic_reflection::server::Builder::configure() method.
    We register the encoded file descriptor set using the register_encoded_file_descriptor_set() method. Finally, we build the server using the build_v1alpha() method and serve it on the specified address using the serve() method. We use the await keyword to wait for the server to start serving requests.
    */
    Server::builder()
        .add_service(
            tonic_reflection::server::Builder::configure()
                .register_encoded_file_descriptor_set(FILE_DESCRIPTOR_SET)
                .build_v1alpha()?,
        )
        .serve(addr)
        .await?;

    Ok(())
}

Now open the terminal and run the cargo run -p authy command. It will start the server and print the message Running server on 50051 to the console.

You can use the postman to test the reflection service. Open the postman and click on new and and select the gRPC request type as shown in the image below.

In the request URL, enter the server address grpc:\\localhost:50051.
Now click on the next text box and select the Use Server Reflection in the popup menu and you will see the available services and methods in the server as shown in the image below.

If you are seeing the available services and methods in the server, then the reflection service is working correctly.

You can select one of the services and methods and send a request to the server to test the service it will return the unimplemented error because we haven't implemented the service yet.

Other tools like BloomRPC, grpcurl, grpcui, grpc-web, etc. can also be used to test the gRPC service. You can use any of these tools to test the gRPC service. However, these tools are not in the scope of this series.

Conclusion

In this part, we compiled the proto file to generate the service stubs and message types. We also used the service reflection to make it easy to test the service from Postman. In the next part, we will implement the service and client to authenticate the user using the gRPC service.

Part 2: Defining the Authentication gRPC Interface

Neeraj Sharma — Wed, 04 Dec 2024 17:53:03 +0000

Introduction

In the previous part, we set up our project structure. Now we'll define our gRPC service interface using Protocol Buffers. This interface will serve as the contract between our client and server.

Defining the authentication proto.
- Service Definition
- OTP Challenge Messages
- OTP Confirmation Messages
- Sign Up Messages
- Sign In Messages
- User Message Type

Defining the Protobuf Scheme

In the previous part, we set up our project structure. Now we'll define our gRPC service interface using Protocol Buffers. This interface will serve as the contract between our client and server.

Service Definition

First, let's create our main.proto file. This file will contain all our service and message definitions.

Location: proto_stub/proto/authy/protobuf/main.proto


syntax = "proto3";
package authy.protobuf;

import "google/protobuf/timestamp.proto";

service AuthService {
    rpc CreateOtpChallenge(CreateOtpChallengeRequest) returns (CreateOtpChallengeResponse);
    rpc ConfirmOtp(ConfirmOtpRequest) returns (ConfirmOtpResponse);

    rpc SignUp(SignUpRequest) returns (SignUpResponse);
    rpc SignIn(SignInRequest) returns (SignInResponse);
}

The main.proto file defines the AuthService service with the following methods:

CreateOtpChallenge: This method creates an OTP challenge for the user to verify their email address. The method takes a CreateOtpChallengeRequest message as input and returns a CreateOtpChallengeResponse message as output.
ConfirmOtp: This method confirms the OTP challenge for the user to verify their email address. The method takes a ConfirmOtpRequest message as input and returns a ConfirmOtpResponse message as output.
SignUp: This method registers a new user account. The method takes a SignUpRequest message as input and returns a SignUpResponse message as output.
SignIn: This method signs in a user account. The method takes a SignInRequest message as input and returns a SignInResponse message as output.

OTP Challenge Messages

Now let's define the CreateOtpChallengeRequest and CreateOtpChallengeResponse message types.

message CreateOtpChallengeRequest {
    string email = 1;
    ActionPurpose action_purpose = 2;

    enum ActionPurpose {
        SIGN_UP = 0;
        SIGN_IN = 1; // sign in via otp
        RESET_PASSWORD = 2;
    }
}

message CreateOtpChallengeResponse {
    string challenge_token = 1;
}

The CreateOtpChallengeRequest message type defines the fields for creating an OTP challenge. The message contains the following fields:

email: The user's email address.
action_purpose: The purpose of the action that requres the two factor auth via otp, such as signing up, signing in, or resetting the password. The ActionPurpose enum defines the possible values for the action purpose.

The CreateOtpChallengeResponse message type defines the fields for the OTP challenge response. The message contains the challenge token that the user will use to verify their email address.

OTP Confirmation Messages

Now let's define the ConfirmOtpRequest and ConfirmOtpResponse message types.

message ConfirmOtpRequest {
    string challenge_token = 1;
    string otp_code = 2;
}

message ConfirmOtpResponse {
    bool success = 1;
    string message = 2;
    optional string action_token = 3;
    Error error = 4;

    enum Error  {
        INVALID_OTP = 0;
        EXPIRED_OTP = 1;
        MAX_ATTEMPTS_REACHED = 2;
    }
}

The ConfirmOtpRequest message type defines the fields for confirming the OTP challenge. The message accepts the challenge token and the OTP code that the user submits to verify their email address.

The ConfirmOtpResponse message type defines the fields for the ConfirmOtp response. The message contains the success status, message, action token, and error type. The Error enum defines the possible error types for the OTP verification process. The error types include INVALID_OTP, EXPIRED_OTP, and MAX_ATTEMPTS_REACHED.

Sign Up Messages

Now let's define the SignUpRequest and SignUpResponse message types.

message SignUpRequest {
    string email = 1;
    string username = 2;
    string password = 3;
    string fullname = 4;
    string gender = 5;
    google.protobuf.Timestamp birthdate = 6;
    string action_token = 7;
}

message SignUpResponse {
    bool success = 1;
    string message = 2;
    optional string session_token = 3;
    Error error = 4;
    User user = 5;

    enum Error {
        INVALID_ACTION_TOKEN = 0;
        EMAIL_ALREADY_EXISTS = 1;
        USERNAME_ALREADY_EXISTS = 2;
    }
}

The SignUpRequest message type defines the fields for registering a new user account. The message contains the fields for user's username and password, and basic information of the user and a action token which is required for the user to perform the signup action.

The SignUpResponse message type defines the fields for the SignUp response. The message contains the success status, message, session_token, user message type that describe the current signin user. and error type. The Error enum defines the possible error types for the SignUp process. The error types include INVALID_ACTION_TOKEN, EMAIL_ALREADY_EXISTS, and USERNAME_ALREADY_EXISTS. session token is optional and might be none in case of error.

Sign In Messages

Now let's define the SignInRequest and SignInResponse message types.

message SignInRequest {
    oneof signInBy { 
        string email = 1;
        string username = 2;
        string action_token = 4;
    }
    optional string password = 3;
}

message SignInResponse {
    bool success = 1;
    string sessin_token = 2;
    string message = 3;
    optional User user = 4;
    Error error = 5;

    enum Error {
        INVALID_CREDENTIALS = 0;
        INVALID_ACTION_TOKEN = 1;
    }
}

The SignInRequest message type defines the fields for signing in a user account. User can sign in using email or username or via otp so we have defined oneof field for the same. oneof field is used to define a field that can have only one value from a set of fields.

Next we have password field which is required for the user to sign in with email or username. This field is optional and might be none in case of sign in via otp.

The SignInResponse message type defines the fields for the SignIn response. The message contains the success status, message, session_token, user message type that describe the current signin user. and error type. The Error enum defines the possible error types for the SignIn process. The error types include INVALID_CREDENTIALS, INVALID_ACTION_TOKEN.

User Message Type

Also, defines the User message type that contains the user information. This message type will be used to return the user information in the SignUp and SignIn responses with session token.
Note that we are using the google.protobuf.Timestamp type for the birthdate and created_at fields. So don't forget to import the timestamp.proto file at the top of the main.proto file.

message User {
    string username = 1;
    string email = 2;
    string fullname = 3;
    string gender = 4;
    google.protobuf.Timestamp birthdate = 5;
    google.protobuf.Timestamp created_at = 6;
}

So far, we have defined the proto file for the authentication service with the service methods and message types. In the next part, we will write the build.rs script to generate the Rust code from the proto file using the tonic-build crate.

See you in the next part. Happy coding! 🚀

Part 1: How to build Auth API in Rust using gRPC

Neeraj Sharma — Wed, 04 Sep 2024 09:41:29 +0000

Introduction

Welcome to the first part of our comprehensive guide on building an authentication API in Rust using gRPC! In this series, we will walk you through the process of creating a robust and secure authentication system from scratch. Whether you are a seasoned Rustacean or new to the language, this tutorial is designed to help you understand and implement key concepts in authentication, gRPC, and secure communication.

By the end of this series, you will have a fully functional authentication API that supports user registration, login, password reset, and OTP verification. We will leverage powerful libraries such as tonic for gRPC, jsonwebtoken for JWT handling, and MongoDB for data storage. Let's embark on this exciting journey to master authentication in Rust!

Overview of the Project
Features
Project Structure
Creating the Project

Overview of the Project

The basic idea of authentication is to verify the identity of a user. This process involves validating the user's credentials, such as a username and password, to determine if they are who they claim to be. In this tutorial, we will build an authentication API in Rust using the gRPC protocol. The API will handle user registration, login, password reset, and OTP verification. We will use JWT tokens for authentication and secure passwords with salting.

Registering a new account and resetting passwords will require the user to verify their email address. The client will request an OTP code, and the server will send the OTP code to the user's email address. The user will then submit the OTP code to verify their email address. Upon confirmation of the email address, the user will be permitted to perform the action.

We'll also need to store the user information. For this, we will use a NoSQL database, MongoDB, and for the gRPC server, we will use the tonic library.

We will make use of the json web token (JWT) for authentication. JWT is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.

You can know more about JWT here.

We will use HMAC SHA-256 for signing the JWT token. HMAC SHA-256 is a cryptographic hash function that produces a fixed-size output (256 bits) for a given input. It is a secure way to verify the integrity and authenticity of the data.
This algorithm used a single key for both signing and verifying the token. In this project the key will be known only to the server. So the server can verify the token and also generate the token. This approach guarantees that the tokens cannot be tampered with or forged by unauthorized parties. By using JWT tokens as session tokens, we can confidently ensure secure and reliable user authentication.

Features

User SignUp and SignIn
Password reset
OTP verification
Securing password with PASSWORD_SALTING

Project Structure

The project will be organized into the following modules:

authy: The authentication service crate that handles user registration, login, and password reset.
proto_stub: The gRPC service definition creat that defines the service methods and message types.
security: The security crate that provides functionality for generating and verifying JWT tokens, salting passwords, and OTP verification.
database: The database crate that provides functionality for interacting with the database.

The following defines the project structure:

├── authy
│   ├── src
│   └── Cargo.toml
├── proto_stub
│   ├── proto
│   │   └── authy
│   │       └── protobuf
│   │           └── main.proto
│   ├── src
│   ├── build.rs
│   └── Cargo.toml
├── security
│   ├── src
│   └── Cargo.toml
├── database
│   ├── src
│   └── Cargo.toml
├── .gitignore
├── Cargo.lock
└── Cargo.toml

Creating the Project

Splitting the project into multiple crates allows us to separate concerns and keep the codebase organized. This would also make it easier to test and maintain the code. Because of this, we are going to use cargo workspace for this project.

Create a new project and open it in Visual Studio Code. Also, delete the src directory in the root of the project.

cargo new auth_api && cd auth_api && rm -r src && code .

Now edit the Cargo.toml file in the root of the project and add the following code:

# /Cargo.toml

[workspace]
members = []

[workspace.dependencies]

tokio = { version = "1.0", features = ["full"] }
tonic = "0.12.3"
tonic-reflection = "0.12.3"
prost = "0.13.3"
prost-types = "0.13.3"
jsonwebtoken = "9.3.0"
chrono = {  version = "0.4.38", features = ["serde"] }
serde = { version = "1.0.215", features = ["derive"] }

Now the Cargo.toml (also called as virtual manifest in this case) file in the root basically defines a workspace rather than a package. The members field lists the crates that are part of the workspace. The workspace.dependencies field is used to define dependencies that are shared across all crates in the workspace. Initially, we don't have any crates in the workspace, so we will leave the members field empty.

But we have defined the dependencies that are shared across all crates in the workspace. The tokio crate is used for asynchronous programming, tonic is used for gRPC, tonic-reflection is used for gRPC reflection, prost and prost-types are used for protocol buffer serialization, jsonwebtoken is used for JWT token generation and verification, chrono is used for date and time manipulation, and serde is used for serialization and deserialization.

Now let's create the authy, proto_stub, security, and database crates. Run the following commands to create the crates:

cargo new authy --bin && 
cargo new proto_stub --lib && 
cargo new security --lib && 
cargo new database --lib

authy is the main crate that will contain the authentication service implementation. proto_stub is the crate that will contain the gRPC service definition and it will compile the proto file and expose them to authy. security is the crate that will contain the security implementation like generating and verifying JWT tokens, salting passwords, and OTP verification. database is the crate that will contain the database implementation.

Now your virtual manifest should have member packages like this:

# /Cargo.toml
[workspace]
members = [
    "authy",
    "proto_stub",
    "security",
    "database"
]

[workspace.dependencies]
 # common dependencies for sub-crates

Now we have set up the project structure and dependencies.
You can now run the following command to build the project:

cargo build

And to build the specif crate you can run the following command:

cargo build -p authy

replace authy with the crate name you want to build.

Conclusion

In this part of the tutorial, we have successfully set up the initial project structure and defined the necessary dependencies for our authentication API. By creating separate sub-crates for different functionalities, we have ensured that our codebase remains organized and maintainable. This modular approach will make it easier to test and extend the project in the future.

In the next part of the tutorial, we will focus on defining the gRPC service methods and message types in the proto file. We will also write the build.rs script to compile the protobuf definitions and generate the Rust stubs for our server. This will lay the groundwork for implementing the core functionality of our authentication service. Stay tuned for more detailed steps and explanations!

If you have any questions or feedback, feel free to leave a comment below. I'll be happy to help you out. Stay tuned for the next part of the tutorial!