Software development is not only about delivering functionality it is about delivering maintainable, scalable, and testable solutions. Even in small applications or single-feature projects like a patient lookup, poor design decisions can lead to tight coupling, duplication, and fragile code that is difficult to evolve.

The goal is to try and demonstrate how to take a simple use case retrieving a patient by ID from a SQL Server database and wrap it in a SOLID-compliant architecture using ASP.NET Core. The goal is to illustrate how enterprise-quality design is not just for complex systems. It brings clarity, reliability, and extensibility to any codebase, regardless of size.

By isolating responsibilities into Models, Repositories, Services, and Web UI layers, you can ensure the system remains:

• Easy to understand and reason about

• Simple to test and mock

• Safe to extend or refactor

• Well-suited to real-world business logic growth

Even if the system starts small, this approach sets a strong foundation that avoids rewrites and future technical debt. It is not about overengineering, but about applying clean architectural principles from the beginning when they are cheapest and most effective to implement.

Goals

• Clean separation of concerns using N-Tier Architecture

• Full adherence to the SOLID principles

• Use of Dependency Injection, async patterns, and stored procedures

• A minimal but functional Web API and Razor Page frontend

• Centralized configuration and clean routing

• A project structure that scales with growth

Recommended Solution Structure
This solution is organized into the following projects:

PatientLookupSolution
├── PatientLookup.Models // Plain old class object
├── PatientLookup.Repositories // SQL logic and ADO.NET (SqlDataClient)
├── PatientLookup.Services // Business logic
└── PatientLookup.Web // API and Razor UI

Each layer only depends on the one below it:

• Web depends on Services

• Services depends on Repositories

• Repositories depends on Models This architecture ensures modularity, testability, and scalability.

SOLID Breakdown
Single Responsibility: Each class serves a single purpose: controller, service, repository, etc.
Open/Closed: You can extend behaviors (e.g., new services) without modifying existing code.
Liskov Substitution: Interfaces are respected; substituting mock services or test repositories is safe.
Interface Segregation: Interfaces are focused (e.g., IPatientService only exposes needed methods).
Dependency Inversion: Higher layers depend on abstractions (IPatientRepository), not implementations.

Code Walkthrough
Patient.cs (Model Layer)

namespace PatientLookup.Models
{
  public class Patient
  {
    public int Id { get; set; }
    public string FirstName { get; set; } = string.Empty;
    public string LastName { get; set; } = string.Empty;
  }
}

• Just a normal class, no attributes describing infrastructure concerns or other responsibilities

• No data annotations to keep the model agnostic of UI or DB layers.

IPatientRepository
This is the part of the application responsible for talking directly to the database in a controlled and consistent way. It defines the contract for how the rest of the system can ask for patient data without needing to know how that data is actually retrieved.

public interface IPatientRepository
{
  Task<Patient?> GetByIdAsync(int id);
}

Basically it tells the system: "If you give me a patientId, I will return the matching Patient object asynchronously."

But it does not say how it does that. The actual logic of running the stored procedure and mapping the SQL result to a model is handled in the class that implements the IPatientRepository public interface (PatientRepository).

IPatientRepository defines a clear boundary between the application and the data layer. It is a small piece with a big impact when it comes to keeping the code clean, testable, and future-proof.

PatientRepository (Repository Layer)
PatientRepository is the implementation of IPatientRepository. It contains the actual logic for accessing the database by calling a stored procedure to fetch patient data. It focuses only on fetching data. No business logic. No UI code. This keeps the data layer clean, testable, and easy to change without breaking the rest of the system.

public class PatientRepository : IPatientRepository
{
  private readonly string _connectionString;

  public PatientRepository(IConfiguration config)
  {
    _connectionString = config.GetConnectionString("DefaultConnection")
      ?? throw new InvalidOperationException("Missing DefaultConnection string.");
  }

  public async Task<Patient?> GetByIdAsync(int id)
  {
    using var conn = new SqlConnection(_connectionString);
    using var cmd = new SqlCommand("cp_GetPatientById", conn)
    {
      CommandType = CommandType.StoredProcedure
    };
    cmd.Parameters.AddWithValue("@patid", id);
    await conn.OpenAsync();

    using var reader = await cmd.ExecuteReaderAsync();
    if (await reader.ReadAsync())
    {
      return new Patient
      {
        Id = reader.GetInt32(reader.GetOrdinal("Id")),
        FirstName = reader.GetString(reader.GetOrdinal("FirstName")),
        LastName = reader.GetString(reader.GetOrdinal("LastName"))
      };
    }

    return null;
  }
}

• Uses ADO.NET for performance and transparency.

• Clean separation from business logic.

• Uses a stored procedure for optimized and secure DB access.

IPatientService
IPatientService defines the business-facing contract for how the application can retrieve patient information. It sits above the repository and lets higher layers (like the controller) request patient data without knowing anything about the data source. This abstraction makes the service layer testable, swappable, and cleanly separated from the database layer.

public interface IPatientService
{
  Task<Patient?> GetPatientByIdAsync(int id);
}

• Acts as the middleman between the controller and the data layer, handling patient-related business logic.

• Offers a simple async method "GetPatientByIdAsync" to fetch a patient by their ID.

PatientService (Service Layer)
PatientService is the implementation of IPatientService. It calls the repository to fetch data and can apply business rules, validation, logging, or transformations before returning the result. Basically, it acts as a bridge between the controller and the repository cleanly separating concerns and centralizing any logic beyond raw data access.

public class PatientService : IPatientService
{
  private readonly IPatientRepository _repository;

  public PatientService(IPatientRepository repository)
  {
    _repository = repository;
  }

  public Task<Patient?> GetPatientByIdAsync(int id)
  {
    return _repository.GetByIdAsync(id);
  }
}

PatientController (Web API Layer)
PatientController is the entry point of the application. It handles incoming HTTP requests, delegates work to the service layer, and returns appropriate responses (usually JSON or a view). In this case, it returns the response to a view.

[Route("api/[controller]")]
[ApiController]
public class PatientController : ControllerBase
{
  private readonly IPatientService _service;

  public PatientController(IPatientService service)
  {
    _service = service;
  }

  [HttpGet("{id}")]
  public async Task<IActionResult> GetPatient(int id)
  {
    var patient = await _service.GetPatientByIdAsync(id);
    if (patient == null)
      return NotFound();

    return Ok(patient);
  }
}

• Validates incoming requests at a high level (e.g., route-level).

• Delegates the actual logic to the service layer.

• Returns a clean HTTP response (200 OK, 404 Not Found, etc.).

• It does not contain business or data logic.

• Minimal and clean controller.

• Relies only on the service interface.

Razor Page: PatientView.cshtml

@page
@model PatientLookup.Web.Pages.PatientViewModel
@{
  ViewData["Title"] = "Patient Details";
}
<h2>Patient Details</h2>
@if (Model.Patient != null)
{
  <div>
    <strong>ID:</strong> @Model.Patient.Id<br />
    <strong>Name:</strong> @Model.Patient.FirstName @Model.Patient.LastName
        </div>
}
else
{
  <div>Patient not found.</div>
}

Code-Behind: PatientView.cshtml

public class PatientViewModel : PageModel
{
  private readonly IPatientService _service;

  public PatientViewModel(IPatientService service)
  {
    _service = service;
  }

  [BindProperty(SupportsGet = true)]
  public int Id { get; set; }

  public Patient? Patient { get; set; }

  public async Task<IActionResult> OnGetAsync()
  {
    Patient = await _service.GetPatientByIdAsync(Id);
    return Patient == null ? NotFound() : Page();
  }
}

• Clean and simple frontend view.

• Demonstrates reuse of business logic via dependency injection in Razor Pages.

Program.cs
Program.cs is the glue that connects and configures all the architectural layers at startup. It is the application entry point in ASP.NET Core and configures the web host, registers services for dependency injection, defines how the application will run, etc.

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using PatientLookup.Repositories;
using PatientLookup.Services;
using System.Data;
using System.Data.SqlClient;

var builder = WebApplication.CreateBuilder(args);

// Load configuration
builder.Configuration.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true);

// Register controllers and framework services
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// Register custom services and repositories
builder.Services.AddScoped<IPatientRepository, PatientRepository>();
builder.Services.AddScoped<IPatientService, PatientService>();

// Register SQL connection for dependency injection
builder.Services.AddScoped<IDbConnection>(sp =>
  new SqlConnection(builder.Configuration.GetConnectionString("DefaultConnection")));

var app = builder.Build();

app.UseHttpsRedirection();
app.UseAuthorization();

app.MapControllers();
app.Run();

appsettings.json (environment based configuration)

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=SQLServer;Database=YourDb;Trusted_Connection=True;"
  }
}

Best Practice Highlights

• Use Stored Procedures: More secure, better for performance.

• Separation of Concerns: Data, business, and presentation logic are isolated.

• Thin Controllers: Controllers delegate logic to services.

• Interface-Driven Design: Easily testable and extensible.

• Async Everywhere: Improves scalability.

How all the Layers Work Together
This architecture separates responsibilities across four key layers, each with a clear purpose:

1. Controller Layer
   Responsibility: Handles HTTP requests and returns responses.
   Example: PatientController
   Accepts GET /api/patient/123
   Calls IPatientService.GetPatientAsync(123)
   Returns 200 OK with the patient object or 404 Not Found

2. Service Layer
   Responsibility: Contains business logic and orchestrates data access.
   Example: PatientService
   Validates input (e.g., patientId > 0)
   Calls repository: IPatientRepository.GetPatientByIdAsync()
   Applies any business rules before returning data

3. Repository Layer
   Responsibility: Communicates with the database (via stored procedures or queries).
   Example: PatientRepository
   Executes cp_APIGetPatientById
   Maps SqlDataReader result to a Patient model
   Returns the data to the service layer

4. Model Layer
   Responsibility: Defines the shape of your data objects.
   Example: Patient class
   Represents patient data across layers
   Keeps your code strongly typed and structured

Separation of Concerns: Each layer does one thing and does it well
Testability: You can mock or stub any layer during unit testing
Maintainability: Changes in one layer (e.g., database schema) do not break the rest
Scalability: Easily extend logic (e.g., add caching or logging) without disrupting the design

Conclusion
This example illustrates how clean, scalable architecture is not limited to large enterprise projects. By applying the SOLID principles, structuring with layered boundaries, and embracing clean code practices, you create software that is:

• Easy to maintain

• Easy to extend

• Easier to onboard new developers

• Ready for scaling into production

if (!model.patienId!.HasValue || (int)model.patienId! == 0)
{ return new ContentResult() { Content = "patienId is a required parameter", StatusCode = 400 }; }

if (string.IsNullOrEmpty(model.ndcnumber))
{ return new ContentResult() { Content = "ndcnumber is a required parameter", StatusCode = 400 }; }

if (!model.qty!.HasValue || (int)model.qty! <= 0) 
{ return new ContentResult() { Content = "qty is a required parameter", StatusCode = 400 }; }

// ... and so on for every field

This approach worked well for what I was doing at the time, but it became messy very quickly, especially as I added more fields and repeated the same pattern in multiple actions and across different controllers. It was hard to read, error-prone to update, and encouraged copy/paste over clean reuse.

To clean this up, I decided to refactor the common validation checks into a dedicated "ValidationHelper" class. This utility would let me validate nullable value types and strings in a reusable and centralized way.

In this post, I show a simple refactor I made to clean up these types of repetitive validation "if" statements in my controller actions by introducing a lightweight ValidationHelper. The result is clearer code, consistent error handling, and much better maintainability.

Refactoring with a Validation Helper
Basically, a helper class is a fancy way to describe a separate CS file where I put reusable code like small utility functions that I can call from my controllers (or anywhere else). It keeps things clean and avoids repeating the same logic in every method. So, instead of cluttering my controllers with repetitive checks (like verifying required fields), I just put those checks in a helper class and call them as needed. It makes the code easier to read and maintain.

This helper lives in its own file under the "/Helpers/ValidationHelper.cs" folder, and I keep it in the shared "MyAPI.Helpers" namespace.

// simple helper method for validating required model fields in ASP.NET Core controllers.
public static class ValidationHelper
{
  // Validate a nullable value type is not null and not its default value (e.g., 0 for int, false for bool).
  // <typeparam name="T">A struct type (e.g., int, bool, DateTime).</typeparam>
  // <param name="value">The value to validate.</param>
  // <param name="name">The name of the parameter (used in the error message).</param>
  // Returns ContentResult with a 400 status if the value is missing or default; otherwise, null.
  public static ContentResult? Required<T>(T? value, string name) where T : struct
  {
    // Check if the value is null or equals the default value for its type (e.g., 0 for int).
    if (!value.HasValue || EqualityComparer<T>.Default.Equals(value.Value, default))
    {
      return new ContentResult
      {
        Content = $"{name} is a required parameter",
        StatusCode = 400
      };
    }

    // If valid, return null to indicate no validation error.
    return null;
  }

  // Validate a string is not null, empty, or whitespace.
  // <param name="value">The string value to validate.</param>
  // <param name="name">The name of the parameter (used in the error message).</param>
  // Returns ContentResult with a 400 status if the string is null or empty; otherwise, null.
  public static ContentResult? Required(string? value, string name)
  {
    // Check if the string is null, empty, or whitespace-only.
    if (string.IsNullOrWhiteSpace(value))
    {
      return new ContentResult
      {
        Content = $"{name} is a required parameter",
        StatusCode = 400
      };
    }

    // If valid, return null to indicate no validation error.
    return null;
  }
}

A Sample of My Model

public class MySampleModel
{
  [Required] public int? patientId { get; set; }
  [Required] public string? ndcnumber { get; set; } = string.Empty;
  [Required] public int? qty { get; set; }
}

Sample Usage in my Controller
Now, instead of repeating lots of "if" validation logic in every action I simply do something like this:

[ApiController]
[Route("[controller]")]
public class MyController : ControllerBase
{
  private ContentResult? _validationResult;

  [HttpPost("DoSomethingEndpoint")]
  public IActionResult DoSomethingEndpoint([FromBody] MySampleModel model)
  {
    // Use ValidationHelper to check required fields
    if ((_validationResult = ValidationHelper.Required(model.patientId, "patientId")) != null) return _validationResult;
    if ((_validationResult = ValidationHelper.Required(model.ndcnumber, "ndcnumber")) != null) return _validationResult;
    if ((_validationResult = ValidationHelper.Required(model.qty, "qty")) != null) return _validationResult;

    // if all fields are valid, proceed with processing
    return Ok("Request accepted");
  }
}

Controller-Wide Result Field
To avoid declaring the same "ContentResult? result;" variable in every action, I made it a private field on the controller, like this:
private ContentResult? _validationResult;

Then I reused it across all of my methods.
if ((_validationResult = ValidationHelper.Required(model.qty, "qty")) != null) return _validationResult;
Because ASP.NET Core creates a new instance of the controller per request, this pattern is safe and avoids unnecessary duplication while keeping the logic tight and readable.

Why This Is Better
Switching to a helper-based approach gave me several benefits:
• Cleaner, reusable validation logic. the core logic lives in one place and is reused everywhere
• Consistent error formatting, validation lines are short, clear, and consistent
• Easier maintenance. Changes to the validation rules only require updates in one spot. Easy to extend and apply to other models.
• Cleaner controller actions. No external validation libraries required

Conclusion
This refactor started as a way to clean up clutter in a single action, but it quickly became a general pattern I now apply across my API projects.

Also, for more complex validation rules, like conditional logic (e.g., field B is required if field A is X) I can simply extend this pattern or supplement it with FluentValidation. If you're writing the same validation statements over and over, give a helper like this a try. It might be all you need to make your codebase more elegant and maintainable.

While this pattern is helpful for POST or PUT endpoints where the client is sending data, it is not intended for GET requests. In GET requests the input should remain as route or query parameters and not the request body.

Sounds simple, right? But in practice, ASP.NET Core’s model binding and validation pipeline is not designed to easily accept both [FromBody] and [FromQuery] inputs for the same model. You typically need to choose one source of input (not both).

In this write-up I go through a (relatively) reusable way to support both input models without introducing unnecessary complexity or breaking existing client functionality.

Objective
Allow my ASP.NET Web API POST/PUT endpoints to accept parameters either through:
• JSON body (using [FromBody])
• Query string (using [FromQuery])
The logic is:
• If the body exists and is valid then use it instead of query parameters.
• If the body is null or invalid then look at query parameters.
• If the query parameters are null or invalid then re-check body as fallback.
• If neither exist or are invalid then return a validation error.

The Problem
• If I decorate my action parameters with just [FromBody], then clients must send JSON. If they do not, they will see errors like “Unsupported Media Type” or model validation failures because the body is missing. I am doing this to help with migration so existing clients do not have to change right away and to support a smooth transition period.
• Mixing [FromBody] and [FromQuery] on the same action parameters does not work particularly well and could throw unexpected validation failures.
• I need to move to a JSON body input but fallback gracefully to query parameters if the body is missing or invalid, especially for existing clients.
• I want validation to “just work” with either input method.

My Solution is an Extension Method That Takes Care of Both Input Types
Here is how I approached it:

• I wrote a helper method that first tries to read and validate my model from the JSON body. A helper method is a fancy way of saying "code" (method) that I have in a in a class file. This helps to simplify and centralize logic that I might otherwise duplicate across multiple places.

• If that does not work (maybe because the client sent no body or the JSON is invalid) then it then tries to build and validate the model from query parameters instead.

• The plan is to end up with one valid model object but it is also possible that neither input works.

• I call this helper from my controller action. If it returns a valid model, preferably from the JSON body (which is the goal here) then I continue with my business logic. If it doesn’t then I return a validation error to the caller.

What Does That Look Like?
I added a new class file named HttpRequestExtensions.cs to my project.

The file contains an extension method for my ASP.NET controllers that helps seamlessly retrieve and validate a model from either the JSON request body ([FromBody]) or the URL query parameters ([FromQuery]). In a nut shell:
• Read and parse the JSON body first, validating the model if present.
• If the body is missing or invalid, it then attempts to build and validate the model from the query string parameters.
• It returns the first valid model it finds, or null if neither source is valid.

This simplifies my controller code by centralizing the logic for supporting both input styles, making migration smoother and keeping the endpoint implementation clean and consistent.

Here is what the HttpRequestExtensions.cs file extension method looks like.

// This static class provides an extension method for Controller to support input binding
// from either JSON body ([FromBody]) or query string ([FromQuery]).
public static class HttpRequestExtensions
{
  // Generic method to try binding a model of type T from the body or query.
  // T must be a class with a parameterless constructor.
  public static async Task<T?> TryGetModelFromBodyOrQueryAsync<T>(this Controller controller) where T : class, new()
  {
    var request = controller.HttpContext.Request;

    // --- STEP 1: Try to bind from JSON body if content exists and is of type application/json ---
    if (request.ContentLength > 0 && 
        request.ContentType?.Contains("application/json", StringComparison.OrdinalIgnoreCase) == true)
    {
      try
      {
        // Attempt to deserialize the JSON body into the model
        var bodyModel = await request.ReadFromJsonAsync<T>();

        // If deserialization is successful and model passes validation, return it
        if (bodyModel != null && controller.TryValidateModel(bodyModel)) 
          return bodyModel;
      }
      catch
      {
        // Ignore JSON parsing errors and fall through to try query string
      }
    }

    // --- STEP 2: Fallback to building the model from query string parameters ---
    var queryModel = new T(); // Create a new instance of T
    var props = typeof(T).GetProperties(); // Reflectively get all public properties

    foreach (var prop in props)
    {
      var key = prop.Name;

      // Skip if the query string does not contain the key
      if (!request.Query.ContainsKey(key)) continue;

      var value = request.Query[key].ToString();

      // Skip if value is empty or whitespace
      if (string.IsNullOrWhiteSpace(value)) continue;

      try
      {
        // Determine the correct type, handling nullable types
        var targetType = Nullable.GetUnderlyingType(prop.PropertyType) ?? prop.PropertyType;

        // Convert the string query value to the correct property type
        var convertedValue = Convert.ChangeType(value, targetType, CultureInfo.InvariantCulture);

        // Assign the converted value to the property
        prop.SetValue(queryModel, convertedValue);
      }
      catch
      {
        // Ignore conversion errors (e.g., invalid format); leave default value
      }
    }

    // Return the query-bound model if it passes validation; otherwise return null
    return controller.TryValidateModel(queryModel) ? queryModel : null;
  }
}

How I use it in my controller
I replaced the existing model-binding code in my controller with this for each of the actions:

var model = await this.TryGetModelFromBodyOrQueryAsync<MyModelType>();
if (model == null)
    return ValidationProblem(ModelState);

// Proceed with my normal business logic using the valid model

Why Is This Awesome?
• Clean & simple controller actions with no messy manual parameter parsing.
• Supports both old clients (query string) and new clients (JSON body).
• Graceful fallback logic. JSON body is preferred but will fall back to query parameters (or error out).
• It is reusable and generic. It works with any of my public property model classes that are defined in my Model.

Is This Method a Good Approach?
It depends. Supporting both [FromBody] and [FromQuery] is not ideal for long-term API design, but it serves as a practical and effective short-term solution when transitioning existing endpoints from query parameters to JSON body input without breaking existing clients
• Have clients relying on query parameters.
• Want a clean and reusable way to handle dual input methods (JSON and parameters).
• Want validation to work seamlessly for either input method (JSON and parameters).
• Want to avoid complex conditional code scattered in my controllers.

Pros of This Approach
• Backwards compatibility: Existing clients keep working while new clients use JSON.
• Future-proof: Existing clients can switch to JSON body without changing server logic.
• Fewer Breaking Changes: Avoids forcing clients to rewrite request logic.
• Clean controller code: Single line to get your model, no manual parameter parsing.
• Generic and reusable: Can be used with any defined model class.
• Graceful fallback: Prefers JSON body but falls back to query parameters if body is missing or invalid.

Cons of This Approach
• Increased complexity: The API endpoint is no longer truly RESTful in a pure sense because it supports two very different input mechanisms simultaneously.
• Not Idiomatic: ASP.NET Core expects one clear model-binding path (e.g., [FromBody] or [FromQuery]). Supporting both circumvents the framework’s intended design.
• Potential Maintenance Burden: basically supporting two versions of input in one endpoint.
• Validation Complexity: Now have to validate two sources and resolve conflicts cleanly.
• Performance overhead: Minor overhead in parsing and validation twice per request.

Is There a Better Way?
Of course, there always is.
• Separate endpoints: Keep old endpoints accepting query parameters for legacy, and new ones accepting JSON body, rather than mixing both in one action. Create one endpoint that supports query parameters (/v1/endpoint) and another that only accepts a JSON body (/v2/endpoint). This is clean, versioned, and explicit.
• Custom model binders: Implement a custom model binder that can elegantly handle both query and body input, but this requires more advanced ASP.NET Core expertise.
• API Gateway or Middleware: Use an API gateway or middleware that transforms query parameters into JSON bodies before the request reaches your controller.
• Deprecate Gradually: Add support for JSON body now, log usage, and phase out query parameter support over time and eventually simplify the codebase to expect only one model-binding source (JSON).

Is Supporting Both JSON Body and Query Parameters a NoNo?
• Although not a strict “NoNo,” it is generally discouraged for clarity and maintainability reasons.
• APIs should ideally be explicit and consistent in how they accept input, mixing sources could potentially confuse both clients and maintainers.
• During transitions or migrations supporting both input styles is a reasonable and often necessary compromise.
• Keep the logic simple and well documented if supporting both input methods.
• Ultimately, the best practice is to have a clear contract (either query parameters or JSON body).

Why I Chose to Do This

1. Transition Period During API Modernization I am modernizing older API endpoints that originally only accepted query parameters, but now need to support more expressive JSON payloads. Instead of requiring all clients to switch immediately, I am allowing both input methods temporarily to maintain backward compatibility. This approach ensures that existing clients keep working without forcing major changes on them.

2. Convenience for Testing and Prototyping When I am testing endpoints in Postman it is easier to pass a few parameters through the URL for quick tests. This is especially helpful during development when the payload is small or simple.

When to Avoid
• Building a new API from scratch.
• For clean consistent POST/PUT API contracts.
• Prioritize long-term maintainability over short-term flexibility.

Summary

1. How easy is it to implement? • This approach takes a bit of setup since it uses a helper method. • Other options might be trickier, like writing a custom model binder.

2. How good is it for backwards compatibility? • This is one of the biggest strengths of this method—it lets old clients keep working without changes. • Other approaches might need separate versioned endpoints.

3. How clear and maintainable is the code? • Mixing query and body input adds a little complexity. • Alternatives that use one clear input model are easier to read and maintain.

4. Does validation still work well? • Yep. FluentValidation works fine with this method. • Same goes for most alternatives.

5. Is this how ASP.NET Core is “supposed” to be used? • Not exactly. It bends the usual model binding rules a bit. • Alternatives tend to stick closer to how the framework was designed to work.

Final Thoughts
This approach helps me keep the API backwards compatible without cluttering up the controller logic. It is a practical middle ground while I migrate endpoints, especially since I still need to support some legacy clients for now.

Once I am ready to drop query parameters entirely, I can just update the action signatures and remove the fallback helper with no major refactoring needed.

Bottom Line
• In the short term, I am okay supporting both [FromQuery] and [FromBody]as I am doing this intentionally with clear fallback rules and proper validation.
• For the long term, the plan is to eventually fully migrate to [FromBody] because it is cleaner and aligns better with modern, RESTful API design. Eventually I will deprecate [FromQuery] for POST and PUT requests.
• As a transition strategy my goal is to move each existing endpoint to JSON body input when the time is right.

Instead of creating a separate stored procedure for each case or writing messy dynamic SQL, I prefer a cleaner approach. I design one flexible stored procedure that can handle all of these lookup paths while keeping my logic organized which makes the code easier to maintain and helps my system adapt to whatever input it receives.

What This Procedure Supports

• Lookups by @patientid

• Lookups by @dob and @zip

• Lookups by @invoice_no

• Optional parameters with fallback matching

• Clean modular structure using Common Table Expressions (CTEs)

• Output in structured JSON, ideal for API responses

Why Flexible Lookup Matters
I rarely get the same kind of data twice. One part of the system might send me a patientid while another might only have a date of birth and ZIP code or just an invoice number.

Here is how it usually breaks down:

• Scenario: API call with internal ID

• Inputs I Get: @patientid

• Scenario: Registration

• Inputs I Get: @dob, @zip

• Scenario: Billing or payment inquiry

• Inputs I Get: @invoice_no

That kind of variety means I need a lookup approach that can adapt. By building in flexible matching logic, I avoid writing separate stored procedures for each case which helps to keep things consistent, avoid duplication, and help me handle more situations with less code with only one stored procedure instead of multiple.

How It Works
The stored procedure follows a clear order of evaluation:

• Scenario: @patientid provided

• What Happens: Direct match

• Scenario: @dob + @zip provided

• What Happens: Match via demographics

• Scenario: @invoice_no provided

• What Happens: Match via invoice number

• Scenario: Multiple match types provided

• What Happens: Uses first match in priority order

• Scenario: No match

• What Happens: Returns empty JSON

• Scenario: Any error

• What Happens: Returns structured JSON error

Why Use CTEs?
Common Table Expressions (CTEs) help keep the matching logic clean, modular, and easy to extend. Each match strategy goes into its own named block:

• Each strategy is easy to isolate and debug

• Logic is easier to read and debug

• Maintenance is simpler when business rules change

• Match types can be reordered or extended without affecting the others

Stored Procedure Walkthrough
This is a simplified version of the procedure that covers all three match types:

use [thedb]
go

drop procedure if exists GetPatientSumInfo
go

set ansi_nulls on
go

set quoted_identifier on
go

create procedure GetPatientSumInfo
  @patientid int = null,
  @dob date = null,
  @zip varchar(20) = null,
  @invnum varchar(50) = null
as
begin
  set nocount on;

  begin try

    ;with patidmatch as (
      select patientid
      from patinfo
      where patientid = @patientid
    ),
    demographicmatch as (
      select p.patientid
      from patinfo as p
      join patinfo_addr as pa on p.patientid = pa.patientid
      where
        @patientid is null and
        @dob is not null and
        @zip is not null and
        p.dob = @dob and
        pa.zip = @zip
    ),
    invoicematch as (
      select distinct p.patientid
      from orderinfo as o
      join patinfo as p on o.patientid = p.patientid
      where
        @patientid is null and
        @invnum is not null and
        o.invnum = @invnum
    ),
    allmatches as (
      select patientid from patidmatch
      union
      select patientid from demographicmatch
      union
      select patientid from invoicematch
    ),
    matchedpatient as (
      select top 1 patientid
      from allmatches
      order by patientid
    )
    select
      p.patientid,
      p.first_name,
      p.last_name,
      p.dob,
      (
        select
          pa.addr_id,
          pa.street,
          pa.city,
          pa.state,
          pa.zip
        from patinfo_addr as pa
        where pa.patientid = p.patientid
        for json path
      ) as address
    from matchedpatient as m
    join patinfo p on p.patientid = m.patientid
    for json path, without_array_wrapper;

  end try
  begin catch
    select
      error_number() as error_number,
      error_message() as error_message,
      error_line() as error_line,
      error_procedure() as error_procedure
    for json path, without_array_wrapper;
  end catch
end

go

Sample Usage
exec GetPatientSumInfo @dob = '1980-05-01', @zip = '12345'

Sample Output

{
  "patientid": 123,
  "first_name": "John",
  "last_name": "Doe",
  "dob": "1980-05-01",
  "address": [
    {
      "addr_id": 789,
      "street": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "zip": "12345"
    }
  ]
}

Error Handling
If any unexpected error happens (e.g., bad join, null issue, query failure, etc.), the CATCH block will return a JSON response like this:

{
  "error_number": 208,
  "error_message": "Invalid object name 'patinfo'.",
  "error_line": 7,
  "error_procedure": "GetPatientSumInfo"
}

This is great for logging or for passing through to an API that displays a friendly error message to the caller.

Performance Comparison
I like using the CTEs + UNION approach because it keeps the code clean and easy to maintain, but it is not always the fastest option, especially in systems with a lot of traffic or big datasets.

Depending on the situation, I sometimes consider other approaches. Here is a quick comparison I use when deciding what fits best:

CTEs + UNION

• Performance: Medium

• Maintainability: Excellent

• Best Use: Clean modular logic with de-duplication

• Notes: Extra cost for de-dupe

CTEs + UNION ALL

• Performance: Good

• Maintainability: Excellent

• Best Use: Clean logic when overlap is impossible

• Notes: Slightly faster if safe to use

Single SELECT + OR conditions

• Performance: Fastest

• Maintainability: Moderate

• Best Use: High-performance environments

• Notes: Harder to maintain and scale

Temp table / Table variable

• Performance: Good

• Maintainability: Moderate

• Best Use: Multi-step logic or complex joins

• Notes: Good for control, indexing flexibility

Indexed view

• Performance: Very Fast

• Maintainability: Hard to manage

• Best Use: High-volume repeat queries

• Notes: Overhead on inserts, complex setup

Final Thoughts
This kind of flexible stored procedure has worked really well for me in situations where I need to match records using different types of information. By combining optional parameters, CTEs, and JSON output, I get something that is clean, modern, and easy to connect to an API.

If performance ever becomes a concern, there are some good ways to optimize without throwing out the whole design. I can switch from UNION to UNION ALL if I know the match paths are mutually exclusive. I can also cache commonly used reference data in the application layer, or preload smaller datasets into temp tables inside the procedure. And in heavier systems, I might use indexed views to speed up the matching process by querying a flattened, pre-joined structure.

But for most systems I have worked on, starting with this kind of clean, modular, CTE-based design provides a solid foundation. It is easy to read, easy to extend, and flexible enough to support all kinds of input combinations.

In my case, I needed to build an API endpoint that could handle multiple types of patient-related data. Sometimes a request had a PatientIdNum, other times it had just a date of birth and zip code, or maybe an invoice number. I wanted a way to let the API decide which method to call based on what was sent, without having to write a long list of conditions in code. So I went with a rule-based approach using a feature in C# called reflection.

What is Dispatching?
"Dispatching" simply means sending something to the right place. In APIs, this usually means figuring out which method should handle a request. A "dispatcher" is just a piece of code that makes this decision.

In my case, I wrote a dispatcher that checks the incoming JSON request, matches it to a rule in a JSON file, and then calls the matching method by name. This keeps the routing logic separate from the rest of the business logic and makes it easier to change.

The Problem with Hardcoded Logic
If you've ever written code like this, you know how quickly it can grow:

if (request.PatientIdNum != null)
  return HandleByPatientIdNum(request);
else if (request.PatInfo?.Dob != null && request.PatInfo?.Zip != null)
  return HandleByDemographics(request);
else if (request.OmInfo?.FirstOrDefault()?.InvoiceNo != null)
  return HandleByInvoice(request);
else
  return BadRequest("Insufficient identifiers");

This kind of logic is fine at first, but over time it:
• Gets harder to read and maintain
• Tangles routing and business logic together
• Requires code changes every time the JSON input and rules change

A Simpler Way: Rule-Based Routing
With rule-based routing, you define your routing rules outside of your code, usually in a file. For me, that file is "rules.json". Each rule lists the fields required to trigger a handler method. Here's an example:

[
  {
    "name": "HandleByPatientIdNum",
    "match": ["PatientIdNum"]
  },
  {
    "name": "HandleByDemographics",
    "match": ["patinfo.dob", "patinfo.zip"]
  },
  {
    "name": "HandleByInvoice",
    "match": ["ominvoice.invoice_no"]
  }
]

Basically, each rule says: If these fields are present and not null, then run the method with this "name".

How Reflection Helps
Reflection is a .NET feature that lets your code look at itself while it's running. That means you can find a method by name and call it even if you didn't hardcode it directly. So, if the rule says to call "HandleByPatientIdNum", and that method exists in your controller, you can call it just by using its name (Reflection).

This makes the system very flexible. To add new functionality, you just write a new method and add a new rule to the JSON file (rules.json).

Reflection Scope Note:
For safety and clarity, I restrict the reflection lookup to non-public instance methods only using BindingFlags.NonPublic | BindingFlags.Instance. This avoids exposing public framework or utility methods unintentionally and keeps the dynamic invocation limited to the intended handler methods.

How It Works
The dispatcher loads the rules from the JSON file.

Rule Validation:
Before evaluating incoming requests, I run a simple preflight validator to check for common mistakes in the "rules.json" file. This helps catch issues early and avoid runtime surprises. The validator:
• Confirms all name entries refer to actual methods (using GetMethod(...))
• Ensures match arrays are not empty
• Optionally checks for duplicate or overly generic rules (e.g., rules that match any input)

This step is run at app startup and helps ensure all routing rules are both valid and intentional.

Then:

1. The request comes in as nested JSON

2. The JSON is flattened into a dictionary with keys like patinfo.dob or ominvoice.invoice_no

3. The dispatcher loads the validated rules from rules.json

4. It checks each rule to see if all required fields are present and not null

5. It picks the most specific matching rule

6. It uses reflection to call the method named in the rule ("name")

Flattening the JSON input
You cannot easily check for field presence like "patinfo.dob" or "ominvoice.invoice_no" with a simple dictionary lookup because those values are nested inside JSON objects.

Flattening turns nested structures into a flat dictionary where the keys represent the full JSON path using dot notation, which makes things much easier.

Here is an example of a nested JSON request:

{
  "patinfo": {
    "dob": "1980-05-01",
    "address": {
      "zip": "12345"
    }
  },
  "ominvoice": {
    "invoice_no": "INV123"
  }
}

And the dictionary (flattened) representation of the JSON input.

{
  "patinfo.dob": "1980-05-01",
  "patinfo.address.zip": "12345",
  "ominvoice.invoice_no": "INV123"
}

Each key is a string path pointing to the original value in the nested JSON which is easier to check instead of writing complex null checks or traversal code.

Example Dispatcher Code
This sample code uses the flattened dictionary to check against the rules in "rules.json" and then calls the right method.

// Find the first rule that matches ALL of its required fields
var matchedRule = rules
  // Keep only the rules where every required field in the rule's `Match` array:
  //   - Exists in the flattened input dictionary
  //   - Is not null
  .Where(r => r.Match.All(field =>
      flattenedInput.ContainsKey(field) && flattenedInput[field] != null))

  // If multiple rules match, prefer the one with the most required fields
  // (i.e., the most specific match)
  .OrderByDescending(r => r.Match.Count)

  // Return the first matching rule, or null if none match
  .FirstOrDefault();

// If no rule matched, return a 400 Bad Request
if (matchedRule == null)
  return BadRequest("No matching handler found");

// Use reflection to locate a method on this controller with the same name
// as the rule's `name` field. Assume all handlers are private instance methods.
var method = this.GetType().GetMethod(
    matchedRule.Name,
    BindingFlags.NonPublic | BindingFlags.Instance
);

// If the method doesn't exist (e.g., typo in rules.json), return error
if (method == null)
  return BadRequest($"Handler method '{matchedRule.Name}' not found");

// Dynamically invoke the matched handler method and pass the `request` object
// This assumes all handler methods follow the signature: 
//   Task<IActionResult> MethodName(PatientRequest request)
var result = await (Task<IActionResult>)method.Invoke(
    this,
    new object[] { request }
);

// Return the handler’s result
return result;

And the matching handler methods look like this:

private async Task<IActionResult> HandleByPatientIdNum(PatientRequest request)
{
  // code here
}

private async Task<IActionResult> HandleByDemographics(PatientRequest request)
{
  // code here
}

private async Task<IActionResult> HandleByInvoice(PatientRequest request)
{
  // code here
}

Why This Is Useful
• You can change the rules without touching the code.
• Helps keep routing logic out of the controller methods.
• Avoids giant if-else/switch blocks.
• Easy to scale by just adding new methods and rules.

Final Thoughts
This rule-based dispatch system has made it much easier for me to handle flexible JSON inputs without burying myself in if-then/switch conditions. By flattening the input to a dictionary and matching fields to rules, I let my code decide what to do based on the data. It's clean, adaptable, and easy to extend. If your API needs to handle many different input patterns, this could be a great way to go.

Notes

While externalizing (rules.json) routing rules offers flexibility, the rules themselves must be managed carefully to avoid becoming a new source of complexity.

The performance benefit of caching method delegates is minimal due to low traffic and simplicity priorities. Reflection is used in a targeted, internal, and predictable way, and the current preference is to keep the dispatch logic simple, stateless, and easier to debug. No performance regressions have been observed in real use, and preliminary profiling showed that JSON parsing and validation dominate the request cycle. However, the architecture leaves room for caching if scale or latency concerns arise. Should performance profiling indicate a need, caching can be introduced in a controlled and validated manner later.

This experience led me to think more seriously about how to track changes to stored procedures; something that would be valuable for auditing, deployment reviews, and debugging. Having visibility into when a stored procedure was created or last modified can help both developers and database administrators identify recent stored procedure changes.

To address this, I took a look at SQL Server's system catalog views. I decided on the sys.procedures view which contain metadata such as creation and modification dates for stored procedures. This brief write-up outlines how to use T-SQL to retrieve a list of stored procedures that were either created or modified within a specified date range, including the script I wrote to accomplish this task.

The TSQL Query

use [yourdatabase]
go

-- select SPs that were created or modified within a specific date range
select
  schema_name(schema_id) as schema_name, -- retrieve schema name (e.g., 'dbo') for the procedure
  name as procedure_name, -- the name of the stored procedure
  create_date, -- the date the procedure was originally created
  modify_date -- the date the procedure was last altered
from sys.procedures -- contains metadata for user-defined procedures
where create_date between '2025-06-01' and '2025-06-18' or modify_date between '2025-06-01' and '2025-06-18'
order by modify_date desc

What This Query Does
It retrieves a list of stored procedures from your selected SQL database that meet either of the following criteria:

• Created or altered between June 06 2025 and June 18 2025
• Each row in the result set includes:
• The schema name (such as dbo)
• The procedure name
• The creation date
• The last modification date

The results are sorted in descending order by modify_date (most recent appear at the top).

Additional Notes
Each database has their own "sys.procedures" and "sys.objects".

If you want to find other objects besides stored procedures you can use "sys.objects" instead of "sys.procedures". Example: Specify type = 'P' with sys.objects to limit the results to stored procedures.

Here is a query to find other object types such as triggers, user tables, etc.

select
distinct
type,
type_desc
from sys.objects

type type_desc
TT TYPE_TABLE
FN SQL_SCALAR_FUNCTION
UQ UNIQUE_CONSTRAINT
SQ SERVICE_QUEUE
F FOREIGN_KEY_CONSTRAINT
U USER_TABLE
D DEFAULT_CONSTRAINT
PK PRIMARY_KEY_CONSTRAINT
V VIEW
S SYSTEM_TABLE
IT INTERNAL_TABLE
P SQL_STORED_PROCEDURE
TR SQL_TRIGGER

Conclusion
SQL Server makes it easy to find out which stored procedures have been added or changed recently. Using the built-in system views, you can quickly get a list of procedures based on when they were created or last modified. This is helpful when trying to audit recent changes, review what went out in a deployment, or troubleshoot something that suddenly stopped working. Pretty good with keeping track of changes to help with things like documentation.

Good Fit for Caching

• Data is read often (rarely written)

• Content is shared across users

• Calls are slow or expensive

• Data freshness is not business-critical

Not a Good Fit for Caching

• Data is updated frequently or in real-time

• Data is personalized or user-specific

• Data is already fast or trivial to retrieve

• Data freshness is business-critical

Some Benefits of Using Caching

• Reduce server load. By serving cached responses, the server uses fewer CPU, disk, and memory resources.

• Improve User Experience. Serving cached responses will make response time faster, smoother, and more responsive.

• Scales Better Under Load. Serving cached responses will help the system handle high volumes of traffic without performing full processing for each incoming request.

Caching is a valuable performance tool, but it is not the only option. Other options such as asynchronous processing, batching, and queuing can also help improve responsiveness and reduce system load, especially when caching is not appropriate for situations where frequently updated data or tasks require the most current data.

Why Use Caching to Boot Performance?
Caching reduces the need to repeatedly perform expensive operations for things like database queries, page rendering, data serialization, and network and disk I/O.

• Querying a database, especially with complex joins or large datasets can be time-consuming. Caching the result set means subsequent requests can bypass the database entirely and deliver the same data as a cached response.

• Calling an external API or service (weather, stock prices, third-party data over HTTP).

• Database access over the network (querying a SQL database hosted on another machine or cloud service).

• Accessing a microservice (sending requests between services in a distributed system).

• Retrieving remote files (documents, images, PDFs, etc.)

Computation or Business Logic
If a response depends on heavy processing (aggregating reports, business rules, etc.) caching can help avoid repeating that work for each request.

Rendering
Is typically for ASP.NET Web Form applications and is the process of generating HTML from server controls (or other content) that will be sent to the browser. In the context of ASP.NET Web Forms, this involves taking server-side controls (like GridView, Label, etc.) and converting them into HTML markup.

Serialization
Is typically for APIs and can be things like serializing return data into JSON or XML. Caching the final JSON or XML result (output caching) is pretty much skipping the rendering/serialization step for repeated (the same) inputs/outputs.

External Resource Access
Fetching data from third-party services or external APIs (weather, stock info, etc.) could introduce latency and maybe even rate limits. Caching these results reduces dependency on the third-party service and external API.

Network and Disk I/O
Reading static files or loading configuration from disk or across the network can also add delays. Caching them in memory will allow for quicker access to that information.

Output Caching
Output Caching in ASP.NET Web Forms
Output caching stores the final rendered HTML of a page and reuses it for subsequent requests. This is particularly effective for pages with static or content that rarely changes and can be represented as more static content.

To implement output caching in a Web Forms application, you can use the OutputCache directive:
<%@ OutputCache Duration="60" VaryByParam="none" %>

• Duration defines how long (in seconds) the page is cached.

• VaryByParam allows different versions of the cache based on query string or form parameters.

For example, to cache different versions of a product page by productId for 120 seconds
<%@ OutputCache Duration="120" VaryByParam="productId" %>

This ensures that each unique productId results in a distinct cached page.

You can also configure output caching programmatically in the page code-behind which provides more caching behavior control.

    Response.Cache.SetExpires(DateTime.UtcNow.AddMinutes(2));
    Response.Cache.SetCacheability(HttpCacheability.Public);
    Response.Cache.VaryByParams["productId"] = true;

Output Caching in C# APIs
ASP.NET Web API does not include built-in output caching like Web Forms does but basic HTTP response caching can be simulated by using a custom action filter. This filter sets caching headers on the response, allowing browsers or intermediary proxies to cache the result for a specified duration.

Here is a simple example defining a custom action filter:

public class OutputCacheAttribute : ActionFilterAttribute
{
  private readonly int _durationSeconds;

  public OutputCacheAttribute(int durationSeconds)
  {
      _durationSeconds = durationSeconds;
  }

  public override void OnActionExecuted(HttpActionExecutedContext context)
  {
    var response = context.Response;
    if (response != null)
    {
      response.Headers.CacheControl = new CacheControlHeaderValue
      {
        Public = true,
        MaxAge = TimeSpan.FromSeconds(_durationSeconds)
      };
    }
  }
}

You would then use the custom action filter in a controller action doing something like this. This caches the response for 120 seconds and reduces the load on the backend for repeated requests with the same parameters.

[OutputCache(120)]
public IHttpActionResult GetProduct(int id)
{
  var product = _productService.GetProductById(id);
  return Ok(product);
}

Data Caching
In addition to output caching, data caching offers greater flexibility and can be used effectively in both Web Forms and APIs. Data caching is the storing of data temporarily in memory so that it can be retrieved faster the next time it is needed. This reduces expensive operations such as repeated database calls.

Data Caching for ASP.NET Web Forms
In an ASP.NET Web Form application, data caching is implemented using the "System.Web.Caching.Cache" class. Example of getting a list of products and cache it for 5 minutes and then reuse it to avoid repeated "database" access.

ProductRepository.cs

public class ProductRepository
{
  public List<string> GetProducts()
  {
    return new List<string> { "Apple", "Banana", "Cherry" };
  }
}

Default.aspx.cs

public partial class _Default : System.Web.UI.Page
{
  protected void Page_Load(object sender, EventArgs e)
  {
    if (!IsPostBack)
    {
      var products = GetProductsFromCache();
      ListBox1.DataSource = products;
      ListBox1.DataBind();
    }
  }

  private List<string> GetProductsFromCache()
  {
    var products = Cache["ProductList"] as List<string>;
    if (products == null)
    {
      var repo = new ProductRepository();
      products = repo.GetProducts();
      Cache.Insert("ProductList", products, null, DateTime.Now.AddMinutes(5), System.Web.Caching.Cache.NoSlidingExpiration);
    }
    return products;
  }
}

Default.aspx
<asp:ListBox ID="ListBox1" runat="server" Width="200"></asp:ListBox>

Data Caching in an ASP.NET Core API
In ASP.NET Core APIs, data caching is commonly implemented using the built-in IMemoryCache service. This allows you to store frequently requested data (such as database query results) in memory to reduce redundant database calls and improve performance. Example of getting a list of products and cache it for 5 minutes and then reuse it to avoid repeated "database" access.

ProductRepository.cs

public class ProductRepository
{
  public List<string> GetProducts()
  {
    return new List<string> { "Apple", "Banana", "Cherry" };
  }
}

ProductController.cs

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Caching.Memory;

[ApiController]
[Route("products")]
public class ProductsController : ControllerBase
{
  private readonly IMemoryCache _cache;
  private readonly ProductRepository _repo = new ProductRepository();

  public ProductsController(IMemoryCache cache)
  {
    _cache = cache;
  }

  [HttpGet]
  public List<string> Get()
  {
    if (!_cache.TryGetValue("ProductList", out List<string> products))
    {
      products = _repo.GetProducts();
      _cache.Set("ProductList", products, TimeSpan.FromMinutes(5));
    }

    return products;
  }
}

Program.cs

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddMemoryCache();
builder.Services.AddControllers();

var app = builder.Build();
app.MapControllers();
app.Run();

Conclusion
Caching is a good way to boost ASP.NET Web Forms and C# API application performance.

Output caching is a good way to speed up an entire page or response and is ideal for quickly serving complete pages or responses.
Data Caching is a good way to improve business logic or data access performance and supports reusability and responsiveness at the business logic layer.

Also, it is handy that you can control how long things stay in the cache and even change what gets cached based on things like query strings or user roles. Basically, you can cache what makes sense when it makes sense and also refresh the cache when required.

Running the script. The user account executing this script will require permissions to connect to the target database and read from the "sys.procedures" and "sys.sql_modules" system tables. Additionally, the account must have write permissions for the designated output file directory.

The Script

# Define the SQL Server connection string
$connectionString = "Server=SQLServerName;Database=DBName;Integrated Security=True"

 # Define the output folder for stored procedure scripts
$outputFolder = "C:\API_SPs" # Can also be a network UNC
$logFile = "$outputFolder\ErrorLog.txt" # Log file to store errors
$errorsOccurred = $false  # Flag to track if any errors occurred
$scriptsWritten = $false  # Flag to track if any scripts were actually written

# Ensure output folder exists, create it if necessary
if (!(Test-Path $outputFolder))
{
  New-Item -ItemType Directory -Path $outputFolder -Force | Out-Null
}

# Define SQL query to retrieve stored procedure definitions
$query = @"
SELECT 
 p.name AS ProcedureName,
 s.name AS SchemaName,
 'DROP PROCEDURE IF EXISTS [' + s.name + '].[' + p.name + '];' + CHAR(13) + CHAR(10) +
 'GO' + CHAR(13) + CHAR(10) +
 sm.definition + CHAR(13) + CHAR(10) +
 'GO' AS ScriptContent
FROM sys.procedures p
JOIN sys.schemas s ON p.schema_id = s.schema_id
JOIN sys.sql_modules sm ON p.object_id = sm.object_id
WHERE 
(
 p.name LIKE 'XXX_YYY%' 
 AND p.name NOT IN ('%BACKUP%', '%OLD%')
)
"@

# Function to log errors to a file and display in the console
function Log-Error
{
  param ([string]$message)
  $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
  $logEntry = "$timestamp - ERROR: $message"
  Add-Content -Path $logFile -Value $logEntry  # Append error to log file

  # Print error directly to console
  Write-Host "ERROR: $message" -ForegroundColor Red  

  # Mark that an error has occurred
  $global:errorsOccurred = $true
}

# Initialize SQL connection and execute query
$sqlConnection = $null  # Variable to hold the connection object
$procedures = @{}  # Dictionary to store procedure names and their scripts

try
{
  # Create and open SQL connection
  $sqlConnection = New-Object System.Data.SqlClient.SqlConnection($connectionString)
  $sqlConnection.Open()

  # Check if connection is successful
  if ($sqlConnection.State -ne 'Open')
  {
    throw "Failed to open SQL connection."
  }

  # Execute the query
  $sqlCommand = $sqlConnection.CreateCommand()
  $sqlCommand.CommandText = $query
  $reader = $sqlCommand.ExecuteReader()

  # Read query results
  while ($reader.Read())
  {
    # Ensure valid file names by replacing invalid characters
    $procedureName = $reader["ProcedureName"] -replace '[\\\/:*?"<>|]', '_' # replace \\\/:*?"<>| with underscore
    $scriptContent = $reader["ScriptContent"]
    $procedures[$procedureName] = $scriptContent  # Store in PS hashtable/dictionary
  }

  $reader.Close()  # Close the SQL data reader
}
catch
{
  Log-Error "Database error: $_"
}
finally
{
  # Ensure SQL connection is closed to avoid resource leaks
  if ($sqlConnection -ne $null -and $sqlConnection.State -eq 'Open')
  {
    $sqlConnection.Close()
  }
}

# Write stored procedure scripts to files only if there are procedures to save
if ($procedures.Count -gt 0)
{
  foreach ($procedureName in $procedures.Keys) # $procedures is a PS hashtable/dictionary and .Keys retrieves all keys from the hashtable
  {
    try
    {
      $filePath = "$outputFolder\$procedureName.sql"
      # Write the script content to the file using UTF-8 encoding
      [System.IO.File]::WriteAllText($filePath, $procedures[$procedureName], [System.Text.Encoding]::UTF8)
      $scriptsWritten = $true  # Mark that at least one script was successfully written
    }
    catch
    {
      Log-Error "Failed to write file: $filePath - $_"
    }
  }
}

# Final status message
if ($errorsOccurred -and -not $scriptsWritten)
{
    Write-Host "No stored procedure scripts were saved. Errors occurred. See $logFile for details." -ForegroundColor Yellow
}
elseif ($errorsOccurred -and $scriptsWritten)
{
    Write-Host "Stored procedure scripts have been saved to: $outputFolder, but some errors occurred. See $logFile for details." -ForegroundColor Yellow
}
elseif ($scriptsWritten)
{
    Write-Host "Stored procedure scripts have been successfully saved to: $outputFolder" -ForegroundColor Green
}
else
{
    Write-Host "No stored procedures matched the criteria. No scripts were generated." -ForegroundColor Cyan
}

Steps Performed by the Script

1. Connect to SQL Server: The script establishes a connection to the SQL Server using the provided credentials.

2. Query the Database: It executes a SQL query to retrieve a list of stored procedures that match the specified criteria (e.g., names starting with "CP_API").

3. Generate Drop and Create Scripts: For each stored procedure, the script constructs a SQL script containing the DROP PROCEDURE IF EXISTS and CREATE PROCEDURE statements, including the procedure's full definition.

4. Save to Files: The script generates an individual .sql file for each stored procedure and saves it to the designated directory (e.g., C:\SQLScripts).

5. Handle Exceptions: Any issues encountered during the execution (such as permission issues, missing procedures, cannot connect to SQL server) are handled by the script. Error messages are written to ErrorLog.txt.

Conclusion
This PowerShell script provides an automated and efficient way to mass generate DROP and CREATE scripts for stored procedures in SQL Server, saving them as individual files for easy deployment or backup. By customizing the SQL query criteria, you can target specific stored procedures, such as those beginning with a particular prefix or excluding certain procedures from the output.

Using this script, database administrators or developers can quickly export the definitions of stored procedures for version control, migrations, or disaster recovery planning. This solution simplifies the process of managing stored procedure scripts, making it a valuable tool for SQL Server environments.

For simplicity, the T-SQL code snippets in this write-up are provided for illustrative purposes only and do not necessarily reflect best coding practices.

1. Fundamentals of SQL Error Handling
TRY...CATCH Block
The TRY...CATCH block is the primary mechanism for handling errors in SQL Server. It allows capturing exceptions and responding appropriately. If an error occurs inside the TRY block, the CATCH block executes, returning error details in a select statement. If you need execution to stop, then you will need to throw the error instead on simply doing a select statement.

begin try
  -- your main sql code here
  -- your main sql code here
end try
begin catch
  select
  error_message() as ErrorMessage,
  error_number() as ErrorNumber,
  error_severity() as ErrorSeverity,
  error_state() as ErrorState
end catch

THROW and RAISEERROR
RAISEERROR allows you to generate custom error messages with specified severity levels.

THROW is used to re-throw captured errors and halt execution.

The point of this code is to demonstrate conditional logic before raising an error in SQL Server using RAISERROR with TRY...CATCH error handling.

-- example of conditional logic before raising an error
declare @somecondition int = 1 -- this will cause the error to be thrown

begin try
  -- conditionally raise an error
  if @somecondition = 1 -- if @somecondition <> 1 then error would not be thrown
  begin
    raiserror('my custom error occurred due to some condition.', 16, 1) -- raise error
  end

  -- your main sql code here
  select 'hello there'
  select 'no error occurred'
end try
begin catch
  -- capture the error and re-throw it
  throw  -- re-throw the error
end catch

Breaking Down the Concept of "Rethrow"

1. An error occurs in the TRY block.

2. If @somecondition = 1, the THROW statement inside TRY raises an error.

3. Execution immediately jumps to the CATCH block.

4. The CATCH block captures the error.

5. SQL Server automatically provides access to error details (ERROR_MESSAGE(), ERROR_NUMBER(), etc.).

6. Just handling the error in CATCH does not automatically stop execution as it needs to be re-raised if necessary.

7. Using THROW in CATCH (Re-throwing the error)

8. Instead of logging the error or handling it silently, THROW raises the exact same error again.

9. This allows the error to propagate up to the caller (e.g., another stored procedure or application).

10. No need to pass error details manually because SQL Server remembers the error context.

Why "Re-throw" Instead of Just "Throw"?

• The term "throw" generally refers to raising a new error.

• The term "rethrow" is used when you catch an existing error and raise it again.

When to Use Rethrow?

• When you don’t want to change the original error.

• When you want the error to propagate up the call stack as if the TRY...CATCH was not there.

• When handling errors in nested stored procedures or transaction rollback scenarios.

An alternative version of the SQL code using just THROW without RAISERROR

declare @somecondition int = 1 -- this will cause the error to be thrown

begin try
  -- conditionally throw an error
  if @somecondition = 1 -- if @somecondition <> 1 then the error would not be thrown
  begin
    throw 50001, 'my custom error occurred due to some condition.', 1
  end

  -- your main sql code here
  select 'hello there'
  select 'no error occurred'
end try
begin catch
  -- capture the error and re-throw it
  throw  -- re-throw the error
end catch

Key Differences Between THROW and RAISERROR

1. Simpler Syntax:

2. THROW 50001, 'My custom error occurred due to some condition.', 1

3. No need to specify severity (16) like in RAISERROR.

4. Built-in THROW for Re-Raising Errors:

5. THROW inside CATCH automatically re-throws the caught error without needing parameters.

6. RAISERROR requires capturing and re-raising the original error manually.

7. Always Uses Severity 16+:

8. With THROW, the severity must be 50000 or higher, which is the custom error range for SQL server.

9. RAISERROR allows you to specify lower severity levels.

When to Use THROW Instead of RAISERROR?

• When you need simpler and cleaner error handling.

• When you don't need advanced formatting. RAISERROR supports message substitution using placeholders.

• When using TRY...CATCH blocks, THROW is the preferred way to re-raise exceptions.

2. Transaction Management and Atomicity
Using TRY...CATCH with Transactions
Transactions in SQL Server guarantee atomicity, meaning that all operations within a transaction either succeed as a group or fail as a group. If any part of the process fails, the system rolls back to its original state, preventing partial updates and ensuring database integrity.

Using transactions is crucial when executing multiple SQL statements that must either fully complete or not execute at all to maintain consistency.

Basic Transaction with Error Handling
This sample code shows how a transaction ensures atomicity. If a specific condition is met, an error is thrown which causes the transaction to roll back:

declare @somecondition int = 1 -- this will cause the error to be thrown

begin transaction
begin try
  if @somecondition = 1 -- if @somecondition <> 1 then the error would not be thrown
  begin
    throw 50001, 'my custom error occurred due to some condition.', 1
  end

  -- sql operations (insert, update, delete, etc.)
  commit transaction
end try
begin catch
  rollback transaction
  throw  -- re-throw the error
end catch

If any SQL statement inside the TRY block fails, SQL Server immediately jumps to the CATCH block. The CATCH block rolls back the transaction, undoing any changes made since BEGIN TRANSACTION, thereby preventing partial updates.

Logging Errors in Transactions
Adding error logging to the CATCH block can help track failures and diagnose issues effectively.

begin transaction
begin try
  -- some sql operations (insert, update, delete, etc.)
  commit transaction
end try
begin catch
    rollback transaction

    -- log error details to a custom audit table
    insert into errorlog (errormessage, errorprocedure, errorline, errortime)
    values (ERROR_MESSAGE(), ERROR_PROCEDURE(), ERROR_LINE(), GETDATE())

    select ERROR_MESSAGE() as errormessage
end catch

Transactions are essential for atomicity and when performing multiple dependent SQL operations. ROLLBACK ensures data consistency by reverting changes in case of failure and the TRY…CATCH block allows for logging errors and prevents partial updates. This is important in all operations that interact with SQL and where data integrity is crucial.

Transactions ensure atomicity, which means that when performing multiple dependent SQL operations, they all must succeed together or fail together. ROLLBACK maintains consistency by reverting changes in case of failure and the TRY…CATCH block handles errors effectively while allowing for error logging and preventing partial updates. Logging errors provides valuable debugging information, ensuring better system reliability.

Transactions are essential in any SQL operation where data integrity is critical, ensuring that changes to the database remain consistent and reliable even in the event of failures.

Using SAVEPOINT for Partial Transaction Rollbacks
SAVEPOINT allows rolling back specific parts of a transaction while keeping others intact. In SQL Server, SAVEPOINT provides finer control over transactions by allowing partial rollbacks. Unlike a full ROLLBACK TRANSACTION, which undoes all changes since BEGIN TRANSACTION, SAVEPOINT enables rolling back only a portion of the transaction while keeping the rest intact. This is useful when handling multiple operations where only certain parts should be undone in case of an error.

SAVEPOINT can help preserve successful operations so if an error occurs, you can roll back to the last SAVEPOINT rather than discarding the entire transaction. This can allow for finer control when handling failures within a large transaction which can be helpful when dealing with dependent operations where certain steps should remain committed even if a later step fails and is rolled back.

begin transaction
begin try
  -- insert new record into the orders table
  insert into orders (orderid, customername, orderdate)
  values (101, 'John Doe', getdate())

  -- define savepoint before inserting a new
  -- record into the orderdetails table
  save transaction OrderDetailsSavepoint

  -- insert new record into the orderdetails table
  insert into orderdetails (orderid, productid, quantity)
  values (101, 1, 5)

  -- simulate an error
  throw 50001, 'simulated error occurred after OrderDetails insertion.', 1

  commit transaction
end try
begin catch
  select 'error. rolling back to OrderDetailsSavepoint savepoint.'

  -- rollback only the changes made after the savepoint
  rollback transaction OrderDetailsSavepoint

  select 'continuing with remaining transaction...'

  -- you can still commit other successful operations
  commit transaction
end catch

If a transaction is fully rolled back (full ROLLBACK TRANSACTION), all SAVEPOINTS within it are also discarded. Using SAVEPOINT does not release locks until the full transaction is committed or fully rolled back.

Using XACT_ABORT for Automatic Rollbacks
XACT_ABORT is a session-level (entire transaction) setting in SQL Server that automatically rolls back the entire transaction if a runtime error occurs. This eliminates the need for explicit error handling with ROLLBACK TRANSACTION which can help ensure data integrity with minimal code. It is very useful for bulk inserts, bulk updates and other "batch" type operations as it prevents partial updates in large batch operations.

XACT_ABORT ensures full rollback on failure. If any statement inside a transaction fails, the entire transaction is automatically rolled back. You do not need explicit BEGIN CATCH and ROLLBACK TRANSACTION with every transaction (reduces manual error handling).

set xact_abort on -- turn it on
-- do not need to turn off xact_abort
-- because it applies to the current session or batch
-- after the session ends or a new connection is made
-- xact_abort resets to its default state (off).

begin transaction
begin try
  -- insert new record into the orders table
  insert into orders (orderid, customername, orderdate)
  values (102, 'Jane Doe', getdate())

  -- simulate an error
    insert into orderdetails (orderid, productid, quantity)
    values (102, NULL, 5)  -- NULL is not allowed for ProductID

    commit transaction  -- this will not run if an error occurs
end try
begin catch
    select 'error. xact_abort automatically rolled back the transaction.'
end catch

3. Error Logging and Reporting
Logging Errors to a Table
Storing error details in a log table helps with troubleshooting and debugging.

begin catch
  insert into errorlog (errormessage, errornumber, errorseverity, errorstate)
  values (ERROR_MESSAGE(), ERROR_NUMBER(), ERROR_SEVERITY(), ERROR_STATE())
end catch

It couldn't hurt to index the errorlog table for better query performance and to add other logging information such as SESSION_USER, APP_NAME(), HOST_NAME(), etc. to help make debugging easier and to add more context. If the error occurs in a stored procedure, then adding ERROR_PROCEDURE() and ERROR_LINE() for good measure might also be helpful.

Using Output Parameters for Error Reporting
Stored Procedures can return error messages via an output parameter.

drop procedure if exists dbo.MyProcedure
go

create procedure dbo.MyProcedure @ErrorMessage nvarchar(4000) output
as
begin
  begin try
    -- sql logic
  end try
  begin catch
    set @errormessage = error_message() -- return the error message to the calling code
  end catch
end
go

Conclusion
Using SQL error handling techniques ensures database reliability and maintainability. Using TRY...CATCH, transaction management, and logging to a table can help improve system resilience, handle unexpected situations effectively and maintain system integrity.

In this write-up, I look at a custom GetResilientConnection method in ADO.NET when connecting to SQL Server using SqlClient to ensure my application handles connection disruptions gracefully by implementing automated custom retry logic that allow my applications to attempt reconnections with controlled delays and limits.

Transient Connection Failures
These faults are temporary connectivity issues, often due to network instability or database server connectivity issues. While these errors are typically resolved once the network or server recovers, they can disrupt an application's flow unless handled properly. Some general transient connection examples can include:

• Network-related errors (e.g., error code 40613)
• SQL Server unavailability (e.g., error code 10928)

Implementing Custom Retry Logic in ADO.NET
A simple yet effective way to enhance resilience is by implementing retry logic. When a transient error occurs, the application should wait for a brief period before attempting to reconnect. This code defines a class named DatabaseHelper, which provides a method called GetResilientConnection. This method is responsible for handling transient database connection failures by implementing a retry mechanism.

Sample Retry Pattern Code Example

using System;
using System.Data.SqlClient;
using System.IO;
using System.Linq;
using System.Net.Sockets;
using System.Threading;

public class DatabaseHelper
{
  public static SqlConnection GetResilientConnection(string connectionString)
  {
    int maxRetries = 3;  // maximum retry attempts
    int delay = 2000;    // initial delay (2 seconds)

    for (int i = 0; i < maxRetries; i++)
    {
      try
      {
        // attempt to establish a SQL connection
        var connection = new SqlConnection(connectionString);
        connection.Open(); // open the connection
        return connection; // successfully connected, return the connection
      }
      catch (Exception ex) when (IsTransientError(ex)) // catch broader transient errors
      {
        Console.WriteLine($"Transient error encountered: {ex.Message}");
        Console.WriteLine($"Retrying in {delay / 1000} seconds...");

        Thread.Sleep(delay); // wait before retrying (exponential backoff)
        delay *= 2; // double the delay for the next retry
      }
    }

    // if all retries fail, throw an exception indicating failure
    throw new Exception("Max retry attempts exceeded.");
  }

  private static bool IsTransientError(Exception ex)
  {
    // some common SQL server transient error codes
    int[] transientErrors = { 40613, 10928, 40197, 40501, 49918, 1205, 233, -2 };

    if (ex is SqlException sqlEx)
    {
      // check if any of the SQL error numbers match the transientErrors errors array
      if (sqlEx.Errors.Cast<SqlError>().Any(e => transientErrors.Contains(e.Number)))
      {
        return true;
      }
    }

    // none of the erros codes in the transientErrors errors array were found
    // so look at these other types 
    // additional transient errors based on exception types
    return ex is TimeoutException  // SQL command timeout
      || ex is IOException       // general network failure
      || ex is InvalidOperationException // connection unexpectedly closed
      || ex is SocketException; // low-level socket failure
  }
}

This GetResilientConnection example method does the following:
• Attempts to establish a SQL Server connection using the provided connection string.
• Retries up to 3 times if a transient failure occurs, with an increasing wait time between attempts - waits (2s → 4s → 8s) before retrying which can improve application server recovery chances. Retries up to 3 times before throwing an exception.
• Uses IsTransientError to detect common transient errors, including SQL timeouts, deadlocks, and network issues. Detects timeouts, network failures, and connection drops.
• Logs the failure and waits before retrying, using exponential backoff (doubling the delay each time).
• Throws an exception if all retry attempts fail.
• Encapsulated in a reusable helper class and can be called from multiple parts of the application for consistent connection handling.

Example of GetResilientConnection Usage
Instead of rewriting SQL connectivity retry logic everywhere in my application where I need to make a SQL connection, I can simply call DatabaseHelper.GetResilientConnection. When another part of my application references DatabaseHelper, it is using this class as a utility to establish SQL connections with built-in resilience.

using (var connection = DatabaseHelper.GetResilientConnection(connectionString))
{
  Console.WriteLine("Connected successfully!");

  // use the connection here
  // and do your data processing stuff
  // in the context of the connection
}

This approach promotes code maintainability and follows the Single Responsibility Principle (SRP) and ensures consistent handling of connection failures across my application.

The Encapsulation Part
I created the custom DatabaseHelper class to centralize database logic and avoid repeating connection code throughout my application. By keeping (encapsulating) this logic in one place, I improve code maintainability and make it easier to update connection handling in the future (only one place if I want to add functionality or fix bugs).

Doing this also ensures that database connection logic remains separate from the rest of my application logic, which helps with making the codebase cleaner and more modular.

Within this class, the IsTransientError method is marked private, meaning transient error detection is only accessible inside DatabaseHelper, which ensures that SQL connectivity error handling is consistent and can only be leveraged by referencing the DatabaseHelper class.

Basically - since DatabaseHelper.GetResilientConnection(connectionString) is public and static, any part of my application that needs a resilient SQL connection can simply call it. This prevents duplicate code and ensures consistent retry logic across the application.

Why Use It
• Improves database connection reliability in case of temporary issues.
• Ensures automatic retry instead of failing immediately.
• Centralized connection handling reduces redundant code across my application.

Conclusion
By creating and using GetResilientConnection, my application can gracefully handle transient failures and improve reliability without requiring manual intervention and ensures that application database connectivity remains stable(ish). Proper logging and exception handling within the retry mechanism further help diagnose persistent issues, making it a valuable strategy for robust database interactions.

In this write up, I show how to achieve this functionality using Windows API and Delphi code.

Key Steps
Check if the Process is Running: Use the "IsProcessRunning" function to determine if the target application is already running. This function scans the active processes and matches their executable names with the desired process name.

Find the Window Associated with the Process: If the process is running, use the "FindWindowByProcess" function to locate the window handle of the application.

Bring the Application to the Foreground: Once the window handle is retrieved, the "SetForegroundWindow" API is used to bring the application window to the front. If minimized, the "ShowWindow" API restores it.

Launch the Application if it is Not Running: If the application is not running, the "ShellExecuteEx" API launches it. After launching, the program waits for the application window to appear and then brings it to the foreground.

 
Example Code
The following code implements the steps for a button click event in my Delphi application. This serves as the core logic and relies on two supporting functions.

procedure TForm1.btnMyButtonClientEvent(Sender: TObject);
var
  ExecInfo: TShellExecuteInfo; // structure to define execution parameters
  Handle: HWND;               // handle to the window of the external application
begin
  // check if the process "TheExternalProgram.exe" is already running
  if IsProcessRunning('TheExternalProgram.exe') then
  begin
    // ff the process is running, find its window by its title
    Handle := FindWindow(nil, 'Extenal Program Window Title');
    if Handle <> 0 then
    begin
      // ff the window is found, restore it if minimized
      ShowWindow(Handle, SW_RESTORE);
      // bring the application window to the foreground
      SetForegroundWindow(Handle);
      end;
  end
  else
  begin
    // if the external executable is not running then prepare to launch it
    ZeroMemory(@ExecInfo, SizeOf(ExecInfo)); // clear the structure
    ExecInfo.cbSize := SizeOf(ExecInfo);  // set the size of the structure
    ExecInfo.fMask := SEE_MASK_NOCLOSEPROCESS; // ensure process handle remains open after launch
    ExecInfo.lpFile := 'c:\thepath\TheExternalProgram.exe'; // path to the executable
    ExecInfo.nShow := SW_SHOWNORMAL; // show the application normally

    // attempt to launch the executable
    if ShellExecuteEx(@ExecInfo) then
    begin
      // wait for the external exe main window to appear
      repeat
        Handle := FindWindow(nil, 'Extenal Program Window Title');
        Sleep(100); // pause for 100ms to allow the external exe to initialize
      until (Handle <> 0); // exit loop once the window handle is found

      // restore the external exe window if minimized and bring it to the foreground
      ShowWindow(Handle, SW_RESTORE);
      SetForegroundWindow(Handle);
    end
    else
    begin
      // show an error message ff launching the external exe fails
      MessageDlg('Failed to launch TheExternalProgram.exe', mtInformation, [mbOk], 0);
    end;
  end;
end;

Supporting Functions
1. Checking if the Process is Running
This supporting code is for the "IsProcessRunning" function. This function checks whether a specific process, identified by its executable name, is currently running on the system. It takes a process name as input, takes a snapshot of all running processes, and compares each process name to the target. If it finds a match, the function returns True, indicating the process is running; otherwise, it returns False.

function IsProcessRunning(const AProcessName: string): Boolean;
var
  SnapShot: THandle; // handle to the process snapshot
  ProcessEntry: TProcessEntry32; // structure to store process information
begin
      Result := False; // default to process not running
  SnapShot := CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0); // take a snapshot of all processes
  if SnapShot = INVALID_HANDLE_VALUE then Exit;

  ProcessEntry.dwSize := SizeOf(TProcessEntry32); // initialize the structure size

  if Process32First(SnapShot, ProcessEntry) then // iterate through the processes in the snapshot
  begin
    repeat
      // compare each process name with the target process name (case-insensitive)
      if SameText(ProcessEntry.szExeFile, AProcessName) then
      begin
        Result := True; // process is running
        Break;
      end;
    until not Process32Next(SnapShot, ProcessEntry); // move to the next process
  end;

  CloseHandle(SnapShot); // release the snapshot handle
end;

2. Finding the Window Associated with a Process
This supporting code is for the "FindWindowByProcess" function. This function searches for a window that is associated with a running process by matching the process name. It iterates through all processes and their windows, comparing the process ID of each window to the target process. If a match is found, it returns the handle of the corresponding window.

function FindWindowByProcess(const ProcessName: string): HWND;
var
  Snapshot: THandle; // handle to the process snapshot
  ProcessEntry: TProcessEntry32; // Structure to store process information
  Handle: HWND; // handle to the window
begin
  Result := 0; // default to no window found
  Snapshot := CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0); // take a snapshot of all processes
  if Snapshot = INVALID_HANDLE_VALUE then Exit;

  ProcessEntry.dwSize := SizeOf(ProcessEntry); // initialize the structure size
  // iterate through the processes in the snapshot
  if Process32First(Snapshot, ProcessEntry) then
  begin
    repeat
      // check if the process name matches the target name (case-insensitive)
      if AnsiCompareText(ProcessEntry.szExeFile, ProcessName) = 0 then
      begin
        // iterate through all top-level windows
        Handle := FindWindow(nil, nil);
        while Handle <> 0 do
        begin
          // check if the window belongs to the target process
          if GetWindowThreadProcessId(Handle, nil) = ProcessEntry.th32ProcessID then
          begin
            Result := Handle; // found the window handle
            Break;
          end;
          Handle := GetWindow(Handle, GW_HWNDNEXT); // move to the next window
        end;
        Break;
      end;
    until not Process32Next(Snapshot, ProcessEntry); // move to the next process
  end;

  CloseHandle(Snapshot); // release the snapshot handle
end;

A Brief Note About the Order of Things
In Delphi, the "IsProcessRunning" and "FindWindowByProcess" functions must be defined before the "btnMyButtonClick" event handler in the code. This order is essential because the button click event needs to reference these functions and they must be available at the time the event is triggered. By defining these functions earlier in my code, I ensure that the button click handler can successfully call them to check if the process is running and to find the associated window.

Conclusion
Incorporating external executables and managing their interactions within a Delphi application is essential when working with legacy systems. By leveraging Delphi’s integration with the Windows API and utilizing key API functions such as "ShellExecuteEx", "ShowWindow", and "SetForegroundWindow", I can easily check if the external program is running, bring its window to the foreground if necessary, and launch it if it’s not already active.

By integrating with my custom API, the Windows service retrieves notification records from the database, validates the data, and triggers the appropriate API delivery method based on the message type (SMS, voice, email).

Note: TheWinService is a placeholder for the actual Windows background service name. I replaced the real name for clarity and confidentiality.

The Windows background service is composed of the following components:

App.config

• Stores application settings, connection strings, and configuration details, such as the API endpoint required for instantiation.

Twilio.cs

• Includes static classes, general utility functions, and logic for retrieving records to process and handling general SQL logging.

Program.cs

• Acts as the entry point for the Windows service. This file configures and initializes the service as a Windows background process, setting up essential dependencies like logging and the core service logic.

WindowsBackgroundService.cs

• Implements the primary background task responsible for periodic processing of notifications, including messaging operations.

App.config

<?xml version="1.0" encoding="utf-8"?>
<configuration>

  <appSettings>

    <add key="service_timer_minutes" value="2" />
    <add key="RequestUri" value="https://the_base_url/Controller/APIEndpoint" />
    <add key="SQL" value="intergrated authentication and connection info" />
    <add key="HashKey" value="a randomly generated client specific hashkey" />

  </appSettings>

</configuration>

Twilio.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Twilio;
using Twilio.TwiML;
using Twilio.Rest.Api.V2010.Account;
using Twilio.Types;
using Twilio.AspNet.Core;
using Twilio.AspNet.Common;
using Microsoft.AspNetCore.Http;
using static Microsoft.Extensions.Logging.EventSource.LoggingEventSource;
using Twilio.Http;
using Twilio.TwiML.Messaging;
using System.Reflection;
using Newtonsoft.Json.Linq;
using Microsoft.Extensions.Logging;
using System.Diagnostics;
using static TheWinService.GeneralFunctions;
using static TheWinService.WindowsBackgroundService;

namespace TheWinService
{

  public class TwilioRecordToProcess
  {
    public string? unique_patent_id  { get; set; }
    public string? to { get; set; }
    public string? from { get; set; }
    public string? pkid { get; set; }
    public string? msgtype { get; set; }
    public string? msgtypevalue { get; set; }
  }


  public class GeneralFunctions
  {
    public static bool IsNull([System.Diagnostics.CodeAnalysis.MaybeNullWhen(true)] object? obj) => obj == null;
    public static bool IsNotNull([System.Diagnostics.CodeAnalysis.NotNullWhen(true)] object? obj) => obj != null;


    public static class Globals
    {
      public static string? _sql_con_str = System.Configuration.ConfigurationManager.AppSettings["SQL"].Replace(@"\\\\", @"\\");
      public static string? hashkey = System.Configuration.ConfigurationManager.AppSettings["HashKey"];
      public static string? RequestUri = System.Configuration.ConfigurationManager.AppSettings["RequestUri"];
    }


    public static TwilioRecordToProcess GetRecordToProcess()
    {
      if (OperatingSystem.IsWindows()) { EventLog.WriteEntry("TheWinService", "GetRecordToProcess"); }

        TwilioRecordToProcess _TwilInfo = new();

      try
       {
         string? _sql_con_str = Globals._sql_con_str;
         System.Data.SqlClient.SqlConnection _sql_con = new System.Data.SqlClient.SqlConnection(_sql_con_str);
         System.Data.SqlClient.SqlCommand _sql_cmd = new System.Data.SqlClient.SqlCommand("GetTheRecToProcess ", _sql_con);
         _sql_cmd.CommandType = System.Data.CommandType.StoredProcedure;
         _sql_con.Open();
         System.Data.SqlClient.SqlDataReader _sql_dr = _sql_cmd.ExecuteReader();
         while (_sql_dr.Read())
         {
                  _TwilInfo.to = (string?)_sql_dr["destination"];
                  _TwilInfo.unique_patent_id = (string?)_sql_dr["unique_patent_id"].ToString();
                  _TwilInfo.from = (string?)_sql_dr["twilio_from_number"];
                  _TwilInfo.pkid = (string?)_sql_dr["pkid"].ToString();
                  _TwilInfo.msgtype = (string?)_sql_dr["msgtype"].ToString();
                  _TwilInfo.msgtypevalue = (string?)_sql_dr["msgtypevalue"].ToString();
         }
         _sql_dr.Close();
         _sql_con.Close();
       }
       catch (Exception ex)
       {
        if (OperatingSystem.IsWindows())
        {
          EventLog.WriteEntry("TheWinService", "GetRecordToProcess - ERROR");
          EventLog.WriteEntry("TheWinService", $"GetRecordToProcess - ERROR: {ex.Message.ToString()}");
        }
       }

      return _TwilInfo;
    }


    public static string LogEndpointCall(string endpoint_name, string payload, string ParticipantMessagingBinding)
    {
      if (IsNull(payload)) { payload = ""; }

      try
      {
        string? _sql_con_str = Globals._sql_con_str;
        System.Data.SqlClient.SqlConnection _sql_con = new System.Data.SqlClient.SqlConnection(_sql_con_str);
        System.Data.SqlClient.SqlCommand _sql_cmd = new System.Data.SqlClient.SqlCommand("DoTheSQLLogging", _sql_con);
        _sql_cmd.CommandType = System.Data.CommandType.StoredProcedure;
        _sql_cmd.Parameters.AddWithValue("@p_partner_id", 0);
        _sql_cmd.Parameters.AddWithValue("@p_endpoint_name", endpoint_name);
        _sql_cmd.Parameters.AddWithValue("@p_payload", payload);
        _sql_cmd.Parameters.AddWithValue("@p_ParticipantMessagingBinding", ParticipantMessagingBinding);
        _sql_con.Open();
        _sql_cmd.ExecuteNonQuery();
        _sql_con.Close();
      }
      catch (Exception ex)
      {
        throw new Exception(ex.Message.ToString());
      }

      return "logged";
    }
  }
}

Program.cs

using TheWinService;
using Microsoft.Extensions.Logging.Configuration;
using Microsoft.Extensions.Logging.EventLog;

IHostBuilder builder = Host.CreateDefaultBuilder(args)
  .UseWindowsService(options =>
  {
    options.ServiceName = "TheWinService";
  })
  .ConfigureServices((context, services) =>
  {
    LoggerProviderOptions.RegisterProviderOptions<
      EventLogSettings, EventLogLoggerProvider>(services);

      services.AddSingleton<CPTwilio>();
      services.AddHostedService<WindowsBackgroundService>();

      services.AddLogging(builder =>
      {
          builder.AddConfiguration(
              context.Configuration.GetSection("Logging"));
      });
  });

IHost host = builder.Build();
host.Run();

WindowsBackgroundService.cs

using System.Diagnostics;
using System.Security.Cryptography.Xml;
using System.Security.Cryptography;
using System.Text;
using System.Net.Http;
using System.Net;
using Newtonsoft.Json;
using System;
using Microsoft.AspNetCore.Mvc;
using Newtonsoft.Json.Linq;

namespace TheWinService  ;


public sealed class WindowsBackgroundService : BackgroundService
{
  private readonly CPTwilio _TheWinService; // used in IsCancellationRequested
  private readonly ILogger<WindowsBackgroundService> _logger; // windows log

  public class SendTwilioSMSBody
  {
    public string? to { get; set; }
    public string? unique_patent_id    { get; set; }
    public string? from { get; set; }
  }


  public WindowsBackgroundService(
    CPTwilio TheWinService  ,
    ILogger<WindowsBackgroundService> logger) =>
    (_TheWinService  , _logger) = (TheWinService  , logger);


  protected override async Task ExecuteAsync(CancellationToken stoppingToken)
  {
    try
    {
      try
      {
        if (OperatingSystem.IsWindows()) { EventLog.WriteEntry("TheWinService", "TheWinService   Start"); }
      }
      catch (Exception)
      { }


      while (!stoppingToken.IsCancellationRequested)
      {
        if (OperatingSystem.IsWindows()) { EventLog.WriteEntry("TheWinService", "GetRecordToProcess"); }

        dynamic SendTwilioSMSBody = GeneralFunctions.GetRecordToProcess();

        GeneralFunctions.LogEndpointCall("Begin ExecuteAsync TheWinService", "", "");

        if (GeneralFunctions.IsNotNull(SendTwilioSMSBody.unique_patent_id  )) // we must have a value
        {
          var ret_list = Newtonsoft.Json.JsonConvert.SerializeObject(SendTwilioSMSBody); // convert class object into JSON

          if (!SendTwilioSMSBody.to.ToString().StartsWith("+1"))
          {
            if (OperatingSystem.IsWindows()) { EventLog.WriteEntry("TheWinService", "[to] must begin with +1 " + ret_list); }
            GeneralFunctions.LogEndpointCall("ExecuteAsync TheWinService", "[to] must begin with +1: " + ret_list, "");
            return;
          }

          if (SendTwilioSMSBody.to.ToString().Length != 12)
          {
            if (OperatingSystem.IsWindows()) { EventLog.WriteEntry("TheWinService", "[to] is incorrect length: " + ret_list); }
            GeneralFunctions.LogEndpointCall("ExecuteAsync TheWinService", "[to] is incorrect length: " + ret_list, "");
            return;
          }
          string ParticipantMessagingBinding = SendTwilioSMSBody.@from +"-"+ SendTwilioSMSBody.@to;

          var result = string.Empty;
          string? signature = string.Empty;
          string? timestamp = DateTime.Now.ToString("yyyy'-'MM'-'dd 'T'HH':'mm':'ss'.'fff'Z'");

          byte[] keyByte = Encoding.UTF8.GetBytes(TheWinService  .GeneralFunctions.Globals.hashkey!);
          using (var hmacsha256 = new HMACSHA256(keyByte))
          {
            byte[] textBytes = System.Text.Encoding.UTF8.GetBytes($"{timestamp}:{TheWinService  .GeneralFunctions.Globals.hashkey!}");
            byte[] hashBytes = hmacsha256.ComputeHash(textBytes);
            string hash = BitConverter.ToString(hashBytes).Replace("-", String.Empty);
            signature = hash.ToUpper();
          }

          // the body stuff
          var content = new StringContent(ret_list, Encoding.UTF8, "application/json"); // add payload to content as Body
          content.Headers.Add("cp_webhook_timestamp", timestamp);
          content.Headers.Add("cp_webhook_signature", signature);

          HttpClient httpClient = new();
          var httpRequestMessage = new HttpRequestMessage();
          httpRequestMessage.Method = HttpMethod.Post;

          // add the content to the response
          httpRequestMessage.Content = content; // required for requestSignature == signature in PartnerRegisteredEndpoint

          // define the URI
          string? RequestUri = TheWinService  .GeneralFunctions.Globals.RequestUri!;
          httpRequestMessage.RequestUri = new Uri(RequestUri!); // set the partner_registered_endpoint

          if (OperatingSystem.IsWindows()) { EventLog.WriteEntry("TheWinService", RequestUri); }

          // call the API TwilioEntryPoint endpoint
          try
          {
            var response = await httpClient.PostAsync(httpRequestMessage.RequestUri.ToString(), content);
            if ((int)response.StatusCode != 200)
            {
              string resp = response.StatusCode.ToString() + " - " + response.ToString() + " - " + RequestUri;
              if (OperatingSystem.IsWindows()) { EventLog.WriteEntry("TheWinService", resp); }
              return;
            }
          }
          catch (Exception)
          {
            if (OperatingSystem.IsWindows()) { EventLog.WriteEntry("TheWinService", "API endpoint did not respond."); }
            return;
          }

          if (OperatingSystem.IsWindows()) { EventLog.WriteEntry("TheWinService", "API SendTwilioSMS endpoint call complete"); }
        }

        string? _minute_timer = System.Configuration.ConfigurationManager.AppSettings["service_timer_minutes"];
        int minutes = int.Parse(_minute_timer!);
        await Task.Delay(TimeSpan.FromMinutes(minutes), stoppingToken);
      }
    }
    catch (TaskCanceledException)
    {
      // When the stopping token is canceled, for example, a call made from services.msc,
      // we shouldn't exit with a non-zero exit code. In other words, this is expected...
    }
    catch (Exception ex)
    {
      _logger.LogError(ex, "{Message}", ex.Message); // _logger is defined as WindowsBackgroundService
      // Terminates this process and returns an exit code to the operating system.
      // This is required to avoid the 'BackgroundServiceExceptionBehavior', which
      // performs one of two scenarios:
      // 1. When set to "Ignore": will do nothing at all, errors cause zombie services.
      // 2. When set to "StopHost": will cleanly stop the host, and log errors.
      //
      // In order for the Windows Service Management system to leverage configured
      // recovery options, we need to terminate the process with a non-zero exit code.

      if (OperatingSystem.IsWindows()) { EventLog.WriteEntry("TheWinService", "TheWinService   Stop"); }

      Environment.Exit(1);
    }
  }
}

Overview: Twilio Windows Background Service
This Windows Background Service, implemented in C#, is designed to automate the delivery of notifications using Twilio. The service continuously monitors a SQL database for new records indicating messages to be sent, such as a notification about a prescription being ready for pickup. The key features and workflow of this service are as follows:

General Features

• Customizable Interval: The service polls the SQL database at a configurable interval (default: 2 minutes) to check for new records.

• SQL Integration: Retrieves relevant data from the database for preparation.

• Custom API Integration: Constructs the message body and initiates an endpoint call to my custom API which, based on message type, sends messages to recipients using Twilio integration.

• Error Handling and Logging: Logs activity and results in both the SQL database and the Windows Event Log. Detects and logs common issues, such as invalid phone numbers or failed API calls.

• Secure Communication: Generates secure signatures for API calls using HMAC-SHA256 to authenticate requests.

• Graceful Shutdown: Handles task cancellations when the service is stopped, ensuring a clean exit.

General Workflow
Initialization:

• The service starts and writes an entry to the Windows Event Log.

• Retrieves the polling interval and endpoint configuration from app settings.

Polling Loop:

• Queries the SQL database for a record indicating a message to process.

• If a record exists:

  • Serializes the record into JSON for use in the request payload.

  • Validates the recipient's phone number (e.g., must begin with +1 and be 12 characters long).

• Constructs the API request:

  • Generates a timestamp and HMAC signature for secure communication.

  • Sets headers and body content for the HTTP request.

  • Communicates with the custom API endpoint to send message data using Twilio integration and handles the response:

    • Logs any errors or issues with the API call to the Windows Event Log and database.

Logging and Delays:

• Logs success or failure of each operation to the database and Windows Event Log.

• Waits for the configured interval before polling the database again.

Shutdown:

• Monitors for cancellation requests (e.g., service stop from Windows).

• Performs cleanup tasks and ensures a clean exit.

Detailed Workflow
1.Host Configuration:

• The Host.CreateDefaultBuilder initializes the default host for the application.

• The UseWindowsService method sets up the application as a Windows Service and specifies its name.

2.Service Registration:

• The ConfigureServices method is used to register required services and the hosted background service:

  • WindowsBackgroundService: The main background task that performs periodic processing.

• Configures logging to use the Windows Event Log with customizable settings.

3.Service Execution:

• The host.Run() method starts the service, transitioning it into the active state where it begins processing messaging tasks.

Key Features
1.Windows Service Configuration:

• The service is configured to run as a Windows Service with the name "TheWinSerice".

• This enables the service to integrate seamlessly with the Windows Service Manager. 2.Dependency Injection:

• Adds the WindowsBackgroundService as a hosted service, which contains the core logic for Twilio message processing. 3.Logging:

• Configures logging using the Windows Event Log.

• Allows further customization by reading logging configurations from the application settings (appsettings.json). 4.Host Creation:

• Uses the Host.CreateDefaultBuilder method to set up the service's default environment, including configuration and dependency injection.

• The UseWindowsService method specifies that this application is designed to run as a Windows Service.

Overview of the Integration and Workflow
Windows Service for Orchestration: The Windows service acts as the primary orchestrator, continuously monitoring the database for new notifications. It operates at a configurable interval (e.g., every 2 minutes), fetching records that require processing. For each record:

• It validates the data.

• Prepares the payload with details like recipient, message type, and content.

• Sends the data to the TwilioEntryPoint API endpoint for further processing.

Centralized API Endpoint: The custom API's "TwilioEntryPoint" endpoint serves as the hub for processing notifications. Upon receiving a request:

• It parses the payload to extract key information (e.g., recipient details, message type).

• Based on the message type (msgtype), the API routes the request to the appropriate handler:

  • SMS notifications are sent using Twilio's messaging services.

  • Voice notifications initiate a call using the Twilio Voice API.

  • Email notifications are processed via a dedicated email controller.

Global Configuration for Flexibility: A static global variable (RequestUri) stores the client-specific API entry endpoint. This ensures the solution can adapt to varying configurations across different deployments, allowing effortless customization without code changes.

Secure Communication: Each API call is signed with a unique HMACSHA256 signature and timestamp, ensuring secure and authenticated communication between the Windows service and the API.

Error Handling and Logging: Robust error handling and logging mechanisms are in place to ensure reliability:

• The Windows service logs errors and status updates to the Windows Event Log.

• The API validates incoming requests, ensuring essential parameters are present and logging any discrepancies.

Benefits of the Approach

• Scalability: Handles high volumes of notifications efficiently.

• Flexibility: Easily adapts to client-specific configurations and requirements.

• Reliability: Ensures secure, error-resistant communication between components.

• Comprehensive Logging: Provides clear insights into the processing flow and status.

Conclusion
The Program.cs file serves as the backbone of the messaging Windows Service, managing its initialization, configuration, and integration with the Windows Service infrastructure. By leveraging dependency injection and structured logging, it ensures modularity, maintainability, and ease of monitoring. Overall, this custom Twilio Windows service provides a robust solution for automating client notifications across multiple channels, including SMS, voice calls, and emails. By seamlessly integrating a custom API with database interactions and the Twilio API, the service guarantees efficient, reliable, and timely communication.

Rather than manually going through my code to extract each endpoint name, action, method, and route details (a process that is both time-consuming and error-prone), I decided to automate the task. My goal was to encapsulate the process within the custom API, keeping everything self-contained while creating a streamlined, dynamic way to generate API endpoint details.

Even before getting started, one of the first questions I considered was where to add all the necessary code within my existing Visual Studio project and which methodologies would be best suited to achieve this, which ultimately led to a significant amount of time researching the topic.

In this write-up, I walk through the process I followed to automate the extraction of endpoint names, actions, methods, and route details from one of my custom C# MVC APIs using Reflection and Dependency Injection.

Note: References to MyCustomAPI is a placeholder for the actual project name used. I replaced the real name for clarity and confidentiality.

What is Reflection?
It is a way for a program to "look at itself" while it's running. It is like a program looking in a mirror. It can see its own parts (like classes and methods) and use them, even if it did not know about them when it was written.

What is Dependency Injection (DI)?
It is like ordering parts for a machine. Instead of the machine finding its own parts, someone else gives it exactly what it needs to work. It is a way for managing how objects in a program get the things (dependencies/parts) they need to work.

Overview of the Steps to Set This Up in My Existing Project

1. Create a new service named "EndpointMetadataService.cs".

2. Register the new service by adding code to Program.cs

3. Create a new controller named "DocsController.cs".

4. Create a new model named "EndpointMetadata.cs" to represent the endpoint metadata.

Step-by-Step Implementation
1. Create a Service for Endpoint Extraction

I am using a dedicated service for endpoint extraction to keep the logic separate from other parts of the application (Separation of Concerns). This approach isolates the endpoint extraction logic from controllers and startup configurations, making it easier to maintain, reuse, and integrate.

A folder named "Services" did not exist in my project, so I created a new folder named "Services" in the root of the project (at the same level as "Controllers", "Models", and "Views").

I added a new blank class file to my project named "EndpointMetadataService.cs" in the new "Services" folder."EndpointMetadataService.cs" will be used to handle the reflection and endpoint metadata extraction.

This is the code for the "EndpointMetadataService.cs" Service.

using MyCustomAPI.Models; // add reference to the model namespace


namespace MyCustomAPI.Services
{
  public class EndpointMetadataService
  {
    // method to retrieve metadata about all endpoints in the application
    public List<EndpointMetadata> GetEndpoints()
    {
        // Get the assembly that contains the executing code (current project)
        var assembly = Assembly.GetExecutingAssembly();

        // Find all classes in the assembly that are derived from ControllerBase (i.e., are controllers)
        // Exclude abstract classes as they cannot be instantiated
        var controllers = assembly.GetTypes()
          .Where(type => typeof(ControllerBase).IsAssignableFrom(type) && !type.IsAbstract);

        // Create metadata for each controller and its associated actions
        var endpoints = controllers.Select(controller => new EndpointMetadata
        {
          Controller = controller.Name.Replace("Controller", ""), // remove the controller suffix

          // Retrieve all public instance methods that are action methods
          Actions = controller.GetMethods(BindingFlags.Instance | BindingFlags.Public)
            // Filter methods that have HTTP method attributes (e.g., [HttpGet], [HttpPost])
            .Where(method => method.GetCustomAttributes<HttpMethodAttribute>().Any())
            .Select(method => new EndpointAction
            {
              Action = method.Name, // Name of the action method
              // HTTP methods associated with the action (e.g., GET, POST)
              Methods = method.GetCustomAttributes<HttpMethodAttribute>().Select(attr => string.Join(", ", attr.HttpMethods)),
              // Route templates defined for the action (e.g., "api/values/{id}")
              Routes = method.GetCustomAttributes<RouteAttribute>().Select(attr => attr.Template ?? "[default]"), // Default to "[default]" if no route is specified
              Description = method.GetCustomAttribute<DescriptionAttribute>()?.Description ?? "No description available",
              Parameters = method.GetParameters().Select(param => new ParameterMetadata
              {
                Name = param.Name!,
                Type = param.ParameterType.Name,
                IsRequired = !param.HasDefaultValue
              }).ToList(), // Convert actions to a list
              ResponseType = method.ReturnType.Name
            }).ToList() // Convert controllers to a list
        }).ToList();

        // Return the constructed list of endpoint metadata
        return endpoints;
    }

  }
}

2.Register the Service in Dependency Injection
I am using ASP.NET Core 6+, so I modified" Program.cs". .NET versions older than 6 would require you to make the changes in "Startup.cs".

I added this code to ensure that the "EndpointMetadataService" is available for use in all of the controllers and other parts of the API (Dependency Injection).
// Register the EndpointMetadataService service builder.Services.AddSingleton<EndpointMetadataService>();

This should be done before building and running the application with “builder.Build()” . I put the new code directly after this line of code.
var builder = WebApplication.CreateBuilder(args);

3.Create a new Controller

I created a new Controller named "DocsController.cs" with an API endpoint ([HttpGet("endpoints")]) for exposing the endpoint metadata. I created this new Controller in the "Controller" folder of my project with a new "endpoints" endpoint.

This is the code for the "DocsController.cs" Controller.

using MyCustomAPI.Services;
using Microsoft.AspNetCore.Mvc;

namespace MyCustomAPI.Controllers
{
  [ApiController]
  [Route("api/[controller]")]
  public class DocsController : ControllerBase
  {
    private readonly EndpointMetadataService _metadataService; // Dependency to handle endpoint metadata


    // Constructor to inject the EndpointMetadataService dependency
    public DocsController(EndpointMetadataService metadataService)
    {
      _metadataService = metadataService; // Assign the injected service to a private readonly field
    }


    // Handles GET requests to "api/docs/endpoints".
    // Retrieves a list of endpoints metadata from the service and returns it in the HTTP response.
    [HttpGet("endpoints")] // basically the addressable endpoint name for the URL
    [Description("Retrieve each endpoint name, action, method, parameters, and route details")]
    public IActionResult GetEndpoints()
    {
      // Fetches endpoint metadata
      var endpoints = _metadataService.GetEndpoints();

      // return an OK response with the endpoints as the response body
      return Ok(endpoints);
    }
  }
}

4.Create a new model to represent the endpoint metadata

I created a new Model named "EndpointMetadata.cs" to represent the endpoint metadata. I created this new Model in the "Model" folder of my project.

The class definitions for the "EndpointMetadata.cs" Model.

namespace MyCustomAPI.Models
{
  public class EndpointMetadata
  {
    public string? Controller { get; set; }
    public IEnumerable<EndpointAction>? Actions { get; set; }
  }

  public class EndpointAction
  {
    public string? Action { get; set; }
    public IEnumerable<string>? Methods { get; set; }
    public IEnumerable<string>? Routes { get; set; }
    public string? Description { get; set; }
    public List<ParameterMetadata>? Parameters { get; set; }
    public string? ResponseType { get; set; }
  }

  public class ParameterMetadata
  {
    public string Name { get; set; }
    public string Type { get; set; }
    public bool IsRequired { get; set; }
  }
}

The "EndpointMetadata" class represents the metadata for each controller with a list of "EndpointAction" objects that detail the actions (methods) as well as HTTP methods (verbs) and routes.

The "EndpointAction" class represents each action in the controller, including its name, HTTP methods, and routes.

Accessing the new Endpoint
To access the new "endpoints" endpoint in the DocsController.cs in development, I simply reference the following URL: http://localhost/api/docs/endpoints

The endpoint will return the dynamically extracted metadata of my API endpoints, including their names, actions, HTTP methods, and routes, and display that information in a JSON format, either in my browser or Postman, depending on which method I use.

Conclusion
Adding a description tag after the endpoint verb declaration can be a helpful way to describe the endpoint's purpose. For instance:

    [HttpPost]
    [Description("Description of this API endpoint")]
    [Route("{controller}/{action}/{variable1}/{variable2}")]

Documentation is a critical part of application design and development, and in this case, I admittedly missed the mark. While there are other methods to achieve the functionality outlined in this write-up, my research led me to conclude that leveraging Reflection and Dependency Injection offers the most straightforward and easy-to-implement solution.

Automating the extraction of API endpoint names and attribute information in my application not only saves time but also ensures the data remains up-to-date with minimal manual effort. By leveraging Reflection and integrating it into my C# MVC API, I can dynamically extract endpoint details, ensuring accuracy, minimizing human error, and providing a scalable solution for managing API endpoint information.

The Script

$folder1 = "c:\PathToFolder1"
$folder2 = "c:\PathToFolder2"

# Get file lists
$folder1files = Get-ChildItem -Recurse -File $folder1
$folder2files = Get-ChildItem -Recurse -File $folder2

# Get relative paths for comparison
$relativePathFolder1 = @{ }
$relativePathFolder2 = @{ }

foreach ($file in $folder1files)
{
  $relativePathFolder1[$file.FullName.Substring($folder1.Length + 1)] = $file.FullName
}
foreach ($file in $folder2files)
{
  $relativePathFolder2[$file.FullName.Substring($folder2.Length + 1)] = $file.FullName
}

# Find new files
Write-Host "`nFinding new files..."
$newFiles = $relativePathFolder1.Keys | Where-Object { -not $relativePathFolder2.ContainsKey($_) }

# Find changed files
Write-Host "`nFinding changed files..."
$changedFiles = @()
foreach ($file in $relativePathFolder1.Keys)
{
  if ($relativePathFolder2.ContainsKey($file))
  {
    # Calculate hashes for both files
    $hashfolder1 = Get-FileHash $relativePathFolder1[$file] -Algorithm MD5 | Select-Object -ExpandProperty Hash
    $hashfolder2 = Get-FileHash $relativePathFolder2[$file] -Algorithm MD5 | Select-Object -ExpandProperty Hash

    # Compare hashes
    if ($hashfolder1 -ne $hashfolder2)
    {
      Write-Host "Changed file: $file"
      $changedFiles += $file
    }
  }
}

# Output results
Write-Host "`nNew Files:"
if ($newFiles.Count -eq 0)
{
  Write-Host "No new files found."
}
else
{
  $newFiles | ForEach-Object { Write-Host $_ }
}

Write-Host "`nChanged Files:"
if ($changedFiles.Count -eq 0)
{
  Write-Host "No changed files found."
}
else
{
  $changedFiles | ForEach-Object { Write-Host $_ }
}

Steps Performed by the Script
1 Define Folder Paths:

• The paths to the 'PathToFolder1' and 'PathToFolder1' folders are stored in $folder1 and $folder2.

2 Retrieve File Lists:

• Get-ChildItem is used to recursively retrieve all files (including those in subdirectories) from each folder.

3 Generate Relative Path Dictionaries:

• Two dictionaries, $relativePathsFolder1 and $relativePathsFolder2, are created:

  • Keys are file paths relative to the root folder.

  • Values are the full file paths.

• This enables direct comparison of files regardless of their root folder paths.

4 Identify New Files:

• Compares the keys (relative paths) in $relativePathsFolder1 against $relativePathsFolder2.

• Files in 'PathToFolder1' that are not present in 'PathToFolder2' are added to $newFiles.

5 Identify Changed Files:

• Iterates through the relative paths in $relativePathsFolder1 that also exist in $relativePathsFolder2.

• Computes the hash of each file using Get-FileHash with the MD5 algorithm.

• Compares the hashes of the corresponding files from both folders.

• Files with mismatched hashes are added to $changedFiles.

6 Output Results:

• Lists new files by displaying each entry in $newFiles. If no new files are found, it outputs "No new files found."

• Lists changed files by displaying each entry in $changedFiles. If no changed files are found, it outputs "No changed files found."

Purpose of Using File Hashes
1 Content-Based Comparison:

• Why: Comparing files based on content rather than metadata ensures you accurately detect differences. Files may have the same name, size, and timestamps but still differ in content.

• How: The MD5 hash uniquely represents the file's content. If two files have different hashes, their content is not identical.

2 Efficient and Reliable:

• File hashes allow for a quick and reliable comparison of file content without manually inspecting the files or relying on less reliable methods like file size.

• MD5 is widely used for this type of integrity checking in scenarios where cryptographic security isn't a concern (as in this use case).

Breaking Down the Hash Command

• Get-FileHash:

  • Calculates a hash of the file content using the MD5 algorithm.

• Algorithm MD5:

  • Using MD5 for its simplicity and speed. While it is not suitable for cryptographic purposes, it works perfectly for file comparison.

  • I could have used the SHA-256 algorithm for greater reliability, however with the speed trade-off, it was not required for this comparison.

• Select-Object -ExpandProperty Hash:

  • Extracts only the Hash property of the Get-FileHash result, making it easier to compare directly.

Why Not Use Metadata?

• Using file properties like size or timestamps could lead to false positives or negatives:

• A file may change content without changing its size.

• Timestamps might not reliably reflect changes, especially when copied or modified under certain conditions.

Key Features:

• Recursive Comparison: Handles files in subdirectories by comparing relative paths.

• Content Comparison: Ensures changes are detected based on content, not just metadata, using hash comparison.

• Informative Output: Provides clear feedback on newly added or changed files.

Conclusion
This script provides a simple solution for comparing files between two directories. By identifying new files and detecting changed files based on their content, the script ensures that you have a clear understanding of differences between folder versions. Its use of relative paths and hash comparisons ensures accuracy, while its straightforward implementation makes it easy to adapt for other scenarios and maintain better control over your directory structures.

"JSProperties" is a DevExpress specific server-side property that allows you to define custom key-value pairs that are then sent to your client-side JavaScript code as part of the "ASPxCallback" control callback response. These properties can be accessed in JavaScript, enabling seamless communication between server-side logic and client-side functionality, which is very useful for updating UI elements, displaying messages, or handling dynamic interactions without requiring a full page reload.

Some Key Features "JSProperties"

Flexible Data Transfer: Enables passing custom data like strings, numbers, or even JSON objects between server and client.

Easy Integration: The data is accessible via the callback event argument on the client-side using JavaScript.

Customizable Keys: Keys must start with the "cp" prefix (e.g., cpMyProperty).

Practical Use Cases

Displaying Status Messages: Inform users of the result of a server-side operation.

Updating UI Components Dynamically: Pass calculated values or server-generated data to update client-side UI elements.

Passing Validation Results: Validate user input server-side and relay feedback to the client.

In this example code, I show how JSProperties works and provide a very basic example.

Using ASPxCallbackPanel with Custom Client-Server Interaction

In this example usage, an "ASPxCallbackPanel" hosts an "ASPxButton" (named clibtn_test) and an "ASPxTextBox" (named cli_MyTextBox) within its "PanelContent" collection. The callback mechanism is defined using the "OnCallback" server-side event handler "MyCallbackPanel_Callback" and the "EndCallback" client-side event handler "CliMyCallbackPanel_EndCallback."

Server-Side Callback Handling

During the server-side callback (MyCallbackPanel_Callback), custom properties are assigned to the JSProperties collection based on the operation's outcome:

Success Case

CaseInfo_CallbackPanel.JSProperties["cp_status"] = "success";

CaseInfo_CallbackPanel.JSProperties["cp_message"] = "success";

On success, these properties indicate a successful operation with appropriate status and message.

Error Case

CaseInfo_CallbackPanel.JSProperties["cp_status"] = "error";

CaseInfo_CallbackPanel.JSProperties["cp_message"] = $"{ex.Message}";

On failure, the properties convey the error status and detailed exception message.

Client-Side Interaction

The "CliMyCallbackPanel_EndCallback" client-side handler processes the callback response by:

1. Setting the text of cli_MyTextBox to the value of cp_message (retrieved from the server).

2. Clearing any existing value of s.cp_function to reset its state.

Key Benefits

This sample highlights how "JSProperties" simplifies dynamic client-server communication in DevExpress "ASPxCallbackPanel". It allows passing detailed operational results, ensuring the UI updates responsively and informs the user of the operation's outcome.

Example Usage

Define the ASPxCallbackPanel in the ASP.NET Form

Define the "ASPxCallbackPanel" with an "ID", "ClientInstanceName", "OnCallback" server-side event, and both an "ASPxButton" with a "ClientSideEvents" definition and a client visible/client disabled "ASPxTextBox" in the panel collection content.

<dx:ASPxCallbackPanel
ID="CaseInfo_CallbackPanel"
ClientInstanceName="cliCaseInfo_CallbackPanel"
runat="server"
ClientVisible="true"
OnCallback="MyCallbackPanel_Callback">
<ClientSideEvents EndCallback="CliMyCallbackPanel_EndCallback" />
<PanelCollection>
  <dx:PanelContent ID="PanelContent2" runat="server">
      <table border="0">
      <tr>
      <td>
        <dx:ASPxButton
        ID="btn_test"
        ClientInstanceName="clibtn_test"
        ClientVisible="true"
        AutoPostBack="false"
        UseSubmitBehavior="false"
        runat="server"
        Text="click here">
        <ClientSideEvents Click="function(s, e){ DoClick('button_click'); }" />
        </dx:ASPxButton>
      </td>
      </tr>

      <tr>
      <td>
        <dx:ASPxTextBox
        ClientEnabled="false"
        ClientVisible="true"
        ID="MyTextBox"
        ClientInstanceName="cli_MyTextBox"
        runat="server"
        Text="">
        </dx:ASPxTextBox>
      </td>
      </tr>
      </table>
  </dx:PanelContent>
</PanelCollection>
</dx:ASPxCallbackPanel>

The Client-side JavaScript for the ASPxButton ClientSideEvents Click Event

This client-side JavaScript code is run when the user clicks on the "ASPxButton". If the "_user_option" variable equals 'button_click' then force a callback on the "cliCaseInfo_CallbackPanel" CallbackPanel, else do nothing.

function Do_Click(_user_option)
{
  if (_user_option === 'button_click')
  {
    // force a callback on the CallbackPanel
    cliCaseInfo_CallbackPanel.PerformCallback('button_click');
  }
}

Server-Side C# Code

This server-side code is run when the "ASPxCallbackPanel" does a callback when initiated by the "ASPxButton" and the "Do_Click" function. This server-side code is defined in the "OnCallback" property of the "ASPxCallbackPanel".

protected void MyCallbackPanel_Callback(object sender, DevExpress.Web.CallbackEventArgsBase e)
{
  if (Regex.IsMatch(e.Parameter, "button_click")) // sent here from javascript Do_Click function
  {
    try
    {

      // your server code here
      // do something here

      // assign "success" values to custom propertiesfor the client-side
      CaseInfo_CallbackPanel.JSProperties["cp_status"] = "success";
      CaseInfo_CallbackPanel.JSProperties["cp_message"] = "success";
    }
    catch (Exception ex)
    {
      // assign "error" values to custom propertiesfor the client-side
      CaseInfo_CallbackPanel.JSProperties["cp_status"] = "error";
      CaseInfo_CallbackPanel.JSProperties["cp_message"] = $"{ex.Message}";
    }
  }
  else
  {
    // assign "nothing to process" values to custom propertiesfor the client-side
    // this not required but is here as a just in case
    CaseInfo_CallbackPanel.JSProperties["cp_status"] = "nothing to process";
    CaseInfo_CallbackPanel.JSProperties["cp_message"] = "nothing to process";
  }

  return;
}

The Client-side JavaScript for the cliCaseInfo_CallbackPanel ClientSideEvents EndCallback Event

This client-side JavaScript is run after the "ASPxCallbackPanel" callback completes. You could interact with other client controls here, such as setting a text box value, checking a checkbox, etc. Here I am setting the "Text" value of the "cli_MyTextBox" "ASPxTextBox" and then deleting the "s.cp_function" value.

function CliMyCallbackPanel_EndCallback(s, e)
{
  var message = s.cpMessage;
  var status = s.cpStatus;

  if (status === "Success" || status === "nothing to process")
  {
    // set text box to the value of message (s.cpMessage)
    cli_MyTextBox.SetText(message);
  }
  else
  {
    console.error("Callback failed");
  }

  // just doing a little clean up here
  delete (s.cp_function);
}

Conclusion The "JSProperties" feature of the "ASPxCallback" control is an easy method to bridge the gap between server-side logic and client-side interactions. Using the transfer of custom key-value pairs during callbacks helps with dynamic, user friendly, and responsive user interfaces without the overhead of full-page postbacks.

The "JSProperties" feature is handy with displaying server-side validation results, updating UI components dynamically, or passing custom messages to the client with its straightforward key-value structure.

"ASPxGridView" is a significant improvement over the standard "GridView" control provided by ASP.NET and offers more customization options, client-side capabilities (via JavaScript). Out of box, it provides some of the following additional features:

• Master-detail relationships

• In-place editing (inline editing, pop-up editing, etc.)

• Export to Excel, PDF, etc.

• Customizable themes and styles

• Hierarchical data representation

• Client-side scripting support (JavaScript)

• Sorting, paging, and filtering

While I won't go into the details of all the additional features of the "ASPxGridView" control, I will demonstrate some of the basic functionality of the control, including events such as "OnAfterPerformCallback", "OnCustomCallback", "BeginCallback", "EndCallback", and "CustomButtonClick", as well as properties like "DataSourceID" and "CssClass".

For the sake of simplicity, the sample code in this document omits error checking, exception handling, logging, and other practices. It is intended for illustrative purposes only and does not necessarily reflect best coding practices.

Defining and Using the ASPxGridView Control on an ASP.NET Web Form

<dx:ASPxGridView
ID="gridSPL"
ClientInstanceName="cligridSPL"
runat="server"
DataSourceID="gridSPLDS"
KeyFieldName="recid"
EnableCallBacks="true"
CssClass="MailMenuSearchBox"
OnCustomCallback="cligridSPL_CustomCallback"
OnAfterPerformCallback="cligridSPL_AfterCallback"
OnHtmlRowPrepared="gridSPL_HtmlRowPrepared"
OnCellEditorInitialize="gridSPL_CellEditorInitialize"
OnRowInserting="gridSPL_RowInserting"
OnRowValidating="gridSPL_RowValidate">
<Columns>
  <dx:gridviewdatatextcolumn FieldName="recid" Visible="false"></dx:gridviewdatatextcolumn>
  <dx:GridViewCommandColumn>
    <CustomButtons>
      <dx:GridViewCommandColumnCustomButton ID="http_addnew" Text="New"></dx:GridViewCommandColumnCustomButton>
    </CustomButtons>
    <CellStyle CssClass="pointer"></CellStyle>
  </dx:GridViewCommandColumn>
</Columns>
<ClientSideEvents
EndCallback="function(s, e){ cligridSPL_EndCallback(s, e); }"
BeginCallback="function(s, e){ cligridSPL_BeginCallback(s, e); }"
CustomButtonClick="function(s, e){ cligridSPL_CustomButtonClick(s, e); }" />
</dx:ASPxGridView>

An Overview of ASPxGridView Properties and Methods

• ID - The server-side reference to the ASPxGridView control.

• ClientInstanceName - The client-side reference to the ASPxGridView control.

• DataSourceID - Defines the SQL data source for the ASPxGridView control.

• KeyFieldName - The primary record from the SQL data source result set.

• EnableCallBacks - Tells the the ASPxGridView control to allow callbacks.

• OnCustomCallback - The server-side event to run on callback.

• OnAfterPerformCallback - The server-side event to run after the callback completes.

• OnHtmlRowPrepared - The server-side event for each grid row within the ASPxGridView. Typically used to change the style settings of each row.

• OnCellEditorInitialize - When the Grid switches a row to edit mode, it sends a callback request to the server to initialize cell editors. Typically used to customize an editor’s settings before it is shown in the edit cell.

• OnRowInserting - The server-side event that occurs when a user tries to save a newly inserted row.

• OnRowValidating - This server-side event is automatically raised when a row is about to be updated. Typically used to validate the new/updated data. You can also compare it to the original data (OldValues and NewValues property).

• EndCallback - The client-side JavaScript event to run at the end of the ASPxGridView callback.

• BeginCallback - The client-side JavaScript event to run at the beginning of the ASPxGridView callback. This runs before the server-side event.

Note: The "" are executed before the server-side events.

The CssClass Property
DevExpress components implement CssClass properties that allow you to assign CSS classes to the component and its elements.

Specify the external styles file.

<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
  <title>Your Web App Title</title>
  <link href="styles/main.css" rel="stylesheet" type="text/css" />
</head>

The style entry in the "styles/main.css" file.

.MailMenuSearchBox
{
  cursor: pointer;
  font-family: 'Open Sans', sans-serif;
  font-size: 14px;
  background-color: #f8f8f8;
}

DataSourceID
The "asp:SqlDataSource" is a standard ASP.NET Web Form control that provides a simple way to interact with a database directly from a web page without needing explicit code to manage the data connection. It simplifies data retrieval, insertion, updating, and deletion operations by automating much of the database interaction. Typically used for simple data binding tasks. No code behind, simply configure the control declaratively. Enables rapid development, especially for applications that require basic data operations with minimal code.

<asp:SqlDataSource
ID="gridSPLDS"
runat="server"
ProviderName="System.Data.SqlClient"
EnableCaching="false"
ConnectionString="<%$ ConnectionStrings:YourSecureConnString %>"
SelectCommand="sp_GetAllrecords"
SelectCommandType="StoredProcedure"
InsertCommand="sp_AddNewRecord"
InsertCommandType="StoredProcedure">
<SelectParameters>
  <asp:Parameter Name="p_matternum" Type="string" />
  <asp:Parameter Name="p_type" Type="string" />
</SelectParameters>
<InsertParameters>
  <asp:Parameter Name="p_matternum" Type="String" />
  <asp:Parameter Name="p_type" Type="String" />
</InsertParameters>
</asp:SqlDataSource>

OnHtmlRowPrepared
This code will change the row backcolor/forecolor based on the value of the "Cost" field in the row. It can also be used for when the ASPxGridView is in edit mode, to hide a row of data based on your criteria, disable row editing based on your criteria, etc.

protected void gridSPL_HtmlRowPrepared(object sender, DevExpress.Web.ASPxGridViewTableRowEventArgs e)
{
  if (e.RowType == DevExpress.Web.GridViewRowType.Data)
  {
    int price = Convert.ToInt32(e.GetValue("Cost"));
    if (price < 20) {e.Row.BackColor = System.Drawing.Color.LightCyan};
    if (price > 50) {e.Row.ForeColor = System.Drawing.Color.DarkRed};
  }
}

CustomButtonClick
The "GridViewCommandColumnCustomButton" "http_addnew" button executes the client-side JavaScript "cligridSPL_CustomButtonClick" function when clicked. Each row contains an "http_addnew" button.

function cligridSPL_CustomButtonClick(s, e)
{
  if (e.buttonID == 'http_addnew')
  {
    cligridSPL.PerformCallback('grid_add_new_row')
    e.processOnServer = true;
  }
}

Which forces a server-side callback on the "cligridSPL ClientInstanceName", which then executes the "cligridSPL_CustomCallback" server-side event. In this instance, the "cligridSPL_CustomCallback" server-side event puts the ASPxGridView into edit mode allowing the user to add a new row of data.

protected void cligridSPL_CustomCallback(object sender, DevExpress.Web.ASPxGridViewCustomCallbackEventArgs e)
{
  if (Regex.IsMatch(e.Parameters, "grid_add_new_row")) // sent here from javascript cligridSPL_CustomButtonClick function
  {
    gridSPL.AddNewRow();
    gridSPL.JSProperties["cp_function"] = "grid_add_new_row"
  }
}

OnCellEditorInitialize
When an "ASPxGridView" row switches to edit mode, it sends a server-side callback request to the server to initialize cell editors. Typically used to customize the "ASPxGridView" editor settings before the column is shown in the edit cell. In this instance, it will make the "location" field the initial edit focus.

protected void gridSPL_CellEditorInitialize(object sender, ASPxGridViewEditorEventArgs e)
{
  if (e.Column.FieldName == "location")
  {
    e.Editor.Focus(); // set location field focus
  }
}

OnRowValidating
This server-side code will get the value of the e.NewValues["location"] field and validate it in my CommonAppCode class. Basically, it just makes sure the new location is valid based on my criteria. If the location value is not valid then the "_SharePointvalidationPassed" global public variable is set to false and e.RowError = "Invalid URL"; event is raised.

protected void gridSPL_RowValidate(object sender, DevExpress.Web.Data.ASPxDataValidationEventArgs e)
{
  string rowtovalidate = Convert.ToString(e.NewValues["location"]);
  if (!CommonAppCode.ValidateUrl(rowtovalidate))
  {
    _SharePointvalidationPassed = false;
    e.RowError = "Invalid URL";
  }
}

Note: "_SharePointvalidationPassed" is a global public variable that I pre-defined.
public bool _SharePointvalidationPassed = true;

OnRowInserting
This server-side code sets the "p_casenum" field to the value of a form textbox control, "p_loctype" is set "S", and both "p_location" and "p_indexlocation" are set to the value of e.NewValues["location"] and the "gridSPL" ASPxGridView is rebound to its data source.

protected void gridSPL_RowInserting(object sender, DevExpress.Web.Data.ASPxDataInsertingEventArgs e)
{
  e.NewValues["p_casenum"] = txtbox10.Text; // the text box value
  e.NewValues["p_loctype"] = "S";
  e.NewValues["p_location"] = e.NewValues["location"];
  e.NewValues["p_indexlocation"] = e.NewValues["location"];
  gridSPL.DataBind();
}

BeginCallback
This JavaScript client-side code is run before the server-side "cligridSPL_CustomCallback" OnCustomCallback event is run. I am just showing this in case you would need to do some processing before running the OnCustomCallback server-side event. For example, If the user decided to cancel editing a row, you could cancel the edit without running the OnCustomCallback server-side event, which would save a server round trip.

function cligridSPL_BeginCallback(s, e)
{
  if (e.command == 'CANCELEDIT')
  {
    e.cancel =- true; // cancel the edit
  }
}

OnAfterPerformCallback
This server-side code run after the server-side "cligridSPL_CustomCallback" OnCustomCallback event is run. This code checks the "_SharePointvalidationPassed" global public variable that is set during validation in "gridSPL_RowValidate".

If it is "true" then pass "add_new_row_success" to the client-side "cligridSPL_EndCallback" javacript function for processing.

If it is "false" then pass "add_new_row_failed" to the client-side "cligridSPL_EndCallback" javacript function for processing.

protected void cligridSPL_AfterCallback(object sender, DevExpress.Web.ASPxGridViewAfterPerformCallbackEventArgs e)
{
  if (_SharePointvalidationPassed) // check variable set in gridSPL_RowValidate
  {
    _SharePointvalidationPassed = false; // reset global variable
    gridSPL.JSProperties["cp_function"] = "add_new_row_success"; // pass this to the cligridSPL_EndCallback javacript function
  }
  else
  {
    gridSPL.JSProperties["cp_function"] = "add_new_row_failed"; // pass this to the cligridSPL_EndCallback javacript function
  }
}

EndCallback
This JavaScript client-side code completes the callback processing. It checks the value of "s.cp_function" that is passed here from the "cligridSPL_CustomCallback" server-side event. It deletes the value of "s.cp_function" and then does some processing based on that value.

function climainCallbackPanel_OnCallbackComplete(s, e)
{
  switch (s.cp_function)
  {
    case 'add_new_row_success':
      delete(s.cp_function);
      // display add new row success message to user
      break;

    case 'add_new_row_failed':
      delete(s.cp_function);
      // display add new row failed message to user
      break;

    default:
      delete(s.cp_function);
      break;
  }
}

Conclusion
I have found the "ASPxGridView" control to be both easy to work with and a flexible solution for displaying and managing data in the interactive, data driven ASP.NET Web Forms applications I have developed over the years.

The Intapp Walls API is a SOAP web service that provides a programmatic interface for interacting with the Intapp Walls application. It is deployed as a standard component web service.

For the sake of simplicity, the sample code in this document omits error checking, exception handling, logging, and other practices. It is intended for illustrative purposes only and does not necessarily reflect best coding practices.

Here I walk through two key scenarios:

1. Retrieving and listing matter team membership.

2. Adding a new member to an existing matter team.

By understanding and using IntApp Walls API operations such as "GetMatterTeamForMatter", "LoadMatterTeam", and "AddUsersToMatterTeam", you can streamline tasks related to ethical wall management. The following examples include code snippets and step-by-step guidance.

This document will not cover the specifics of configuring development access to the IntApp Walls API. However, the management solution must be installed on your local domain, and the web service is typically accessible via a file named "APIService.svc", which should be added as a service reference in Visual Studio.

The sample code references the following IntApp Walls API operations:

• GetMatterTeamForMatter - Gets the ID of the matter team that is associated with the specified matter.

• LoadMatterTeam - Loads the properties of a matter team.

• GetDMSUserID - Get the DMS user ID. Some of the API methods require the DMS user ID for a user. For example, the CreateWall() method requires the user ID to be that of the DMS, not a user's timekeeper ID or records system ID. This method can be used to get the DMS user ID given another known ID for the user.

• LoadMatterTeamMembership - Loads the matter team membership.

• GetWarningsIfUserIsIncluded - Gets any warnings that would be generated if the specified user was granted access (i.e., included) to a particular client or matter. This function returns any warnings that may be generated by conflicting ethical walls.

• AddUsersToMatterTeam - Adds the user to an existing matter team with a specified role.

Example: Retrieving and Listing Matter Team Membership
The following code snippet uses the IntApp Walls API "GetMatterTeamForMatter" and "LoadMatterTeam" operations to retrieve a list of matter team members and then write the team membership particulars to the console.

Notes:
• Working with the IntApp API typically requires specific privileges, often granted to a service account with appropriate IntApp Walls access.
• References to "intapp_web_api" in the code snippet below, refers to the name of your IntApp API service reference as defined in Visual Studio.

Step 1: Retrieve the unique IntApp Walls-managed matter team ID number.
Retrieve the ID of the matter team associated with a specified matter. This matter team ID will then be used to obtain the matter team membership details.

To achieve this, invoke the "GetMatterTeamForMatter" operation, which requires a "matterID" parameter. The "matterID" is typically an internally generated ID, sometimes referred to as a "case number." This value is supplied by the user or programmer from their own Timekeeper-type source.

string matterID = "01234"; // matterID supplied by you
string matterTeamID = String.Empty; // the return value

// get the walls matter team id
// example of matter team id "COOLE-033517"
matterTeamID = GetMatterTeamForMatter(matterID);

public static string GetMatterTeamForMatter(string matterID)
{
  intapp_web_api.Matter matter = new intapp_web_api.Matter();
  string matterTeamID = string.Empty;

  try
  {
    intapp_web_api.APIServiceClient intapp_web_api = new intapp_web_api.APIServiceClient();
    matterTeamID = intapp_web_api.GetMatterTeamForMatter(matterID);

    if ((string.IsNullOrEmpty(matterTeamID)))
    {
      matterTeamID = "blank";
    }
  }
  catch (Exception ex)
  {
    if (string.IsNullOrEmpty(matterTeamID) || ex.Message == "Error")
    {
      matterTeamID = "blank";
    }
  }
  return matterTeamID;
}

Step 2: Load the Matter Team Results
Define the "LoadMatterTeam" method and use the unique IntApp Walls-managed matter team ID number "matterTeamID" variable obtained from executing the "GetMatterTeamForMatter" method to call the "LoadMatterTeam" method to retrieve the matter team. Iterate through the "UserMemberships" collection within the matter team and output the user team ID and role to the console.

public static intapp_web_api.MatterTeam LoadMatterTeam(string matterTeamID)
{
  intapp_web_api.MatterTeam matterTeam = new intapp_web_api.MatterTeam();

  try
  {
    intapp_web_api.APIServiceClient intapp_web_api = new intapp_web_api.APIServiceClient();
    matterTeam = intapp_web_api.LoadMatterTeam(wallscaseteamid);
  }
  catch (Exception ex)
  {
    throw new Exception(ex.Message.ToString());
  }

  return matterTeam;
}

MatterTeam the_matter_team_list = LoadMatterTeam(wallscaseteamid);

using (APIServiceClient intapp_web_api = new APIServiceClient())
{
  // iterate through the usermemberships collection in the matterteam
  foreach (UserMembership user in the_matter_team_list.UserMemberships)
  {
    string _userid = user.UserId.ToString(); // get the user id
    string _therole = user.Role.ToString(); // get the user role

    // output the user team id and role to the console
    Console.WriteLine($"user team id: {_userid}");
    Console.WriteLine($"user team role: {_therole}");
  }
}

Example: Adding a New Member to an Existing Matter Team Membership
Building on the "GetMatterTeamForMatter" and "LoadMatterTeam" operations to retrieve a list of matter team members, the following code snippet demonstrates how to use the IntApp Walls API to check existing team membership and add a new member to the team if they are not already a member.

Notes:
• Manipulating IntApp Walls teams via the IntApp API requires specific privileges, which are beyond the scope of this document. The requester will also need to be in an IntApp Walls matter admin role as defined in IntApp Walls.
• Working with the IntApp API typically requires specific privileges, often granted to a service account with appropriate IntApp Walls access.
• References to "intapp_web_api" in the code snippet below, refers to the name of your IntApp API service reference as defined in Visual Studio.

Step 1: Using the "GetDMSUserID" operation, Get the "sAMAccountName" of the user you want to add to the Walls team.
The "sAMAccountName" (Security Account Manager Account Name) is an attribute in Microsoft Active Directory (AD) that represents a user's logon name used to authenticate to the domain.

string theid = "jsmith"; // the sAMAccountName ad account name of user to add
string wallsuserid = string.Empty;

wallsuserid = intapp_web_api.GetDMSUserID(UserIDSource.WindowsNetworkLogon, $@"YourDomainName\{theid}") // change "YourDomainName" to your domain name

// check if wallsuserid contains a value
if (string.IsNullOrEmpty(wallsuserid))
{
  Console.WriteLine("the user you are trying to add to Walls team does not exists in Walls");
  return;
}

Step 2: Check if the Matter exists in Walls.

string matterID = "01234"; // matterID supplied by you

try
{
  matterTeamID = intapp_web_api.GetMatterTeamForMatter(matterID);
}
catch (Exception ex)
{
  if (ex.Message.Contains("The matter") && ex.Message.Contains("does not exist"))
  {
    Console.WriteLine("the matter does do not exist");
    return;
  }
  else
  {
    Console.WriteLine(ex.Message);
    return;
  }
}

Step 3: If the Matter exists, is the user already a team member?

// is the user you are trying to add already on the case team?
// use matterTeamID from step #2 above
// use wallsuserid from step #2 above
MatterTeam matterteamlist = intapp_web_api.LoadMatterTeamMembership(matterTeamID);
foreach(UserMembership user in matterteamlist.UserMemberships)
{
  if (smaccountname == wallsuserid) // are they on the case team already?
  {
    Console.WriteLine("the user you are trying to add is already a member");
    return;
  }
}

Step 4: Will adding the user to the Matter team cause an internal conflict?

// will adding the user to the case team cause a conflict?
// use wallsuserid from step #2 above

string matterID = "01234"; // matterID supplied by you

string[] warning = intapp_web_api.GetWarningsIfUserIsIncluded(null, wallsuserid, SecurableEntityType.Matter, matterID);
if (warning.Length > 0 && warning[0].Contains("has conflicting case-level access"))
{
  Console.WriteLine("adding the user as a member will cause a conflict");
  return;
}

Step 5: Finally, add the user to the Matter team.

// Add the user to the Matter team
// use wallsuserid from step #2 above
// use matterTeamID from step #3 above
// UserMembership is a partial public class
// of the Wallbuilder API service reference

string caseteamrole = "Member";
string theReason = $"{theid} added programmatically via the Walls API Service"

UserMembership _mbr = new() // _mbr membership string array
{
  UserId = wallsuserid,
  Role = caseteamrole,
  Reason = theReason
};

// build user membership- must be string array for AddUsersToMatterTeam
UserMembership[] TheAddUserMmbrshipList = { _mbr };

// actually add the user now
intapp_web_api.AddUsersToMatterTeam(matterTeamID, UserIDSource.DMS, TheAddUserMmbrshipList); // do the add

Conclusion
The IntApp Walls API offers a comprehensive set of operations for managing matter team memberships and safeguarding sensitive information. From retrieving team details to adding new members while checking for conflicts, these API functions enable seamless integration with your workflows and adherence to ethical wall policies. With the right implementation, managing matter teams becomes a streamlined and efficient process that upholds data integrity.

While transactions can be managed explicitly using specific commands (explicit transactions), SQL Server also handles transactions automatically (implicit transactions) for simpler operations.

Including BEGIN TRANSACTION, COMMIT, and ROLLBACK in your SQL code is a good practice when the operation involves multiple steps or when there is a need to ensure atomicity (all steps succeed or none are applied). If the UPDATE operation is the only operation you are performing and does not depend on other complex logic, you do not need to manually include explicit transactions because SQL Server, by default, wraps single UPDATE statements in an implicit transaction.

Transaction boundaries
Transaction boundaries define the start and end points of a database transaction. They encapsulate a series of operations that must be treated as a single, atomic unit. Within these boundaries, either all operations succeed (commit) or none are applied (rollback) to ensure consistency and integrity of the data.

Components of Transaction Boundaries

1. Start of a Transaction:

   • Marked by BEGIN TRANSACTION in SQL.

   • Indicates the beginning of a logical group of operations.

2. Commit (Successful End):

   • Marked by COMMIT TRANSACTION.

   • Saves all the changes made during the transaction to the database

3. Rollback (Unsuccessful End):

   • Marked by ROLLBACK TRANSACTION.

   • Undoes all changes made during the transaction.

   • Used when an error occurs or a condition fails within the transaction boundary.

4. Implicit and Explicit Transactions:

   • Implicit Transactions: SQL Server wraps individual DML statements like UPDATE, INSERT, or DELETE in a transaction automatically.

   • Explicit Transactions: Developers explicitly define the transaction boundaries using BEGIN TRANSACTION, COMMIT, and ROLLBACK.

The Two Transaction Types
Implicit

• Implicit transactions are automatically managed by SQL Server and automatically start a transaction whenever a data-modifying statement such as INSERT, UPDATE, or DELETE is executed. This is helpful in situations where you want SQL Server to handle the transaction for you without having to manually manage it. This is ideal for simple scripts where you don't need full control over transaction boundaries.

• Implicit transactions are tied to the connection context. If the connection is closed or disconnected, then the transaction will be rolled back automatically.

Explicit

• Explicit transactions are not automatically managed by SQL Server and require you to define (and manage) the transaction boundaries of your SQL actions using the BEGIN TRANSACTION, COMMIT TRANSACTION, and ROLLBACK TRANSACTION commands. This allows more control over when the transaction begins and ends.

• Explicit transactions can span multiple operations and even across multiple batches or procedures as long as the same connection remains open.

Atomicity, Consistency, Isolation, Durability (ACID) Properties (a lot of highfalutin words)

Atomicity:
Transactions are atomic. What this means is that a transaction (UPDATE, INSERT, or DELETE) will either complete entirely or not at all (basically a ROLLBACK).

Consistency:
Transactions move the database from one consistent state to another.
Basically, what this means is that transactions ensure that the database remains in a valid state before and after a transaction. It means all defined rules (constraints, relationships, etc.) are adhered to, preventing data corruption or invalid states. If a transaction violates any constraint, the database reverts to its previous consistent state (basically a ROLLBACK).

Isolation:
This ensures that concurrent transactions (running at the same time) do not interfere with each other which maintains the integrity of each transactions operations. Basically, it allows transactions to execute as if they were running sequentially, preventing issues like dirty reads, non-repeatable reads, or phantom reads, depending on the isolation level.

Durability:
Once a transaction is committed, the changes are permanent, even in the event of a system failure.

When to Include Transactions:

• If multiple statements need to succeed or fail as a group (ACID).

• If the operation involves dependencies or cascading changes across multiple tables. An example of something like this would be deleting a primary parent (ex. customer) record, which requires cascading deletions of all related child records (ex. orders and payments) to maintain referential integrity across the tables.

• If future enhancements might make the procedure more complex.

Performance Considerations

• Implicit transactions could unintentionally incur additional overhead due to SQL Server managing the transaction boundaries automatically.

• Explicit transactions can sometimes be more efficient because you have complete control over when transactions start and end (the boundaries).

• In a high-performance environment you should use explicit transactions to minimize unnecessary transaction overhead and ensure that transactions only last as long as necessary.

Some Randomly Related Stuff
Error Handling and Explicit Transactions
Always use error handling (TRY...CATCH), keep your transactions as short as you can, and only include statements that need to be part of the same transaction.

TRY...CATCH blocks are used to catch errors and perform a ROLLBACK if something goes wrong.

Error Handling and Implicit Transactions
Implicit transactions are more prone to unintended commits if error handling is not properly implemented.

What does this mean? Implicit transactions are automatically committed (by SQL Server) after each individual statement completes successfully (INSERT, UPDATE, DELETE, etc.) without explicit control over the transaction boundaries. If an error occurs mid-operation then the already completed statements cannot be rolled back. This could leave your database in an inconsistent state. Because of this, using error handling and explicit transactions (BEGIN, COMMIT, ROLLBACK) provide you with greater control and ensure atomicity and consistency.

A very simplistic TSQL example of Explicit Transaction
This example code snippet is for illustrative purposes only and does not necessarily represent best coding practices.

declare @theid int = 5

begin try
  begin transaction MyNamedTransaction

    -- insert into "YourSQLTable"
    insert into [dbo].[YourSQLTable] (Column1, Column2, Column3, Column4, Column5)
    values (@theid, 'some text value', 2, 3, getdate())

    -- update "AnotherSQLTable"
    update [dbo].[AnotherSQLTable]
    set [somecolumn] = 1,
    [anothercolumn] = (select [columnname] from [dbo].[YourSQLTable] where [pid] = @theid)
    where [cid] = @theid

  commit transaction MyNamedTransaction
end try
begin catch
  if @@trancount > 0
  begin  
    rollback transaction MyNamedTransaction
  end    
  declare @message nvarchar(2048) = error_message()
  insert into [dbo].[MyErrorLogTable] (ErrorMessage, ErrorDate) values (@message, getdate())
  throw
end catch

Conclusion
Choosing between implicit and explicit transactions depends on the complexity of your database operations.

Implicit transactions are ideal for simple, single-step actions that require atomicity without the need for explicit transaction management.

As operations become more complex and involve multiple actions or tables, explicit transactions provide more control and flexibility.

By understanding implicit and explicit transactions (and when to use them or not), you can ensure your SQL code is both efficient and reliable, maintaining data integrity and minimizing errors.

Overview of Twilio’s Gather Verb

The Gather verb in TwiML (Twilio Markup Language) is used to capture user input during a call. By using the Gather verb, you can prompt users to press keys on their phone’s keypad and respond based on their input.

Step 1: Set Up an Endpoint for Keypad Input

To begin, create an endpoint using ASP.NET Core to serve TwiML that includes the Gather verb. This endpoint provides instructions to the caller and waits for a single digit of input.

Example Implementation

Copy

Copy

using Microsoft.AspNetCore.Mvc;
using Twilio.TwiML;
using Twilio.TwiML.Voice;

[Route("api/[controller]")]
[ApiController]
public class VoiceController : ControllerBase
{
  [HttpGet("gather")]
  public IActionResult Gather()
  {
    var response = new VoiceResponse();

    // create a Gather verb to listen for keypad input
    var gather = new Gather(
      input: new List<Gather.InputEnum> { Gather.InputEnum.Dtmf }, // listen for keypad input
      numDigits: 1, // gather 1 digit
      action: new Uri("https://yourapp.com/api/voice/handle-key") // redirect to handle-key endpoint after gathering input
    );

    gather.Say("Press 1 for sales, 2 for support, or 3 for billing."); // add instructions to the Gather verb
    response.Append(gather); // add the Gather verb to the response
    response.Say("We didn’t receive any input. Please try again."); // provide a fallback if no input is gathered

    return Content(response.ToString(), "application/xml");
  }
}

Step 2: Handle Keypad Input

Create another endpoint to handle the user’s input and respond based on the keypad digit they entered. Once the user provides input, this endpoint processes the received digit and returns an appropriate response based on their selection.

Example Implementation

Copy

Copy

[HttpPost("handle-key")]
public IActionResult HandleKey([FromForm] string Digits)
{
  var response = new VoiceResponse();

  // check the gathered digit and respond accordingly
  switch (Digits)
  {
    case "1":
      response.Say("You pressed 1. Connecting you to sales.");
      // Here you could redirect to another call or add more actions
      break;
    case "2":
      response.Say("You pressed 2. Connecting you to support.");
      // Redirect to support, etc.
      break;
    case "3":
      response.Say("You pressed 3. Connecting you to billing.");
      // Redirect to billing, etc.
      break;
    default:
      response.Say("Invalid option. Please try again.");
      response.Redirect(new Uri("https://yourapp.com/api/voice/gather")); // Redirect back to gather if invalid input
      break;
  }

  return Content(response.ToString(), "application/xml");
}

Step 3: Initiate the Call

Trigger the voice call and direct it to the endpoint created for gathering input (/api/voice/gather).

Example Implementation

Copy

Copy

[HttpPost("handle-key")]
public IActionResult HandleKey([FromForm] string Digits)
{
  var response = new VoiceResponse();

  // check the gathered digit and respond accordingly
  switch (Digits)
  {
    case "1":
      response.Say("You pressed 1. Connecting you to sales.");
      // Here you could redirect to another call or add more actions
      break;
    case "2":
      response.Say("You pressed 2. Connecting you to support.");
      // Redirect to support, etc.
      break;
    case "3":
      response.Say("You pressed 3. Connecting you to billing.");
      // Redirect to billing, etc.
      break;
    default:
      response.Say("Invalid option. Please try again.");
      response.Redirect(new Uri("https://yourapp.com/api/voice/gather")); // Redirect back to gather if invalid input
      break;
  }

  return Content(response.ToString(), "application/xml");
}

Step 3: Initiate the Call

Trigger the voice call and direct it to the endpoint created for gathering input (/api/voice/gather).

Example Implementation

Copy

Copy

var call = CallResource.Create(
  to: new PhoneNumber("+1234567890"), // recipient's phone number
  from: new PhoneNumber("+0987654321"), // your Twilio phone number
  url: new Uri("https://yourapp.com/api/voice/gather")
);

Console.WriteLine($"Voice call initiated with SID: {call.Sid}");

Complete Flow Overview

Call Initiation: A voice call is initiated, and the user is directed to the /api/voice/gather endpoint.

Gather Input: The user hears a message and provides input by pressing a key on their phone.

Input Handling: The digit entered is sent to the /api/voice/handle-key endpoint, which responds based on the user’s choice.

Redirection: If the input is invalid, the user is redirected back to the gather step for another attempt.

Conclusion

Using Twilio’s Gather verb in combination with .NET provides a powerful way to collect user input during calls and handle it dynamically. This approach is ideal for creating interactive voice response (IVR) systems, ensuring a seamless user experience for callers. By implementing TwiML endpoints, you can prompt users, process their input, and respond with tailored actions, all while leveraging Twilio’s scalable communications platform.

The first step was to break down the high-level tasks and produce a Level of Effort (LOE) estimate. While I won't go into detail on each step here, the primary stages included Requirements Gathering and Planning, Webhook Setup, Stream Deserialization and Validation, Database Design and Mapping, SQL Database Work, Testing and Debugging, and finally, Deployment and Documentation.

Below is a very brief breakdown of the development process based on this sample client JSON.

{
  "OrderID": "123",
  "OrderType": "Cash",
  "SubTotal": 8.24,
  "StoreID": 0,
  "CashierID": -99,
  "CustomerID": 3481142,
  "Time": "2020-03-21T10:17:46.3093832-04:00",
  "SalesTax": 0.0,
  "Total": 8.24,
  "TransactionTypeID": 0,
  "Comment": "",
  "TransactionNumber": 56355116,
  "Status": 0,
  "TransactionEntries": [
    {
      "ID": 1,
      "TransactionNumber": 56355116,
      "ItemID": 96197,
      "description": "aspirin",
      "Cost": 0.0,
      "FullPrice": 2.99,
      "Price": 2.99,
      "Quantity": 1.0,
      "Taxable": false,
      "SalesTax": 0.0,
      "TaxAmount": 0.0,
      "Comment": "",
      "DateCreated": "2021-05-10T10:17:26.692389-04:00",
      "Notes": "",
      "ItemLookupCode": "002414763521",
      "SellByWeight": false,
      "CategoryName": "Misc.",
      "OptionDescription": null,
      "OptionDescriptionPrice": null
    },
    {
      "ID": 2,
      "TransactionNumber": 56355116,
      "ItemID": 96100,
      "description": "tylenol",
      "Cost": 0.0,
      "FullPrice": 5.25,
      "Price": 5.25,
      "Quantity": 1.0,
      "Taxable": false,
      "SalesTax": 0.0,
      "TaxAmount": 0.0,
      "Comment": "",
      "DateCreated": "2021-05-10T10:17:26.692389-04:00",
      "Notes": "",
      "ItemLookupCode": "123456763521",
      "SellByWeight": false,
      "CategoryName": "Misc.",
      "OptionDescription": null,
      "OptionDescriptionPrice": null
    }
  ]
}

Step 1: Setup a new Webhook and Controller
To set up the webhook and its corresponding controller, I configured a route in the app.MapControllerRoute method as follows:

app.MapControllerRoute
(
  name: "POSTransactionExportCL",
  pattern: "{controller}/{action}",
  defaults: new { controller = "TheClientControllerName", action = "POSTransactionExportCL" }
);

Note: TheClientControllerName is a placeholder for the actual controller name used in the application. I've replaced the actual name in this example for clarity and confidentiality.

Step 2: Define Model Classes for the JSON Stream
To parse the JSON stream provided by the client, I created two model classes: POSTransactionExportCL_Order and POSTransactionExportCL_TransactionEntry. These classes define the structure of the JSON data and include all the necessary properties for orders and their associated transaction entries. By using these models, the JSON stream is deserialized into a strongly typed structure, ensuring accurate data processing, and simplifying further operations in the application.

Order Model

public class POSTransactionExportCL_Order
{
  public int OrderID { get; set; }
  public string? OrderType { get; set; }
  public decimal SubTotal { get; set; }
  public int StoreID { get; set; }
  public int CashierID { get; set; }
  public int CustomerID { get; set; }
  public DateTime Time { get; set; }
  public decimal SalesTax { get; set; }
  public decimal Total { get; set; }
  public int TransactionTypeID { get; set; }
  public string? Comment { get; set; }
  public long TransactionNumber { get; set; }
  public int Status { get; set; }
  public POSTransactionExportCL_TransactionEntry[]? TransactionEntries { get; set; }
}

Transaction Entry Model

public class POSTransactionExportCL_TransactionEntry
{
  public int ID { get; set; }
  public long TransactionNumber { get; set; }
  public int ItemID { get; set; }
  public string? Description { get; set; }
  public decimal Cost { get; set; }
  public decimal FullPrice { get; set; }
  public decimal Price { get; set; }
  public decimal Quantity { get; set; }
  public bool Taxable { get; set; }
  public decimal SalesTax { get; set; }
  public decimal TaxAmount { get; set; }
  public string? Comment { get; set; }
  public DateTime DateCreated { get; set; }
  public string? Notes { get; set; }
  public string? ItemLookupCode { get; set; }
  public bool SellByWeight { get; set; }
  public string? CategoryName { get; set; }
  public string? OptionDescription { get; set; }
  public decimal? OptionDescriptionPrice { get; set; }
}

Step 3: Created a New "POSTransactionExportCL" Webhook to Handle Incoming Transaction Data from the Client JSON Stream
The POSTransactionExportCL webhook in the client controller is designed to securely and efficiently handle incoming transaction data provided in a JSON stream via POST HTTP requests. Acting as a gateway for processing and storing point-of-sale (POS) transaction details, this webhook ensures that data integrity and security remain top priorities throughout its workflow.

This endpoint validates the client's access token (X-Auth-Token), verifies payload integrity, and stores transaction data in the backend database. The processing pipeline includes token validation, payload deserialization, and database interaction via SQL methods. With comprehensive error handling and logging mechanisms, the webhook provides clear feedback to the client in the event of issues, such as invalid tokens, unauthorized access, or payload formatting errors.

The following code snippet provides the complete implementation of the POSTransactionExportCL webhook:

[HttpPost]
[Route("{controller}/{action}")]
public async Task<IActionResult> POSTransactionExportCL()
{
  string? client_token = Request.Headers["X-Auth-Token"]; // client passed in header - this value is generated from GetPatientData
  string? BodyContent = string.Empty;
  string? actionName = Request.Path; // get the IActionResult controller and name (/Base/IActionResult)

  var config = new ConfigurationBuilder().SetBasePath(Directory.GetCurrentDirectory()).AddJsonFile("appsettings.json"); // read appsettings.json for config settings
  var configuration = config.Build();

  // do the regular token processing
  if (!GeneralFunctions.IsCPTokenValid(client_token!)) // JWT token from the header
  {
    return new ContentResult() { Content = "Unauthorized - X-Auth-Token is invalid", StatusCode = 401 };
  }

  // make sure the client has access to the webhook
  if (!GeneralFunctions.HasEndpointAccess(actionName.Split('/')[2])) // get everything after the second / and check HasEndpointAccess
  {
    GeneralFunctions.LogEndpointCall(actionName.Split('/')[2], $"{client_token} Endpoint access denied: {actionName.Split('/')[2]}");
    return new ContentResult() { Content = $"{client_token} Endpoint access denied", StatusCode = 401 };
  }


  JObject obj; // instantiate empty JObject for reading and processing Body payload
  StreamReader? reader = null; // instantiate empty nullable StreamReader variable
  try
  {
    var httpResponseMessage = HttpContext.Request.Body;
    using(reader = new StreamReader(httpResponseMessage))
      {
        BodyContent = await reader.ReadToEndAsync(); // read the response body
    }

    obj = JObject.Parse(BodyContent); // just to see if we get an error processing the body
    if (!obj.HasValues)
    {
      GeneralFunctions.LogEndpointCall(actionName.Split('/')[2], $"Error: the payload appreasrs to not contain any values");
      return new ContentResult() { Content = $"Error: the payload appreasrs to not contain any values", StatusCode = 500 };
    }

    // check payload parameters
    string payloaderror = String.Empty;
    try
    {
      if ((string?)obj.SelectToken("OrderID") == "" || (string?)obj.SelectToken("OrderID") == String.Empty || (string?)obj.SelectToken("OrderID") == null || string.IsNullOrEmpty((string?)obj.SelectToken("OrderID"))) { payloaderror = "OrderID"; }
      if ((string?)obj.SelectToken("OrderType") == "" || (string?)obj.SelectToken("OrderType") == String.Empty || (string?)obj.SelectToken("OrderType") == null || string.IsNullOrEmpty((string?)obj.SelectToken("OrderType"))) { payloaderror = "OrderType"; }
      if ((string?)obj.SelectToken("CustomerID") == "" || (string?)obj.SelectToken("CustomerID") == String.Empty || (string?)obj.SelectToken("CustomerID") == null || string.IsNullOrEmpty((string?)obj.SelectToken("CustomerID"))) { payloaderror = "CustomerID"; }
      if ((string?)obj.SelectToken("TransactionNumber") == "" || (string?)obj.SelectToken("TransactionNumber") == String.Empty || (string?)obj.SelectToken("TransactionNumber") == null || string.IsNullOrEmpty((string?)obj.SelectToken("TransactionNumber"))) { payloaderror = "TransactionNumber"; }
        if (payloaderror != String.Empty)
        {
        GeneralFunctions.LogEndpointCall(actionName.Split('/')[2], $"{payloaderror} - {payloaderror} missing from payload {JObject.Parse(BodyContent)}");
        return new ContentResult() { Content = $"{payloaderror} - {payloaderror} missing from payload", StatusCode = 422 };
        }
      }
      catch (Exception)
      {
      GeneralFunctions.LogEndpointCall(actionName.Split('/')[2], $"error processing payload: {JObject.Parse(BodyContent)}");
      return new ContentResult() { Content = "error processing payload", StatusCode = 422 };
    }


    POSTransactionExportCL_Order? orderinfo; // declares a variable named orderinfo that will hold an instance of both POSTransactionExportCL_Order/POSTransactionExportCL_TransactionEntry classes
    try
    {
      // deserialize the JSON stream (body) into the orderinfo object
      orderinfo = JsonConvert.DeserializeObject<POSTransactionExportCL_Order>(BodyContent);
    }
    catch (JsonException ex)
    {
      return new ContentResult() { Content = $"Invalid JSON format: {ex.Message}", StatusCode = 422 };
    }

    try
    {
      // call the POSTransactionExportCLSQL SQL processing method
      // write everything to the POSTransactionExportCL table
      // write everything to the POSTransactionExportCLTransactionEntries table
      // using cp_APIPOSTransactionExportCL and cp_APIPOSTransactionEntryExportCL
      string status = await POSTransactionExportCLSQL(orderinfo!);
    }
    catch (Exception ex)
    {
      return new ContentResult() { Content = $"Error: POSTransactionExportCLSQL: {ex.Message}", StatusCode = 422 };
      }
    }
    catch (Exception)
  {
    GeneralFunctions.LogEndpointCall(actionName.Split('/')[2], $"Error reading payload: {JObject.Parse(BodyContent)}");
    return new ContentResult() { Content = "Error reading payload", StatusCode = 500 };
  }

  return new ContentResult() { Content = $"POSTransactionExportCL - success - {client_token}", StatusCode = 200 };
}

At its core, the webhook performs essential operations such as validating access tokens, verify that the client has access to the webhook, verify payload integrity, and write transaction data to specific database tables. With a focus on security, it checks the client's authentication and authorization before processing any request. The incoming payload undergoes validation to ensure the required data is present and formatted correctly. Any anomalies in the process are logged for traceability, and detailed error responses are provided to the client for troubleshooting.

Below is an overview of its key components:

Attributes and Routing

• [HttpPost]: The method handles POST requests.

• [Route("{controller}/{action}")]: Defines a dynamic route based on the controller and action name.

Primary Steps

1. Token Validation

• The client sends an X-Auth-Token in the request headers.

• The token is validated using GeneralFunctions.IsCPTokenValid.

• If the token is invalid, the method returns a 401 Unauthorized response

2. Access Control

• Extracts the endpoint name from the request path.

• Uses GeneralFunctions.HasEndpointAccess to determine if the token has access to the requested endpoint.

• Logs unauthorized attempts and returns a 401 response if access is denied.

3. Payload Parsing

• Reads the request body and ensures it's valid JSON using JObject.Parse.

• Checks for required fields (OrderID, OrderType, CustomerID, TransactionNumber).

• Logs and returns an error if required fields are missing.

4. Deserialization

• Converts the JSON payload into a POSTransactionExportCL_Order object using JsonConvert.DeserializeObject.

• Handles any deserialization errors gracefully with appropriate logging.

5. Database Interaction

• Processes the order and its transactions using POSTransactionExportCLSQL.

• Writes data into tables (POSTransactionExportCL and POSTransactionExportCLTransactionEntries) via stored procedures.

6. Error Handling

• Comprehensive error handling is implemented at every stage, including token validation, payload parsing, and database interaction.

• Logs specific error details for debugging and returns appropriate HTTP status codes to the client.

7. Response Codes

• 200 OK: Indicates successful processing.

• 401 Unauthorized: Token validation or access control failure.

• 422 Unprocessable Entity: Errors in payload structure or content.

• 500 Internal Server Error: Unexpected errors during payload reading or processing.

Key Highlights

• Dynamic Configuration: Reads configuration from appsettings.json for flexibility.

• Logging: Logs all significant events and errors, aiding in troubleshooting and monitoring.

• Validation-Driven Workflow: Ensures token authenticity, endpoint permissions, and payload integrity before proceeding.

• Modular Structure: Separates concerns like token validation, payload parsing, and database interaction for better maintainability.

Step 4: The SQL Method
The POSTransactionExportCLSQL method is responsible for exporting point-of-sale (POS) order data and its associated transaction entries to the SQL database.

public static async Task<string> POSTransactionExportCLSQL(POSTransactionExportCL_Order orderinfo)
{
  int rowsAffected = 0;
  string retval = string.Empty;
  string pkid = string.Empty;

  if (orderinfo == null)
  {
    return "Invalid order information provided.";
  }


  try
  {
    var config = new ConfigurationBuilder().SetBasePath(Directory.GetCurrentDirectory()).AddJsonFile("appsettings.json"); // read appsettings.json for config settings
    var configuration = config.Build();
    string? _sql_con_str = configuration["sqlsettings:cphdbintegrated"];

    using (var _sql_con = new System.Data.SqlClient.SqlConnection(_sql_con_str))
    {
      await _sql_con.OpenAsync();

      // insert order data (from orderinfo class)
      using (var _sql_cmd = new System.Data.SqlClient.SqlCommand("cp_APIPOSTransactionExportCL", _sql_con))
      {
        _sql_cmd.CommandType = System.Data.CommandType.StoredProcedure;

        // Add Order parameters
        _sql_cmd.Parameters.AddWithValue("@OrderID", orderinfo.OrderID);
        _sql_cmd.Parameters.AddWithValue("@OrderType", orderinfo.OrderType);
        _sql_cmd.Parameters.AddWithValue("@SubTotal", orderinfo.SubTotal);
        _sql_cmd.Parameters.AddWithValue("@StoreID", orderinfo.StoreID);
        _sql_cmd.Parameters.AddWithValue("@CashierID", orderinfo.CashierID);
        _sql_cmd.Parameters.AddWithValue("@CustomerID", orderinfo.CustomerID);
        _sql_cmd.Parameters.AddWithValue("@Time", orderinfo.Time);
        _sql_cmd.Parameters.AddWithValue("@SalesTax", orderinfo.SalesTax);
        _sql_cmd.Parameters.AddWithValue("@Total", orderinfo.Total);
        _sql_cmd.Parameters.AddWithValue("@TransactionTypeID", orderinfo.TransactionTypeID);
        _sql_cmd.Parameters.AddWithValue("@Comment", orderinfo.Comment);
        _sql_cmd.Parameters.AddWithValue("@TransactionNumber", orderinfo.TransactionNumber);
        _sql_cmd.Parameters.AddWithValue("@Status", orderinfo.Status);

        // Execute the query and read the result
        using (var reader = await _sql_cmd.ExecuteReaderAsync())
        {
          if (await reader.ReadAsync())
          {
            pkid = reader["theGUID"].ToString()!;
          }
        }
      }

      if (IsNull(pkid)) { return "error - parent pkid is null"; }

      using (var _sql_cmd = new System.Data.SqlClient.SqlCommand("cp_APIPOSTransactionEntryExportCL", _sql_con))
      {
        _sql_cmd.CommandType = System.Data.CommandType.StoredProcedure;

        // insert transactionentries data (from POSTransactionExportCL_TransactionEntry)
        foreach (var entry in orderinfo.TransactionEntries!)
        {
          _sql_cmd.Parameters.Clear();

          // Add TransactionEntry parameters
          _sql_cmd.Parameters.AddWithValue("@pkid", pkid);
          _sql_cmd.Parameters.AddWithValue("@ID", entry.ID);
          _sql_cmd.Parameters.AddWithValue("@OrderID", orderinfo.OrderID);
          _sql_cmd.Parameters.AddWithValue("@TransactionNumber", entry.TransactionNumber);
          _sql_cmd.Parameters.AddWithValue("@ItemID", entry.ItemID);

          _sql_cmd.Parameters.AddWithValue("@Description", entry.Description ?? "");

          _sql_cmd.Parameters.AddWithValue("@Cost", entry.Cost);
          _sql_cmd.Parameters.AddWithValue("@FullPrice", entry.FullPrice);
          _sql_cmd.Parameters.AddWithValue("@Price", entry.Price);
          _sql_cmd.Parameters.AddWithValue("@Quantity", entry.Quantity);
          _sql_cmd.Parameters.AddWithValue("@Taxable", entry.Taxable);
          _sql_cmd.Parameters.AddWithValue("@SalesTax", entry.SalesTax);
          _sql_cmd.Parameters.AddWithValue("@TaxAmount", entry.TaxAmount);
          _sql_cmd.Parameters.AddWithValue("@Comment", entry.Comment ?? "");
          _sql_cmd.Parameters.AddWithValue("@DateCreated", entry.DateCreated);
          _sql_cmd.Parameters.AddWithValue("@Notes", entry.Notes ?? "");
          _sql_cmd.Parameters.AddWithValue("@ItemLookupCode", entry.ItemLookupCode ?? "");
          _sql_cmd.Parameters.AddWithValue("@SellByWeight", entry.SellByWeight);
          _sql_cmd.Parameters.AddWithValue("@CategoryName", entry.CategoryName ?? "");
          _sql_cmd.Parameters.AddWithValue("@OptionDescription", entry.OptionDescription ?? "");
          _sql_cmd.Parameters.AddWithValue("@OptionDescriptionPrice", entry.OptionDescriptionPrice ?? 0);

          await _sql_cmd.ExecuteNonQueryAsync();
        }
      }


    }
  }
  catch (Exception ex)
  {
    // log the error to the error logging table
    GeneralFunctions.LogError("POSTransactionExportCLSQL", ex, orderinfo);
    return $"Error: {ex.Message}";
  }

  return rowsAffected.ToString();
}

Here is an overview of its key operations:

Input Validation:

• Validates the orderinfo parameter to ensure it contains valid order data. If null, it returns an error message immediately.

Database Connection Setup:

• Reads connection settings from an appsettings.json file using ConfigurationBuilder.

• Establishes a SQL connection using the provided connection string.

Order Data Export:

• Executes the stored procedure cp_APIPOSTransactionExportCL to insert order-related data into the database. Parameters such as OrderID, OrderType, SubTotal, and others are mapped from the orderinfo object.

• Captures a primary key (theGUID) returned by the stored procedure for use in subsequent operations.

Transaction Entries Export:

• Iterates through the TransactionEntries collection within the orderinfo object.

• For each transaction entry, executes the cp_APIPOSTransactionEntryExportCL stored procedure to store detailed transaction data, including item details, pricing, tax information, and additional metadata.

Error Handling:

• Wraps operations in a try-catch block to handle exceptions.

• Logs any errors encountered using the GeneralFunctions.LogError method and returns a descriptive error message.

Return Value:

• Returns the number of rows affected or an appropriate error message.

Use Cases
This method is well-suited for scenarios requiring:

• Batch processing of POS orders and their line items into a database.

• Structured logging of errors for troubleshooting.

• Integration with a broader POS or order management system.

Considerations:

• The method relies on two stored procedures for database operations, promoting modularity.

• SQL injection risks are mitigated by using parameterized queries.

Step 5: The SQL Table Structure

drop table if exists [POSTransactionExportCLTransactionEntries]
go

drop table if exists [POSTransactionExportCL]
go


-- parent table (Order Entries)
create table [POSTransactionExportCL]
(
  [pkid] uniqueidentifier not null unique,
  [OrderID] int,
  [OrderType] nvarchar(50),
  [SubTotal] decimal(18, 2),
  [StoreID] int,
  [CashierID] int,
  [CustomerID] int,
  [Time] datetime,
  [SalesTax] decimal(18, 2),
  [Total] decimal(18, 2),
  [TransactionTypeID] int,
  [Comment] nvarchar(255),
  [TransactionNumber] bigint,
  [Status] int,
  primary key ([pkid]) -- define primary key (parent)
  )
go



-- child table (Transaction Entries)
create table [POSTransactionExportCLTransactionEntries]
(
  [pkid] uniqueidentifier not null, -- this will be the pkid value from POSTransactionExportCL
  [ID] int,
  [OrderID] int,
  [TransactionNumber] bigint,
  [ItemID] int,
  [Description] nvarchar(255) null,
  [Cost] decimal(18, 2) null,
  [FullPrice] decimal(18, 2) null,
  [Price] decimal(18, 2) null,
  [Quantity] decimal(18, 2) null,
  [Taxable] bit null,
  [SalesTax] decimal(18, 2) null,
  [TaxAmount] decimal(18, 2) null,
  [Comment] nvarchar(255) null,
  [DateCreated] datetime null,
  [Notes] nvarchar(255) null,
  [SellByWeight] bit null,
  [CategoryName] nvarchar(50) null,
  [OptionDescription] nvarchar(255) null,
  [OptionDescriptionPrice] decimal(18, 2) null,
  foreign key ([pkid]) references [POSTransactionExportCL] ([pkid]) -- define foreign key relationship (Child)
)

go

The table structure defines a parent-child relationship between POSTransactionExportCL and POSTransactionExportCLTransactionEntries, designed for managing point-of-sale (POS) transactions and their associated entries.

Parent Table: POSTransactionExportCL
This table serves as the central repository for order-level transaction data. Each row uniquely identifies an order using the pkid column, a uniqueidentifier serving as the primary key. Key fields include OrderID, OrderType, StoreID, CashierID, and financial details such as SubTotal, SalesTax, and Total. It provides a high-level overview of transactions.

Child Table: POSTransactionExportCLTransactionEntries
This table stores detailed line-item entries associated with transactions in the parent table. The pkid column in this table is a foreign key referencing the pkid in the parent table, establishing the relationship. Each row represents an individual item or transaction entry, including details such as ItemID, Description, Price, Quantity, and Taxable status. It supports a comprehensive breakdown of items sold, returned, or discounted.

Key Features:

• The parent table enforces referential integrity through a primary key on pkid.

• The child table maintains a foreign key constraint on pkid, ensuring that all entries correspond to a valid transaction in the parent table.

• This structure supports efficient querying and reporting, enabling quick joins between orders and their detailed line items.

Step 6: The SQL Stored Procedures
cp_APIPOSTransactionExportCL
This stored procedure is responsible for populating the POSTransactionExportCL table with detailed transaction data from a Point of Sale (POS) system. It takes multiple parameters representing key attributes of a transaction, such as order information, store and cashier IDs, customer details, and transaction metadata.

drop procedure if exists [dbo].[cp_APIPOSTransactionExportCL]
go


set ansi_nulls on
go

set quoted_identifier on
go



create procedure [dbo].[cp_APIPOSTransactionExportCL]
  @OrderID int,
  @OrderType nvarchar(50),
  @SubTotal decimal(18, 2),
  @StoreID int,
  @CashierID int,
  @CustomerID int,
  @Time datetime,
  @SalesTax decimal(18, 2),
  @Total decimal(18, 2),
  @TransactionTypeID int,
  @Comment nvarchar(max),
  @TransactionNumber nvarchar(50),
  @Status nvarchar(50)
as
begin
    set nocount on;
    begin try
      declare @theGUID as uniqueidentifier = newid()
      declare @p_namedtransaction varchar(60) = 'cp_APIPOSTransactionExportCL'

      begin transaction @p_namedtransaction
        insert into POSTransactionExportCL
        (
          [pkid],
          [OrderID],
          [OrderType],
          [SubTotal],
          [StoreID],
          [CashierID],
          [CustomerID],
          [Time],
          [SalesTax],
          [Total],
          [TransactionTypeID],
          [Comment],
          [TransactionNumber],
          [Status]
        )
        values
        (
          @theGUID,
          @OrderID,
          @OrderType,
          @SubTotal,
          @StoreID,
          @CashierID,
          @CustomerID,
          @Time,
          @SalesTax,
          @Total,
          @TransactionTypeID,
          @Comment,
          @TransactionNumber,
          @Status
        )
      commit transaction @p_namedtransaction
      select @theGUID as [theGUID] -- return for cp_APIPOSTransactionEntryExportCL
    end try
    begin catch
      if @@trancount > 0
        rollback transaction @p_namedtransaction;
      throw;
    end catch
end
go

Key Features:

1. Primary Purpose

• Inserts a new record into the POSTransactionExportCL table using the provided parameters.

• Assigns a unique identifier (uniqueidentifier) to each transaction for tracking and reference.

2. Transactional Safety

• Uses an explicit named transaction (@p_namedtransaction) to ensure atomicity. This prevents partial inserts by rolling back the transaction in case of an error.

• Includes structured error handling with a TRY...CATCH block to handle potential issues during execution.

3. Parameters

• The procedure accepts a range of input parameters, such as:

• Order Details: @OrderID, @OrderType, @SubTotal, @SalesTax, @total.

• Entity Identifiers: @StoreID, @CashierID, @CustomerID.

• Transaction Metadata: @time, @TransactionTypeID, @Comment, @TransactionNumber, @Status.

4. Output

• Returns the generated unique identifier (@theGUID) for the newly inserted record. This @theGUID variable is then used by cp_APIPOSTransactionEntryExportCL, to insert records into the POSTransactionExportCLTransactionEntries child table.

5. Resiliency

• The NOCOUNT setting is enabled to reduce overhead from row count messages.

• Proper use of BEGIN TRANSACTION and COMMIT TRANSACTION ensures data integrity.

6. Benefits

• Data Integrity: The use of transactions ensures that either all or none of the data is written.

• Scalability: Designed to handle a variety of transaction scenarios, from in-store to online orders.

• Traceability: The generated unique identifier (@theGUID) allows easy identification and troubleshooting.

This procedure plays a critical role in maintaining a reliable record of POS transactions, which is essential for reporting, auditing, and analytics.

POSTransactionExportCLTransactionEntries
This stored procedure is designed to populate the POSTransactionExportCLTransactionEntries table with detailed order transaction entries, breaking down the specifics of each item within a transaction and complements the cp_APIPOSTransactionExportCL procedure, which logs the high-level transaction details.

drop procedure if exists [dbo].[cp_APIPOSTransactionEntryExportCL]
go

set ansi_nulls on
go

set quoted_identifier on
go


create procedure [dbo].[cp_APIPOSTransactionEntryExportCL]
  @pkid uniqueidentifier,
  @ID int,
  @OrderID int,
  @TransactionNumber bigint,
  @ItemID int,
  @Description nvarchar(255),
  @Cost decimal(18, 2),
  @FullPrice decimal(18, 2),
  @Price decimal(18, 2),
  @Quantity decimal(18, 2),
  @Taxable bit,
  @SalesTax decimal(18, 2),
  @TaxAmount decimal(18, 2),
  @Comment nvarchar(255),
  @DateCreated datetime,
  @Notes nvarchar(255),
  @ItemLookupCode nvarchar(50),
  @SellByWeight bit,
  @CategoryName nvarchar(50),
  @OptionDescription nvarchar(255),
  @OptionDescriptionPrice decimal(18, 2)
as
begin
  set nocount on;
    begin try
      declare @theGUID as uniqueidentifier = newid()
      declare @p_namedtransaction varchar(60) = 'cp_APIPOSTransactionExportCL'

      begin transaction @p_namedtransaction
        insert into [POSTransactionExportCLTransactionEntries]
        (
          [pkid],
          [ID],
          [OrderID],
          [TransactionNumber],
          [ItemID],
          [Description],
          [Cost],
          [FullPrice],
          [Price],
          [Quantity],
          [Taxable],
          [SalesTax],
          [TaxAmount],
          [Comment],
          [DateCreated],
          [Notes],
          [ItemLookupCode],
          [SellByWeight],
          [CategoryName],
          [OptionDescription],
          [OptionDescriptionPrice]
        )
        values
        (
          @pkid,
          @ID,
          @OrderID,
          @TransactionNumber,
          @ItemID,
          @Description,
          @Cost,
          @FullPrice,
          @Price,
          @Quantity,
          @Taxable,
          @SalesTax,
          @TaxAmount,
          @Comment,
          @DateCreated,
          @Notes,
          @ItemLookupCode,
          @SellByWeight,
          @CategoryName,
          @OptionDescription,
          @OptionDescriptionPrice
        )
      commit transaction @p_namedtransaction
      select @theGUID as [theGUID] -- return this value for cp_APIPOSTransactionEntryExportCL
    end try
    begin catch
      if @@trancount > 0
        rollback transaction @p_namedtransaction;
      throw;
    end catch
end
go

Key Features:

1. Purpose

• Inserts itemized transaction details into the POSTransactionExportCLTransactionEntries table.

• Handles granular data, including pricing, taxes, discounts, quantities, and metadata for individual items in an order.

2. Parameters

• Transaction Identifiers: @pkid links the entry to the primary transaction, while @id and @OrderID help identify the item within the context of the transaction.

• Item-Specific Details: @ItemID, @Description, @Cost, @price, @FullPrice, @Taxable, and @Quantity describe the item and its financial attributes.

• Additional Metadata: Fields like @Notes, @ItemLookupCode, @CategoryName, and @OptionDescription add context for reporting or customer service.

3. Transactional Integrity

• The procedure employs a named transaction to ensure that the insertion is atomic, meaning it is either fully successful or fully rolled back in case of an error.

• A unique identifier (@theGUID) is generated and returned for referencing the specific entry.

4. Error Handling

• A TRY...CATCH block ensures that any errors encountered during execution result in a rollback of the transaction, maintaining data integrity.

5. Output

• The unique identifier (@theGUID) of the inserted entry is returned, enabling seamless linking and traceability.

6. Benefits

• Comprehensive Tracking: Captures detailed item-level data for every transaction, crucial for inventory management, tax calculations, and customer service.

• Flexibility: The numerous parameters allow the procedure to handle a wide range of item types and transaction scenarios.

• Auditability: By linking to the primary transaction (@pkid) and generating unique identifiers, it supports clear and traceable records.

This procedure is a critical component of the POS system, ensuring that all transaction details are recorded and accessible for business operations, analysis, and compliance purposes.

A Note About Using System.Data.SqlClient
In this system, I have chosen to use System.Data.SqlClient for database interactions due to its ability to provide high-performance, low-level access to the SQL Server database. This approach is particularly important in scenarios where I need to process large JSON streams efficiently and with minimal latency and minimizes overhead and provides the flexibility required for performance optimization.

While Entity Framework is good for working with databases in higher-level applications, its abstraction layers can introduce unnecessary overhead, which can be a limitation when the goal is to maximize speed, optimization, and resource utilization. By opting for System.Data.SqlClient, I avoid this overhead for more efficient database access and faster processing times - both key factors when dealing with high-performance tasks such as JSON stream processing and data-intensive operations.

In summary, the use of System.Data.SqlClient ensures that the system can handle complex, performance-critical database tasks with greater precision and speed, allowing for the optimization of stored procedure execution and overall system responsiveness.

Conclusion
Developing a custom webhook to process a client-supplied POS JSON stream required a strategic approach to ensure efficiency, accuracy, and security. By breaking down the task into manageable stages - from webhook setup and model definition to SQL database design and stored procedure creation, I was able to deliver a robust solution that seamlessly integrates with the client's data stream.

Using strongly typed C# model classes and carefully crafted SQL structures, the implementation ensures data consistency and simplifies debugging. Additionally, the modular design of the webhook also provides a foundation for extending functionality and supporting additional future integrations.