CG.Infrastructure.Calendar 3.10.2

CG.Infrastructure.Calendar

A comprehensive calendar and time management library that provides business logic for working with dates, times, work schedules, and holiday calculations in .NET applications.

Overview

CG.Infrastructure.Calendar is a specialized library that extends the core infrastructure with comprehensive calendar functionality. It provides business logic for working with work schedules, holiday calculations, time tracking, and various calendar operations commonly needed in business applications.

Features

• Date and Time Utilities: Comprehensive date manipulation and calculation methods
• Work Schedule Management: Calculate working hours, lunch breaks, and time tracking
• Holiday Calculations: UK bank holiday calculations with automatic weekend adjustments
• Tax Year Support: UK tax year and period calculations
• Day Type Classification: Support for various day types (weekday, weekend, bank holiday, leave, etc.)
• Time Zone Support: Time zone aware operations
• Flexible Time Calculations: Calculate flexi time, hours worked, and time remaining
• Configuration Integration: Seamless integration with .NET configuration system

Requirements

• .NET 9.0 or later
• CG.Infrastructure.Core 3.10.4+
• Microsoft.Extensions.Configuration.Abstractions 9.0.7+
• Microsoft.Extensions.Configuration.Binder 9.0.7+

Installation

dotnet add package CG.Infrastructure.Calendar

Or add the following to your .csproj file:

<PackageReference Include="CG.Infrastructure.Calendar" Version="3.10.0" />

Quick Start

1. Configure Calendar Options

Add configuration to your appsettings.json:

{
  "CalendarOptions": {
    "StartDate": "2024-01-01",
    "WorkingHours": "08:00",
    "LunchBreak": "01:00"
  }
}

2. Register Services

In your Program.cs or Startup.cs:

using Infrastructure.Calendar.Extensions;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

// Register calendar services with configuration
builder.Services.RegisterInfraCalendarServices(builder.Configuration);

var app = builder.Build();

3. Use the Calendar Service

[ApiController]
[Route("[controller]")]
public class TimeTrackingController : ControllerBase
{
    private readonly ICalendarService _calendarService;

    public TimeTrackingController(ICalendarService calendarService)
    {
        _calendarService = calendarService;
    }

    [HttpGet("work-hours")]
    public ActionResult<TimeSpan> GetWorkHours(DateTime start, DateTime lunch, DateTime back)
    {
        var startOffset = _calendarService.GetDateTimeOffset(start);
        var lunchOffset = _calendarService.GetDateTimeOffset(lunch);
        var backOffset = _calendarService.GetDateTimeOffset(back);

        var hoursWorked = _calendarService.GetWorkedToday(startOffset, lunchOffset, backOffset);
        return Ok(hoursWorked);
    }
}

Core Functionality

Date and Time Operations

// Get start and end of week
var startOfWeek = _calendarService.GetStartOfWeek(DateTimeOffset.Now);
var endOfWeek = _calendarService.GetEndOfWeek(DateTimeOffset.Now);

// Get end of month
var endOfMonth = _calendarService.GetEndOfMonth(DateTimeOffset.Now);

// Get week number
var weekNumber = _calendarService.GetWeekNumber(DateTimeOffset.Now, CalendarWeekRule.FirstFullWeek);

Tax Year Calculations

// Get tax year (UK tax year starts April 6th)
var taxYear = _calendarService.GetTaxYearFromDate(DateTimeOffset.Now);

// Get tax period (1-12, where 1 = April)
var taxPeriod = _calendarService.GetTaxPeriodFromDate(DateTimeOffset.Now);

Work Schedule Management

// Calculate hours worked today
var hoursWorked = _calendarService.GetWorkedToday(start, lunch, back);

// Calculate remaining time today
var timeLeft = _calendarService.GetLeftToday(hoursWorked, expectedHours);

// Calculate finish time
var finishTime = _calendarService.GetFinishToday(start, lunch, back, finish, worked, left);

// Calculate lunch break duration
var lunchDuration = _calendarService.GetLunchBreak(start, finish);

Day Type Classification

// Determine day type
var dayType = _calendarService.GetDayType(DateTimeOffset.Now);

// Get expected hours for day type
var expectedHours = _calendarService.GetDayTypeHours(dayType);

// Calculate days worked based on day type
var daysWorked = _calendarService.GetDaysWorked(dayType);

Holiday and Leave Management

// Calculate holiday taken (full and half days)
var holidayTaken = _calendarService.GetHolidayTaken(fullDays, halfDays);

// Get UK bank holidays for a year
var holidays = CalendarService.GetHolidays(2024);

// Check if date is a bank holiday
var isBankHoliday = _calendarService.GetDayType(date) == DayTypeEnum.BankHoliday;

Time Zone Operations

// Get midnight in specific time zone
var midnightInTz = _calendarService.MidnightInTimeZone(date, "Europe/London");

// Convert DateTime to DateTimeOffset
var dateTimeOffset = _calendarService.GetDateTimeOffset(dateTime);

// Parse date from string
var parsedDate = _calendarService.GetDateFromString("2024-01-01");

Flexi Time Calculations

// Calculate flexi time (difference between worked and expected)
var flexiTime = _calendarService.GetFlexi(hoursWorked, expectedHours);

// Generate time list for scheduling
var timeSlots = _calendarService.GetTimeList(date, 30); // 30-minute intervals

Configuration Options

The library supports configuration through CalendarOptions:

Day Types

The library supports various day types through DayTypeEnum:

• Weekday: Standard working day
• Weekend: Saturday and Sunday
• BankHoliday: UK bank holidays
• AnnualLeave: Annual leave days
• HalfDay: Half working day
• Training: Training days
• Sick: Sick leave days
• CompassionateLeave: Compassionate leave
• PaternityLeave: Paternity leave
• Special: Special working days
• Toil: Time off in lieu
• NonWorking: Non-working days
• WellBeing: Well-being days
• Giving: Charity/volunteer days

Dependencies

• CG.Infrastructure.Core: Provides the base service infrastructure and dependency injection support
• Microsoft.Extensions.Configuration.Abstractions: Configuration system integration
• Microsoft.Extensions.Configuration.Binder: Configuration binding support

Integration with Core Infrastructure

This library extends the core infrastructure by:

1. Implementing IService: Integrates with the automatic service registration system
2. Configuration Binding: Automatically binds configuration sections to options
3. Dependency Injection: Seamlessly integrates with the DI container
4. Service Extensions: Provides extension methods for easy service registration

Contributing

This library is part of the CG Infrastructure suite. For contributions, please follow the established patterns and ensure all tests pass.

License

This project is licensed under the terms specified in the LICENSE file.

Version History

• 3.10.0: Current stable release
• Supports .NET 9.0
• Includes comprehensive calendar and time management capabilities
• Provides UK-specific business logic for tax years and bank holidays
• Integrates with the core infrastructure service registration system

Support

For issues, questions, or contributions, please refer to the project repository or contact the maintainers.