ClosedXML для C# (.NET): полное руководство с примерами

Введение в ClosedXML: что это и зачем нужно

ClosedXML — это мощная open-source библиотека для языка C# (.NET), предназначенная для создания, чтения и редактирования файлов Microsoft Excel (форматы .xlsx, .xlsm, .xltx). Она предоставляет удобный объектно-ориентированный интерфейс для работы с электронными таблицами без необходимости установки Microsoft Office или использования COM-объектов.

Библиотека особенно полезна для:

• Автоматизации отчетности — генерация сложных Excel-отчетов с данными из БД, API или других источников
• Импорта/экспорта данных — массовая обработка табличных данных между системами
• Создания шаблонов — заполнение заранее подготовленных Excel-шаблонов данными
• Финансовых и аналитических расчетов — работа с формулами, сводными таблицами, диаграммами
• Миграции с VBA — перенос макросов на современный C#

ClosedXML поддерживает все основные возможности Excel: форматирование ячеек, объединение ячеек, условное форматирование, диаграммы, сводные таблицы, проверку данных, защиту листов и многое другое. При этом библиотека работает полностью в памяти и не требует установленного Excel на сервере.

Установка ClosedXML

Установка ClosedXML выполняется через NuGet Package Manager. Ниже приведены все способы установки:

Через .NET CLI

dotnet add package ClosedXML

Через Package Manager Console (Visual Studio)

Install-Package ClosedXML

Через NuGet Package Manager UI

1. Откройте проект в Visual Studio
2. Правый клик на проекте → "Manage NuGet Packages"
3. Найдите "ClosedXML" и нажмите "Install"

Проверка установки

После установки добавьте using-директиву в ваш код:

using ClosedXML.Excel;

Быстрый старт: создаем первую Excel-таблицу

Давайте создадим простую таблицу с данными о сотрудниках и сохраним её в файл:

using ClosedXML.Excel;

class Program
{
    static void Main(string[] args)
    {
        // Создаем новую рабочую книгу
        using (var workbook = new XLWorkbook())
        {
            // Добавляем рабочий лист
            var worksheet = workbook.Worksheets.Add("Сотрудники");

            // Заполняем заголовки
            worksheet.Cell("A1").Value = "ID";
            worksheet.Cell("B1").Value = "Имя";
            worksheet.Cell("C1").Value = "Должность";
            worksheet.Cell("D1").Value = "Зарплата";

            // Заполняем данные
            worksheet.Cell("A2").Value = 1;
            worksheet.Cell("B2").Value = "Иван Петров";
            worksheet.Cell("C2").Value = "Разработчик";
            worksheet.Cell("D2").Value = 150000;

            worksheet.Cell("A3").Value = 2;
            worksheet.Cell("B3").Value = "Мария Сидорова";
            worksheet.Cell("C3").Value = "Аналитик";
            worksheet.Cell("D3").Value = 120000;

            // Форматируем заголовки
            var headerRange = worksheet.Range("A1:D1");
            headerRange.Style.Font.Bold = true;
            headerRange.Style.Fill.BackgroundColor = XLColor.LightBlue;

            // Автоподбор ширины колонок
            worksheet.Columns().AdjustToContents();

            // Сохраняем файл
            workbook.SaveAs("employees.xlsx");
        }

        Console.WriteLine("Файл успешно создан!");
    }
}

Этот пример создает файл employees.xlsx с тремя строками данных и форматированными заголовками.

Основные методы и функции ClosedXML

1. Создание рабочей книги и листов

Метод: new XLWorkbook() и workbook.Worksheets.Add()

Описание: Создает новую рабочую книгу и добавляет в неё рабочие листы.

Параметры:

• XLWorkbook() — конструктор без параметров создает пустую книгу
• XLWorkbook(string filePath) — открывает существующий файл
• Worksheets.Add(string name) — добавляет лист с указанным именем

Пример:

using (var workbook = new XLWorkbook())
{
    var sheet1 = workbook.Worksheets.Add("Данные");
    var sheet2 = workbook.Worksheets.Add("Отчет");
    var sheet3 = workbook.Worksheets.Add("Графики");
    
    // Переименование листа
    sheet1.Name = "Основные данные";
    
    workbook.SaveAs("test.xlsx");
}

2. Запись данных в ячейки

Метод: worksheet.Cell(address).Value

Описание: Устанавливает значение в указанную ячейку. Поддерживает различные типы данных: int, double, string, DateTime, bool.

Параметры:

• address — строка вида "A1", "B2" или объект IXLCell
• Value — устанавливаемое значение любого поддерживаемого типа

Пример:

var ws = workbook.Worksheets.Add("Типы данных");

ws.Cell("A1").Value = "Текст";
ws.Cell("B1").Value = 123.45;
ws.Cell("C1").Value = 42;
ws.Cell("D1").Value = true;
ws.Cell("E1").Value = DateTime.Now;
ws.Cell("F1").Value = 3.14159f;

// Чтение значения
var textValue = ws.Cell("A1").GetString();
var numberValue = ws.Cell("B1").GetDouble();

3. Форматирование ячеек и диапазонов

Метод: worksheet.Range().Style

Описание: Позволяет применять форматирование к ячейкам: шрифт, заливка, границы, выравнивание и т.д.

Параметры:

• Range(startCell, endCell) — задает диапазон ячеек
• Style — объект для настройки стилей

Пример:

var range = ws.Range("A1:C10");

// Настройка шрифта
range.Style.Font.FontName = "Arial";
range.Style.Font.FontSize = 12;
range.Style.Font.Bold = true;
range.Style.Font.FontColor = XLColor.DarkBlue;

// Заливка
range.Style.Fill.BackgroundColor = XLColor.LightYellow;

// Границы
range.Style.Border.OutsideBorder = XLBorderStyleValues.Thin;
range.Style.Border.InsideBorder = XLBorderStyleValues.Dotted;
range.Style.Border.OutsideBorderColor = XLColor.Black;

// Выравнивание
range.Style.Alignment.Horizontal = XLAlignmentHorizontalValues.Center;
range.Style.Alignment.Vertical = XLAlignmentVerticalValues.Middle;

// Числовой формат
ws.Cell("B2").Style.NumberFormat.Format = "#,##0.00";

4. Работа с формулами

Метод: cell.FormulaA1

Описание: Устанавливает формулу Excel в ячейку. Формулы вычисляются автоматически при открытии файла.

Параметры:

• FormulaA1 — строка с формулой в формате A1 (например, "=SUM(A1:A10)")

Пример:

// Заполняем данные
for (int i = 1; i <= 10; i++)
{
    ws.Cell($"A{i}").Value = i * 10;
    ws.Cell($"B{i}").Value = i * 5;
}

// Сумма
ws.Cell("A11").FormulaA1 = "=SUM(A1:A10)";
ws.Cell("B11").FormulaA1 = "=SUM(B1:B10)";

// Среднее
ws.Cell("A12").FormulaA1 = "=AVERAGE(A1:A10)";

// Если
ws.Cell("C1").FormulaA1 = "=IF(A1>50, \"Больше\", \"Меньше\")";

// ВПР (VLOOKUP)
ws.Cell("D1").FormulaA1 = "=VLOOKUP(A1, Sheet2!A:B, 2, FALSE)";

5. Объединение ячеек

Метод: worksheet.Range().Merge()

Описание: Объединяет несколько ячеек в одну. Значение сохраняется в верхней левой ячейке.

Параметры:

• Merge() — объединяет ячейки
• Unmerge() — разъединяет ячейки

Пример:

// Объединение для заголовка
var titleRange = ws.Range("A1:E1");
titleRange.Merge();
titleRange.Value = "Годовой отчет за 2024 год";
titleRange.Style.Font.FontSize = 16;
titleRange.Style.Font.Bold = true;
titleRange.Style.Alignment.Horizontal = XLAlignmentHorizontalValues.Center;

// Объединение нескольких ячеек по вертикали
ws.Range("A2:A5").Merge();
ws.Cell("A2").Value = "Объединенный текст";

// Проверка, объединена ли ячейка
bool isMerged = ws.Cell("A2").IsMerged();

6. Условное форматирование

Метод: worksheet.Range().AddConditionalFormat()

Описание: Добавляет условное форматирование, которое меняет внешний вид ячеек в зависимости от их значений.

Параметры:

• WhenGreaterThan(value) — условие "больше чем"
• WhenLessThan(value) — условие "меньше чем"
• WhenBetween(min, max) — условие "между"
• WhenEquals(value) — условие "равно"

Пример:

var dataRange = ws.Range("B2:B100");

// Выделить ячейки больше 100 красным
dataRange.AddConditionalFormat()
    .WhenGreaterThan(100)
    .Fill.SetBackgroundColor(XLColor.Red)
    .Font.SetFontColor(XLColor.White);

// Выделить ячейки между 50 и 100 желтым
dataRange.AddConditionalFormat()
    .WhenBetween(50, 100)
    .Fill.SetBackgroundColor(XLColor.Yellow);

// Выделить ячейки меньше 50 зеленым
dataRange.AddConditionalFormat()
    .WhenLessThan(50)
    .Fill.SetBackgroundColor(XLColor.Green);

// Цветовые шкалы (Color Scale)
dataRange.AddConditionalFormat()
    .ColorScale()
    .LowestValue(XLColor.Red)
    .Midpoint(XLColor.Yellow)
    .HighestValue(XLColor.Green);

7. Создание диаграмм

Метод: worksheet.Charts.Add()

Описание: Добавляет диаграмму на лист. Поддерживаются различные типы: Column, Bar, Line, Pie, Area и другие.

Параметры:

• Add(type) — тип диаграммы (XLChartType.Column, XLChartType.Line и т.д.)
• SetPosition(row, column) — позиция диаграммы на листе
• AddSeries() — добавляет ряд данных

Пример:

// Подготовка данных
ws.Cell("A1").Value = "Месяц";
ws.Cell("B1").Value = "Продажи";
ws.Cell("A2").Value = "Янв"; ws.Cell("B2").