Working with Calendars

Creating a Calendar

Calendars in Microsoft Project define working and non-working time, directly impacting task scheduling and resource availability. In Aspose.Tasks for .NET, calendars can be created using the Calendar class, which provides three constructor overloads:

• Calendar() – Initializes a default calendar.
• Calendar(int id) – Initializes a calendar with a specific ID.
• Calendar(string name) – Initializes a calendar with a specified name.

The following code sample demonstrates how to instantiate calendars using each constructor. Once generated, calendars can be viewed in Microsoft Project by navigating to Project > Project Information.

Project information showing the calendars

// Create a project instance
Project project = new Project();

// New calendar can be added to a project's calendar collection using the collection's Add method.
Calendar cal1 = project.Calendars.Add("New Info");
Calendar cal2 = project.Calendars.Add("no name");
Calendar cal3 = project.Calendars.Add("cal3");

project.Save("CreatingCalendar_out.Xml", SaveFileFormat.XML);

Defining Weekdays for a Calendar

The Days collection of the Calendar class represents working days and their associated time ranges. Weekday definitions are modeled through the WeekDay and WorkingTime classes.

Developers can use CreateDefaultWorkingDay() to initialize standard hours for a given weekday, or set custom working intervals via the FromTime and ToTime properties.

The sample below defines Monday to Thursday as default working days, and Friday with custom working hours. To verify the result in Microsoft Project, go to Tools > Change Working Time.

Defining weekdays in Microsoft Project

// This example shows how Aspose.Tasks API can be used to define a new Calendar, add week days to it and define working times for days
// Create a project instance
Project project = new Project();

// Define Calendar
Calendar cal = project.Calendars.Add("Calendar1");

// Add working days monday through thursday with default timings
cal.WeekDays.Add(WeekDay.CreateDefaultWorkingDay(DayType.Monday));
cal.WeekDays.Add(WeekDay.CreateDefaultWorkingDay(DayType.Tuesday));
cal.WeekDays.Add(WeekDay.CreateDefaultWorkingDay(DayType.Wednesday));
cal.WeekDays.Add(WeekDay.CreateDefaultWorkingDay(DayType.Thursday));
cal.WeekDays.Add(new WeekDay(DayType.Saturday));
cal.WeekDays.Add(new WeekDay(DayType.Sunday));

// Set friday as short working day
WeekDay myWeekDay = new WeekDay(DayType.Friday);

// Sets working time. Only time part of DateTime is important
WorkingTime wt1 = new WorkingTime();
wt1.FromTime = new DateTime(1, 1, 1, 9, 0, 0, 0);
wt1.ToTime = new DateTime(1, 1, 1, 12, 0, 0, 0);
WorkingTime wt2 = new WorkingTime();
wt2.FromTime = new DateTime(1, 1, 1, 13, 0, 0, 0);
wt2.ToTime = new DateTime(1, 1, 1, 16, 0, 0, 0);
myWeekDay.WorkingTimes.Add(wt1);
myWeekDay.WorkingTimes.Add(wt2);
myWeekDay.DayWorking = true;
cal.WeekDays.Add(myWeekDay);

project.Save("Project_DefineCalendarWeekdays_out.xml", SaveFileFormat.XML);

Replacing a Calendar

Base calendars serve as templates for resource and task scheduling. Aspose.Tasks allows replacing an existing calendar by accessing the CalendarCollection via the Project object.

Supported base calendar types include:

• Standard: Monday–Friday, 08:00–17:00.
• 24-Hours: Used for continuous work schedules.
• Night Shift: Monday night to Saturday morning, 23:00–08:00.

The code below demonstrates how to remove an existing calendar and add a new standard calendar to the collection.

// Create project
Project project = new Project("New Project.mpp");

// Access project calendars
CalendarCollection calColl = project.Calendars;
foreach (Calendar myCalendar in calColl)
{
    if (myCalendar.Name == "TestCalendar")
    {
        // Remove calendar
        calColl.Remove(myCalendar);
    }
}

// Add new calendar
Calendar newCalendar = calColl.Add("TestCalendar");
project.Save("ReplaceCalendar_out.mpp", SaveFileFormat.MPP);

Creating a Standard Calendar

A standard calendar defines default working days and hours commonly used in project schedules. Aspose.Tasks provides two static methods to facilitate this:

• MakeStandardCalendar() – Creates a new calendar with standard configuration.
• MakeStandardCalendar(Calendar cal) – Converts an existing calendar to standard.

To inspect the result in Microsoft Project, use Tools > Change Working Time.

The Change Working Times Information dialogue shows the standard calendar used by the project

// Create a project instance
Project project = new Project();

// Define Calendar and make it standard
Calendar cal1 = project.Calendars.Add("My Cal");
Calendar.MakeStandardCalendar(cal1);

project.Save("Project_MakeStandardCalendar_out.xml", SaveFileFormat.XML);

Writing Updated Calendar Data to MPP

Aspose.Tasks allows updating calendar definitions and saving them back into an MPP file. The process involves:

1. Loading the existing MPP file.
2. Modifying the calendar collection (add, update).
3. Saving the updated project back to disk.

The following example demonstrates adding a new calendar and writing it back to the source MPP file.

Project project = new Project("New Project.mpp");
Calendar cal = project.Calendars.GetByUid(3);

// Update the calendar information
Calendar.MakeStandardCalendar(cal);
cal.Name = "Test calendar";
CalendarException exc = new CalendarException();
exc.FromDate = DateTime.Now;
exc.ToDate = DateTime.Now.AddDays(2);
exc.DayWorking = true;

WorkingTime wt1 = new WorkingTime();
wt1.FromTime = new DateTime(10, 1, 1, 9, 0, 0);
wt1.ToTime = new DateTime(10, 1, 1, 13, 0, 0);

WorkingTime wt2 = new WorkingTime();
wt2.FromTime = new DateTime(10, 1, 1, 14, 0, 0);
wt2.ToTime = new DateTime(10, 1, 1, 19, 0, 0);

WorkingTime wt3 = new WorkingTime();
wt3.FromTime = new DateTime(10, 1, 1, 20, 0, 0);
wt3.ToTime = new DateTime(10, 1, 1, 21, 0, 0);

exc.WorkingTimes.Add(wt1);
exc.WorkingTimes.Add(wt2);
exc.WorkingTimes.Add(wt3);
cal.Exceptions.Add(exc);

CalendarException exc2 = new CalendarException();
exc2.FromDate = DateTime.Now.AddDays(7);
exc2.ToDate = exc2.FromDate;
exc2.DayWorking = false;
cal.Exceptions.Add(exc2);

project.Set(Prj.Calendar, cal);

project.Save("WriteUpdatedCalendarDataToMPP_out.mpp", SaveFileFormat.MPP);