Jak wyeksportować szablon w języku C#

Dłączego warto używać szablonów Excel do eksportu danych?

Szablony programu Excel oferują znaczące korzyści w porównaniu z tworzeniem arkuszy kalkulacyjnych od podstaw. Szablony zachowują profesjonalne formatowanie, złożone formuły, reguły formatowania warunkówego oraz sprawdzone struktury danych. Organizacje często dysponują standardowymi szablonami faktur, raportów i pulpitów nawigacyjnych, które muszą zachować swój wygląd, jednocześnie uwzględniając dynamiczne dane z baz danych, interfejsów API lub obiektów zbiorczych, takich jak tabele danych. Podczas stosowania formatowania warunkówego i formatowania komórek w pliku wyjściowym szablony zapewniają spójność wszystkich wygenerowanych dokumentów w formacie xlsx.

Wypełniając istniejące szablony programowo, programiści oszczędzają niezliczone godziny pracy nad formatowaniem i zapewniają spójność wszystkich generowanych dokumentów. IronXL sprawia, że proces ten przebiega płynnie, obsługując różne formaty Excel, w tym pliki XLSX, XLS, szablony XLSM i XLTX, bez konieczności instalowania pakietu Office. Kod źródłowy tych operacji jest prosty i łatwy do wdrożenia w dowolnym folderze projektu.

Konfiguracja IronXL do operacji z szablonami

Zacznij od zainstalowania IronXL za pomocą menedżera pakietów NuGet. Otwórz konsolę menedżera pakietów i uruchom następujące polecenie:

Install-Package IronXl.Excel

Po instalacji dodaj niezbędną przestrzeń nazw do pliku C#:

using IronXL;

using IronXL;

Imports IronXL

IronXL działa niezależnie, bez konieczności instalacji pakietu Microsoft Office, co czyni go idealnym rozwiązaniem dla środowisk serwerowych i aplikacji wielopłatformowych, w tym kontenerów Docker i platform chmurowych. Szczegółowe instrukcje konfiguracji i dodatkowe informacje można znaleźć w przewodniku IronXL "Pierwsze kroki". Biblioteka obsługuje .NET Framework, .NET Core i .NET 5+ w środowiskach Windows, Linux i macOS, dzięki czemu idealnie nadaje się do aplikacji .NET.

Ładowanie i wypełnianie szablonów Excel

Wczytanie istniejącego szablonu jest proste dzięki metodzie WorkBook.Load() w IronXL. Poniższy przykład pokazuje, jak otworzyć szablon i wypełnić go danymi, traktując pierwszy wiersz jako nagłówki i efektywnie zarządzając nazwami kolumn:

// Load the existing Excel template for data import
WorkBook workbook = WorkBook.Load("ReportTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;
// Populate specific worksheet cells with data
sheet["B2"].Value = "Q4 2024 Sales Report";
sheet["C4"].StringValue = DateTime.Now.ToString("MMMM dd, yyyy");
sheet["C6"].DecimalValue = 125000.50m;
sheet["C7"].DecimalValue = 98500.75m;
sheet["C8"].Formula = "=C6-C7"; // Profit calculation
// Populate a range with array data
decimal[] monthlyData = { 10500, 12300, 15600, 11200 };
for (int i = 0; i < monthlyData.Length; i++)
{
    sheet[$"E{10 + i}"].DecimalValue = monthlyData[i];
}
// Save the populated template
workbook.SaveAs("Q4_Sales_Report.xlsx");

// Load the existing Excel template for data import
WorkBook workbook = WorkBook.Load("ReportTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;
// Populate specific worksheet cells with data
sheet["B2"].Value = "Q4 2024 Sales Report";
sheet["C4"].StringValue = DateTime.Now.ToString("MMMM dd, yyyy");
sheet["C6"].DecimalValue = 125000.50m;
sheet["C7"].DecimalValue = 98500.75m;
sheet["C8"].Formula = "=C6-C7"; // Profit calculation
// Populate a range with array data
decimal[] monthlyData = { 10500, 12300, 15600, 11200 };
for (int i = 0; i < monthlyData.Length; i++)
{
    sheet[$"E{10 + i}"].DecimalValue = monthlyData[i];
}
// Save the populated template
workbook.SaveAs("Q4_Sales_Report.xlsx");

Imports System

' Load the existing Excel template for data import
Dim workbook As WorkBook = WorkBook.Load("ReportTemplate.xlsx")
Dim sheet As WorkSheet = workbook.DefaultWorkSheet
' Populate specific worksheet cells with data
sheet("B2").Value = "Q4 2024 Sales Report"
sheet("C4").StringValue = DateTime.Now.ToString("MMMM dd, yyyy")
sheet("C6").DecimalValue = 125000.50D
sheet("C7").DecimalValue = 98500.75D
sheet("C8").Formula = "=C6-C7" ' Profit calculation
' Populate a range with array data
Dim monthlyData As Decimal() = {10500D, 12300D, 15600D, 11200D}
For i As Integer = 0 To monthlyData.Length - 1
    sheet($"E{10 + i}").DecimalValue = monthlyData(i)
Next
' Save the populated template
workbook.SaveAs("Q4_Sales_Report.xlsx")

Ten kod ładuje gotowy szablon, zachowuje całe dotychczasowe formatowanie i wypełnia określone komórki nowymi danymi. Właściwość DecimalValue zapewnia zachowanie prawidłowego formatowania danych liczbowych. Komórki zawierające formuły są automatycznie przeliczane po zmianie sąsiednich danych, co pozwala zachować logikę obliczeniową szablonu. Dowiedz się więcej o pracy z formułami programu Excel w IronXL.

Praca z symbolami zastępczymi szablonów

Wiele szablonów zawiera znaczniki tekstu zastępczego, które należy zastąpić rzeczywistymi danymi. IronXL skutecznie radzi sobie z tym scenariuszem dzięki iteracji komórek i zamianie tekstu. Gdy trzeba zapisać dane w szablonach Excel i wstawić treści dynamiczne, to podejście zapewnia maksymalną elastyczność:

// Load template with placeholders
WorkBook workbook = WorkBook.Load("InvoiceTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;
// Find and replace placeholder text in cells
foreach (var cell in sheet["A1:H50"])
{
    if (cell.Text.Contains("{{CustomerName}}"))
        cell.Value = cell.Text.Replace("{{CustomerName}}", "Acme Corporation");
    if (cell.Text.Contains("{{InvoiceDate}}"))
        cell.Value = cell.Text.Replace("{{InvoiceDate}}", DateTime.Now.ToShortDateString());
    if (cell.Text.Contains("{{InvoiceNumber}}"))
        cell.Value = cell.Text.Replace("{{InvoiceNumber}}", "INV-2024-001");
}
// Populate line items dynamically
var items = new[] {
    new { Description = "Software License", Qty = 5, Price = 299.99 },
    new { Description = "Support Package", Qty = 1, Price = 999.99 }
};
int startRow = 15;
foreach (var item in items)
{
    sheet[$"B{startRow}"].Value = item.Description;
    sheet[$"E{startRow}"].IntValue = item.Qty;
    sheet[$"F{startRow}"].DoubleValue = item.Price;
    sheet[$"G{startRow}"].Formula = $"=E{startRow}*F{startRow}";
    startRow++;
}
workbook.SaveAs("GeneratedInvoice.xlsx");

// Load template with placeholders
WorkBook workbook = WorkBook.Load("InvoiceTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;
// Find and replace placeholder text in cells
foreach (var cell in sheet["A1:H50"])
{
    if (cell.Text.Contains("{{CustomerName}}"))
        cell.Value = cell.Text.Replace("{{CustomerName}}", "Acme Corporation");
    if (cell.Text.Contains("{{InvoiceDate}}"))
        cell.Value = cell.Text.Replace("{{InvoiceDate}}", DateTime.Now.ToShortDateString());
    if (cell.Text.Contains("{{InvoiceNumber}}"))
        cell.Value = cell.Text.Replace("{{InvoiceNumber}}", "INV-2024-001");
}
// Populate line items dynamically
var items = new[] {
    new { Description = "Software License", Qty = 5, Price = 299.99 },
    new { Description = "Support Package", Qty = 1, Price = 999.99 }
};
int startRow = 15;
foreach (var item in items)
{
    sheet[$"B{startRow}"].Value = item.Description;
    sheet[$"E{startRow}"].IntValue = item.Qty;
    sheet[$"F{startRow}"].DoubleValue = item.Price;
    sheet[$"G{startRow}"].Formula = $"=E{startRow}*F{startRow}";
    startRow++;
}
workbook.SaveAs("GeneratedInvoice.xlsx");

Imports System

' Load template with placeholders
Dim workbook As WorkBook = WorkBook.Load("InvoiceTemplate.xlsx")
Dim sheet As WorkSheet = workbook.DefaultWorkSheet
' Find and replace placeholder text in cells
For Each cell In sheet("A1:H50")
    If cell.Text.Contains("{{CustomerName}}") Then
        cell.Value = cell.Text.Replace("{{CustomerName}}", "Acme Corporation")
    End If
    If cell.Text.Contains("{{InvoiceDate}}") Then
        cell.Value = cell.Text.Replace("{{InvoiceDate}}", DateTime.Now.ToShortDateString())
    End If
    If cell.Text.Contains("{{InvoiceNumber}}") Then
        cell.Value = cell.Text.Replace("{{InvoiceNumber}}", "INV-2024-001")
    End If
Next
' Populate line items dynamically
Dim items = {
    New With {.Description = "Software License", .Qty = 5, .Price = 299.99},
    New With {.Description = "Support Package", .Qty = 1, .Price = 999.99}
}
Dim startRow As Integer = 15
For Each item In items
    sheet($"B{startRow}").Value = item.Description
    sheet($"E{startRow}").IntValue = item.Qty
    sheet($"F{startRow}").DoubleValue = item.Price
    sheet($"G{startRow}").Formula = $"=E{startRow}*F{startRow}"
    startRow += 1
Next
workbook.SaveAs("GeneratedInvoice.xlsx")

To podejście polega na wyszukiwaniu znaczników zastępczych w określonym zakresie i zastępowaniu ich rzeczywistymi wartościami. Formatowanie szablonu, w tym czcionki, kolory i obramowania, pozostaje niezmienione w trakcie całego procesu. W bardziej zaawansowanych scenariuszach warto zapoznać się z opcjami stylizacji komórek w IronXL, aby w razie potrzeby dynamicznie modyfikować formatowanie.

Przykład wdrożenia w praktyce

Oto kompletny przykład generowania miesięcznego raportu sprzedaży na podstawie istniejącego szablonu Excel z wstępnie sformatowanymi komórkami. Ten kod pokazuje, jak obsługiwać zdarzenia wysyłające obiekty i tworzyć kompleksowe raporty. Podczas pracy z danymi z systemówej bazy danych lub kolekcji w pamięci można efektywnie eksportować dane do programu Excel, używając nowej tabeli danych lub istniejącego zestawu danych w celu wypełnienia szablonów:

public void GenerateMonthlyReport(string templatePath, Dictionary<string, decimal> salesData)
{
    // Load the existing template file
    WorkBook workbook = WorkBook.Load(templatePath);
    WorkSheet sheet = workbook.GetWorkSheet("Monthly Report");
    // Set report header information
    sheet["B2"].Value = $"Sales Report - {DateTime.Now:MMMM yyyy}";
    sheet["B3"].Value = $"Generated: {DateTime.Now:g}";
    // Populate sales data starting from row 6
    int currentRow = 6;
    decimal totalSales = 0;
    foreach (var sale in salesData)
    {
        sheet[$"B{currentRow}"].Value = sale.Key;  // Product name
        sheet[$"C{currentRow}"].DecimalValue = sale.Value;  // Sales amount
        sheet[$"D{currentRow}"].Formula = $"=C{currentRow}/C${salesData.Count + 6}*100"; // Percentage formula
        totalSales += sale.Value;
        currentRow++;
    }
    // Update total row with sum
    sheet[$"C{currentRow}"].DecimalValue = totalSales;
    sheet[$"C{currentRow}"].Style.Font.Bold = true;
    // Save with timestamp
    string outputPath = $"Reports/Monthly_Report_{DateTime.Now:yyyyMMdd}.xlsx";
    workbook.SaveAs(outputPath);
}

public void GenerateMonthlyReport(string templatePath, Dictionary<string, decimal> salesData)
{
    // Load the existing template file
    WorkBook workbook = WorkBook.Load(templatePath);
    WorkSheet sheet = workbook.GetWorkSheet("Monthly Report");
    // Set report header information
    sheet["B2"].Value = $"Sales Report - {DateTime.Now:MMMM yyyy}";
    sheet["B3"].Value = $"Generated: {DateTime.Now:g}";
    // Populate sales data starting from row 6
    int currentRow = 6;
    decimal totalSales = 0;
    foreach (var sale in salesData)
    {
        sheet[$"B{currentRow}"].Value = sale.Key;  // Product name
        sheet[$"C{currentRow}"].DecimalValue = sale.Value;  // Sales amount
        sheet[$"D{currentRow}"].Formula = $"=C{currentRow}/C${salesData.Count + 6}*100"; // Percentage formula
        totalSales += sale.Value;
        currentRow++;
    }
    // Update total row with sum
    sheet[$"C{currentRow}"].DecimalValue = totalSales;
    sheet[$"C{currentRow}"].Style.Font.Bold = true;
    // Save with timestamp
    string outputPath = $"Reports/Monthly_Report_{DateTime.Now:yyyyMMdd}.xlsx";
    workbook.SaveAs(outputPath);
}

Public Sub GenerateMonthlyReport(templatePath As String, salesData As Dictionary(Of String, Decimal))
    ' Load the existing template file
    Dim workbook As WorkBook = WorkBook.Load(templatePath)
    Dim sheet As WorkSheet = workbook.GetWorkSheet("Monthly Report")
    ' Set report header information
    sheet("B2").Value = $"Sales Report - {DateTime.Now:MMMM yyyy}"
    sheet("B3").Value = $"Generated: {DateTime.Now:g}"
    ' Populate sales data starting from row 6
    Dim currentRow As Integer = 6
    Dim totalSales As Decimal = 0
    For Each sale In salesData
        sheet($"B{currentRow}").Value = sale.Key ' Product name
        sheet($"C{currentRow}").DecimalValue = sale.Value ' Sales amount
        sheet($"D{currentRow}").Formula = $"=C{currentRow}/C${salesData.Count + 6}*100" ' Percentage formula
        totalSales += sale.Value
        currentRow += 1
    Next
    ' Update total row with sum
    sheet($"C{currentRow}").DecimalValue = totalSales
    sheet($"C{currentRow}").Style.Font.Bold = True
    ' Save with timestamp
    Dim outputPath As String = $"Reports/Monthly_Report_{DateTime.Now:yyyyMMdd}.xlsx"
    workbook.SaveAs(outputPath)
End Sub

Ta metoda przyjmuje dane dotyczące sprzedaży i wypełnia standardowy szablon, automatycznie obliczając wartości procentowe i sumy, zachowując jednocześnie profesjonalny wygląd szablonu. Istniejące wykresy i formatowanie warunkówe w szablonie są automatycznie aktualizowane na podstawie nowych danych. Uwaga: Podczas przenoszenia danych do programu Excel z obiektów DataTable lub zbiorów danych należy zachować nazwy kolumn i potraktować pierwszy wiersz jako nagłówki.

Poniższe przykładowe podejście sprawdza się doskonale, niezależnie od tego, czy chcesz zapisać dane ze słowników, wstawić wartości z zapytań do bazy danych, czy też wyeksportować dane do programu Excel z różnych źródeł systemówych. Wystarczy zapisać plik wyjściowy w wyznaczonym folderze, aby mieć do niego łatwy dostęp. Aby uzyskać dodatkowe informacje na temat pracy z DataTables, zapoznaj się z dokumentacją dotyczącą importu DataTable oraz przykładami kodu źródłowego.

Rozwiązywanie typowych problemów

Podczas pracy z szablonami upewnij się, że ścieżki do plików są poprawne, a szablony nie są zablokowane przez inne procesy. W przypadku szablonów chronionych hasłem należy użyć WorkBook.Load("template.xlsx", "password"). Jeśli formuły nie aktualizują się, wywołaj metodę sheet.Calculate() po wprowadzeniu danych. W przypadku dużych zbiorów danych warto rozważyć użycie metody workbook.SaveAs() z opcjami strumieniowania, aby zoptymalizować wykorzystanie pamięci. W przypadku pracy z plikami w formacie xlsx w różnych środowiskach systemówych należy zapoznać się z dokumentacją dotyczącą rozwiązywania problemów, aby uzyskać dodatkowe informacje i rozwiązania.

Wnioski

IronXL upraszcza wypełnianie szablonów Excel w języku C#, zachowując złożone formatowanie i jednocześnie efektywnie wprowadzając dane dynamiczne z różnych źródeł, w tym obiektów zestawów danych i połączeń z bazami danych. Takie podejście znacznie skraca czas programowania i zapewnia spójność dokumentów w ramach procesów raportowania w całej organizacji. Niezależnie od tego, czy chcesz zapisać dane w Excelu, wstawić nowe wiersze, czy zastosować formatowanie komórek w pliku wyjściowym, IronXL zapewnia narzędzia niezbędne do profesjonalnej automatyzacji Excela w aplikacjach .NET.

Chcesz usprawnić tworzenie raportów w Excelu? Rozpocznij bezpłatny okres próbny IronXL, aby przetestować wypełnianie szablonów w swoim projekcie, lub zapoznaj się z innymi samouczkami dotyczącymi automatyzacji programu Excel, aby usprawnić swój przepływ pracy. Aby wdrożyć rozwiązanie w środowisku produkcyjnym, zapoznaj się z opcjami licencyjnymi dostosowanymi do Twoich potrzeb.