| name | devexpress-blazor-scheduler |
| description | Build and configure the DevExpress Blazor Scheduler (DxScheduler) — a calendar/appointment scheduling component for Blazor Server, WebAssembly, and Hybrid apps. Use for day/week/work-week/month/timeline views; data binding via DxSchedulerDataStorage and AppointmentMappings; appointment creation, editing, deletion, drag-and-drop and resize; recurring appointments (RecurrenceInfo / recurrence rules); resources (rooms/people); labels/statuses; and time/work-time configuration. Also use for DxScheduler, scheduler, calendar, appointment calendar, recurring appointments, and scheduling feature comparisons or migration scenarios. |
| compatibility | Requires .NET 8, 9, or 10. NuGet package DevExpress.Blazor is available on NuGet.org. A valid DevExpress license is required. Requires interactive render mode (InteractiveServer, InteractiveWebAssembly, or InteractiveAuto). |
| metadata | {"author":"DevExpress","version":"26.1","source-commit":"8493730c9e9a47a009fc307a37c307e157663819"} |
DevExpress Blazor Scheduler
DxScheduler is a calendar/appointment component for Blazor. It visualizes time-based data as appointments across Day, Week, Work Week, Month, and Timeline views. Users can create, edit, drag, resize, and delete appointments through built-in UI.
When to Use This Skill
- Display appointments or events in calendar views
- Bind to a collection of appointment data objects via
DxSchedulerDataStorage
- Support recurring appointments (daily, weekly, monthly, yearly)
- Manage multiple resources (rooms, employees, etc.)
- Create, edit, or delete appointments through the built-in edit forms
- Show work-time-only views with
ShowWorkTimeOnly
- Navigate between dates with the scheduler toolbar
Prerequisites & Installation
NuGet Package
| Package | Purpose |
|---|
DevExpress.Blazor | Scheduler + all standard Blazor UI components |
dotnet add package DevExpress.Blazor
Setup
- Register in
Program.cs:
builder.Services.AddDevExpressBlazor();
v26.1 note: DevExpress.Blazor no longer includes options.BootstrapVersion or DevExpress.Blazor.BootstrapVersion. Do not generate either API.
- Apply a theme and add client scripts in
App.razor inside <head>:
@using DevExpress.Blazor
@DxResourceManager.RegisterTheme(Themes.Fluent)
@DxResourceManager.RegisterScripts()
- Add namespace to
_Imports.razor:
@using DevExpress.Blazor
Before You Start — Ask the Developer
- Render mode: Are you using
InteractiveServer, InteractiveWebAssembly, or InteractiveAuto?
- Data model: What is your appointment data class? What are the field names for start, end, subject, type, recurrence, etc.?
- Initial view: Which view should be shown by default? (Day, Week, Work Week, Month, Timeline)
- Start date: What date should the scheduler open on?
- Features: Do you need recurring appointments? Resources? Custom labels/statuses?
Component Overview
DxScheduler includes:
- Data Storage (
DxSchedulerDataStorage): Connects the component to appointment data via AppointmentsSource and AppointmentMappings
- Appointment Mappings (
DxSchedulerAppointmentMappings): Maps your data model fields to scheduler concepts (Id, Start, End, Subject, Type, RecurrenceInfo, etc.)
- Views:
DxSchedulerDayView, DxSchedulerWeekView, DxSchedulerWorkWeekView, DxSchedulerMonthView, DxSchedulerTimelineView
- Recurrence (
DxSchedulerRecurrenceInfo): Built-in recurrence rule support (Daily, Weekly, Monthly, Yearly)
- Resources: Bind appointment resources via
DxSchedulerResourceMappings and DxSchedulerDataStorage
- Labels & Statuses: Configurable labels and status indicators for appointments
- Appointment Templates (
HorizontalAppointmentTemplate, VerticalAppointmentTemplate on each view; AppointmentTooltipTemplate on DxScheduler): Customize how appointments and hover tooltips render
- Drag & Resize (
AllowDragAppointment, AllowDragAppointmentBetweenResources, AllowResizeAppointment): Users can drag appointments to reschedule them, drag between resource groups, or resize by dragging appointment borders; all three are enabled by default; set to false to restrict a specific operation; AppointmentStartDragging, AppointmentStartResizing, and AppointmentDraggingBetweenResources events allow customizing or canceling these operations
- Toolbar (
ToolbarItems): Add, remove, or replace built-in toolbar items (DxSchedulerDateNavigatorToolbarItem, DxSchedulerTodayToolbarItem, etc.) and inject custom DxToolbarItem commands
Core Entry Point (Razor)
@rendermode InteractiveServer
<DxScheduler StartDate="@DateTime.Today"
DataStorage="@DataStorage">
<DxSchedulerWeekView ShowWorkTimeOnly="true" />
</DxScheduler>
@code {
DxSchedulerDataStorage DataStorage = new DxSchedulerDataStorage {
AppointmentsSource = new List<AppointmentData>(),
AppointmentMappings = new DxSchedulerAppointmentMappings {
// Required mappings:
Id = nameof(AppointmentData.Id),
Type = nameof(AppointmentData.AppointmentType),
Start = nameof(AppointmentData.StartDate),
End = nameof(AppointmentData.EndDate),
Subject = nameof(AppointmentData.Caption),
// Optional mappings (add as needed):
// AllDay = nameof(AppointmentData.AllDay),
// Description = nameof(AppointmentData.Description),
// Location = nameof(AppointmentData.Location),
// LabelId = nameof(AppointmentData.Label),
// StatusId = nameof(AppointmentData.Status),
// RecurrenceInfo = nameof(AppointmentData.Recurrence)
}
};
}
Documentation & Navigation Guide
Getting Started
📄 references/getting-started.md
When you need to:
- Set up the scheduler from scratch
- Configure
DxSchedulerDataStorage and AppointmentMappings
- Display your first calendar view
Data Binding
📄 references/data-binding.md
When you need to:
- Connect your appointment data model to the scheduler
- Load appointments from a service or database
- Understand all
AppointmentMappings properties
Appointments
📄 references/appointments.md
When you need to:
- Handle appointment creation, editing, and deletion events
- Configure recurring appointments
- Customize appointment display with labels and statuses
- Use the compact form settings
Views
📄 references/views.md
When you need to:
- Choose between Day, Week, Work Week, Month, and Timeline views
- Configure
ShowWorkTimeOnly
- Set visible time range and cell duration
Examples
💻 examples/quickstart.razor — Multi-view scheduler with appointment CRUD, labels, and statuses
💻 examples/resources.razor — Multi-resource timeline view with ResourcesSource, ResourceMappings, and GroupType.Resource
Quick Start Example
@page "/scheduler-demo"
@rendermode InteractiveServer
<DxScheduler StartDate="@DateTime.Today"
DataStorage="@DataStorage">
<DxSchedulerDayView />
<DxSchedulerWeekView ShowWorkTimeOnly="true" />
<DxSchedulerWorkWeekView />
<DxSchedulerMonthView />
</DxScheduler>
@code {
DxSchedulerDataStorage DataStorage;
protected override void OnInitialized() {
var appointments = new List<AppointmentData> {
new AppointmentData {
Id = 1, AppointmentType = 0,
StartDate = DateTime.Today.AddHours(9),
EndDate = DateTime.Today.AddHours(10),
Caption = "Team Meeting",
Description = "Weekly sync",
Label = 2, Status = 0
},
new AppointmentData {
Id = 2, AppointmentType = 0,
StartDate = DateTime.Today.AddDays(1).AddHours(14),
EndDate = DateTime.Today.AddDays(1).AddHours(15),
Caption = "Code Review",
Label = 3, Status = 0
},
};
DataStorage = new DxSchedulerDataStorage {
AppointmentsSource = appointments,
AppointmentMappings = new DxSchedulerAppointmentMappings {
Id = nameof(AppointmentData.Id),
Type = nameof(AppointmentData.AppointmentType),
Start = nameof(AppointmentData.StartDate),
End = nameof(AppointmentData.EndDate),
Subject = nameof(AppointmentData.Caption),
Description = nameof(AppointmentData.Description),
AllDay = nameof(AppointmentData.AllDay),
Location = nameof(AppointmentData.Location),
LabelId = nameof(AppointmentData.Label),
StatusId = nameof(AppointmentData.Status),
RecurrenceInfo = nameof(AppointmentData.Recurrence)
}
};
}
class AppointmentData {
public int Id { get; set; }
public int AppointmentType { get; set; }
public DateTime StartDate { get; set; }
public DateTime EndDate { get; set; }
public string Caption { get; set; }
public string Description { get; set; }
public string Location { get; set; }
public bool AllDay { get; set; }
public int Label { get; set; }
public int Status { get; set; }
public string Recurrence { get; set; }
}
}
Key Properties
DxScheduler
| Property | Type | Description |
|---|
StartDate | DateTime | Initial date displayed |
DataStorage | DxSchedulerDataStorage | Data source and mapping configuration |
ActiveViewType | SchedulerViewType | Currently active view |
GroupType | SchedulerGroupType | Group appointments by date or resource |
DxSchedulerDataStorage
| Property | Type | Description |
|---|
AppointmentsSource | IList | Collection of appointment data objects |
AppointmentMappings | DxSchedulerAppointmentMappings | Field mapping configuration |
ResourcesSource | IList | Collection of resource objects |
ResourceMappings | DxSchedulerResourceMappings | Resource field mappings |
DxSchedulerAppointmentMappings
| Property | Maps To |
|---|
Id | Appointment unique identifier |
Type | Appointment type (0 = one-time, 1 = pattern, 2 = occurrence, 3 = changed occurrence, 4 = deleted occurrence) |
Start | Start date/time |
End | End date/time |
Subject | Appointment title |
AllDay | All-day flag (bool) |
Description | Appointment notes |
Location | Location string |
LabelId | Label ID (int?) |
StatusId | Status ID (int) |
RecurrenceInfo | Recurrence XML string |
Programmatic Recurrence Patterns
When a user asks to make an appointment recurring, create a recurring pattern in the data
source. Set AppointmentType = 1 and assign a recurrence rule string to the mapped
Recurrence field. Do not invent helpers like WeeklyRecurrence(...) unless the project
already defines them.
var start = DateTime.Today.AddDays(1).AddHours(14);
var end = DateTime.Today.AddDays(1).AddHours(15);
var appointment = new AppointmentData {
Id = 3,
AppointmentType = 1,
StartDate = start,
EndDate = end,
Caption = "Planning Session",
Description = "Sprint planning",
Label = 5,
Status = 1,
Recurrence = string.Format(
System.Globalization.CultureInfo.InvariantCulture,
"<RecurrenceInfo Start=\"{0}\" End=\"{1}\" WeekDays=\"{2}\" Frequency=\"1\" Range=\"0\" Type=\"1\" Id=\"{3}\" />",
start,
end,
1 << (int)start.DayOfWeek,
Guid.NewGuid())
};
Use the following recurrence rule shapes for common prompts:
| Prompt Shape | Required Rule Fields | Example Rule Body |
|---|
Every N days | Type="0", Frequency | Type="0" Frequency="3" |
Every N weeks on specific weekdays | Type="1", Frequency, WeekDays | Type="1" Frequency="2" WeekDays="16" |
| Every month on a day number | Type="2", Frequency, WeekOfMonth="0", DayNumber | Type="2" Frequency="1" WeekOfMonth="0" DayNumber="30" |
| Every month on a weekday pattern | Type="2", Frequency, WeekOfMonth, WeekDays | Type="2" Frequency="1" WeekOfMonth="1" WeekDays="2" |
| Every year on a fixed date | Type="3", Frequency, Month, WeekOfMonth="0", DayNumber | Type="3" Frequency="1" Month="3" WeekOfMonth="0" DayNumber="5" |
| Every year on a weekday pattern | Type="3", Frequency, Month, WeekOfMonth, WeekDays | Type="3" Frequency="1" Month="3" WeekOfMonth="1" WeekDays="2" |
Range values control when the series ends:
| Range Shape | Meaning |
|---|
Range="0" | No end date |
Range="1" OccurrenceCount="N" | End after N occurrences |
Range="2" End="..." | End on a specific date |
For changed or deleted occurrences, use an exception rule instead of a pattern rule:
"<RecurrenceInfo Id=\"6de79b21-6b16-4dea-9736-c500058ec858\" Index=\"25\"/>"
Use this exception rule only for changed or deleted occurrences, not for the base recurring
pattern.
Advanced Recurrence Details
Use these value mappings when a prompt requires exact recurrence control:
WeekDays value | Meaning |
|---|
1 | Sunday |
2 | Monday |
4 | Tuesday |
8 | Wednesday |
16 | Thursday |
32 | Friday |
64 | Saturday |
62 | WorkDays (Monday through Friday) |
65 | WeekendDays (Saturday and Sunday) |
127 | EveryDay |
WeekDays is a flags enum. Combine values with bitwise OR in C# when building recurrence data in
code. In XML, the combined numeric value is stored in the WeekDays attribute.
WeekOfMonth value | Meaning |
|---|
0 | None |
1 | First |
2 | Second |
3 | Third |
4 | Fourth |
5 | Last |
When WeekOfMonth = "0", the week position does not affect the rule and WeekDays is ignored
for monthly and yearly day-number rules. In those cases, use DayNumber instead.
| Property | Constraint |
|---|
DayNumber | Valid values are 1 through 31. Lower values are normalized to 1; higher values are normalized to 31. |
Month | Valid values are 1 through 12. Lower values are normalized to 1; higher values are normalized to 12. |
If a project works with recurrence objects instead of raw XML strings, use the documented XML
conversion methods on ISchedulerRecurrenceInfo:
| Method | Use |
|---|
FromXml(string) | Reconstruct recurrence information from an XML rule string |
ToXml() | Convert recurrence information to an XML rule string |
Reset(SchedulerRecurrenceType) | Reset recurrence fields for a specific recurrence type |
Assign(...) | Copy recurrence settings from another recurrence object |
If a prompt mentions time zones for recurring appointments, map the appointment time zone field
with DxSchedulerAppointmentMappings.TimeZoneId. Recurrence time zone information is obtained
from the appointment item and is used to calculate recurring series start and end times.
For prompt interpretation, use the following rules:
| Prompt Intent | Recommended Output |
|---|
| "every work day" | Weekly rule with WeekDays="62" |
| "every day" | Daily rule or WeekDays="127" only when the project specifically models recurrence that way |
| "first Monday of each month" | Monthly rule with Type="2" WeekOfMonth="1" WeekDays="2" |
| "last Monday of April every year" | Yearly rule with Type="3" Month="4" WeekOfMonth="5" WeekDays="2" |
| "skip this occurrence" | Create or preserve a deleted-occurrence exception with an Id/Index rule |
| "edit only this occurrence" | Create or preserve a changed-occurrence exception with an Id/Index rule |
Do not generate changed-occurrence or deleted-occurrence records unless the prompt explicitly
targets a single occurrence or the surrounding code already manages recurrence exceptions.
Troubleshooting
| Symptom | Cause | Fix |
|---|
| No appointments shown | AppointmentMappings fields not matching model | Use nameof() for all mapping properties |
| Appointments show wrong time | Time zone mismatch | Ensure StartDate/EndDate are stored in local or UTC consistently |
| Scheduler does not respond to clicks | Static render mode | Add @rendermode InteractiveServer to the page |
| Recurring appointments broken | RecurrenceInfo mapping missing | Set RecurrenceInfo = nameof(AppointmentData.Recurrence) in mappings |
MissingMethodException: Constructor on type 'Int32Converter' not found (WASM) | Blazor linker removes required types during WebAssembly compilation | Set <BlazorWebAssemblyEnableLinking>false</BlazorWebAssemblyEnableLinking> in the project file, or add a LinkerConfig.xml to preserve required types |
"Unhandled exception on the current circuit" with no detail | CircuitOptions.DetailedErrors not set | Add builder.Services.Configure<CircuitOptions>(o => o.DetailedErrors = true); in Program.cs (development only) |
"Component parameter 'ValueChanged' is used two or more times" compile error | @bind-Value and ValueChanged used together | Use @bind-Value="@val" for two-way binding, or Value="@val" ValueChanged="@handler" — never both simultaneously |
dx-blazor.js not found (404) behind a reverse proxy | Reverse proxy strips the app base path | Add app.UsePathBase("/subpath") before app.MapBlazorHub(), or set <base href="/subpath/" /> in App.razor |
Static assets return 404 (dx-blazor.css, dx-blazor.js) | UseStaticWebAssets() not called | Add app.UseStaticWebAssets(); in Program.cs before app.UseStaticFiles() |
"Could not find 'X' in 'window.DxBlazor'" JavaScript error | Stale browser-cached JS from an older DevExpress version | Hard-refresh the browser (Ctrl+Shift+R), clear site data, or verify all DevExpress NuGet packages are the same version |
"Cannot pass the parameter 'X' to component 'Y' with rendermode" | Non-serializable parameter passed across a render mode boundary | Move the component to a child .razor file with its own @rendermode directive; pass only serializable parameters |
Constraints & Rules
- Never invent API: If a property, method, event, or feature is not documented in this skill or its references, do not assume it exists. When asked about an unfamiliar API, first try to verify it using the DevExpress documentation MCP (
devexpress_docs_search) or the local apidoc/ folder. Only after checking: if confirmed, use the API; if not found, explicitly state that it does not appear to be part of the DxScheduler API. Do not warn that a feature "may have been introduced in a recent version" as a way to justify inventing it.
- Render mode:
DxScheduler requires interactive render mode for appointment creation, editing, and navigation.
- AppointmentMappings: All mapping properties must exactly match your data model field names. Use
nameof() to avoid spelling errors.
- AppointmentType: Recurring appointments created in code require
AppointmentType = 1 and a valid RecurrenceInfo mapping. Regular non-recurring appointments use 0.
- NuGet packages: Use
DevExpress.Blazor. Match versions across all DevExpress packages.
- Build verification: Run
dotnet build after changes.
Using DevExpress Documentation MCP
If devexpress_docs_search and devexpress_docs_get_content are available:
devexpress_docs_search(technology="Blazor", query="Scheduler recurrence appointments data binding")devexpress_docs_get_content(url="https://docs.devexpress.com/Blazor/...")
Use MCP for: resource grouping configuration, custom appointment tooltips, drag-and-drop event handling, compact form settings, and time zone support.
