Jak eksportować dane do istniejącego szablonu Excel w C# używając IronXL

Dłączego szablony Excel usprawniają tworzenie raportów?

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, które zostały już zatwierdzone przez Twoją organizację. Zespoły finansowe, działy operacyjne i grupy ds. zgodności często dysponują standardowymi szablonami faktur, pulpitów nawigacyjnych i dokumentów regulacyjnych, które muszą zachować swój wygląd, jednocześnie uwzględniając aktualne dane z baz danych, interfejsów API lub zbiorów w pamięci.

Wypełniając istniejące szablony programowo, oszczędzasz wiele godzin pracy związanej z formatowaniem i gwarantujesz spójność wszystkich generowanych dokumentów. IronXL obsługuje formaty XLSX, XLS, XLSM i XLTX bez konieczności instalowania pakietu Office, dzięki czemu nadaje się do środowisk serwerowych, kontenerów Docker i potoków w chmurze, gdzie instalacja pakietu Microsoft Office jest niepraktyczna lub niemożliwa.

Kluczowe zalety podejścia opartego na szablonach:

• Zachowanie formuł — istniejące formuły SUM, AVERAGE i lookup są automatycznie przeliczane po zapisaniu danych
• Zachowanie stylu — czcionki, obramowania, kolory komórek i formaty liczb pozostają dokładnie takie, jak w projekcie
• Formatowanie warunkówe — reguły powiązane z zakresami komórek nadal działają w oparciu o nowe wartości danych
• Zero zależności od pakietu Office — IronXL odczytuje i zapisuje pliki Excel całkowicie w zarządzanym kodzie .NET
• Obsługa wielu platform — działa w systemach Windows, Linux i macOS, w tym w środowiskach .NET 10

Jak zainstalować IronXL w swoim projekcie?

Zacznij od zainstalowania IronXL za pośrednictwem NuGet. Otwórz konsolę menedżera pakietów i uruchom:

Install-Package IronXL

Install-Package IronXL

Lub użyj interfejsu CLI platformy .NET:

dotnet add package IronXL

dotnet add package 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. Szczegółowe instrukcje konfiguracji można znaleźć w przewodniku IronXL "Pierwsze kroki". Biblioteka jest przeznaczona dla platform .NET Framework, .NET Core oraz .NET 5 do .NET 10, działających w systemach Windows, Linux i macOS.

Po instalacji dodaj przestrzeń nazw na początku pliku:

using IronXL;

using IronXL;

Imports IronXL

Jak załadować i wypełnić istniejący szablon Excel?

Wczytanie istniejącego szablonu jest proste dzięki metodzie WorkBook.Load() w IronXL. Poniższy przykład otwiera szablon kwartalnego raportu sprzedaży i wypełnia określone komórki danymi przy użyciu instrukcji najwyższego poziomu:

using IronXL;

// Load the existing Excel template
WorkBook workbook = WorkBook.Load("ReportTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

// Write header values to named cells
sheet["B2"].Value = "Q4 2025 Sales Report";
sheet["C4"].StringValue = DateTime.Now.ToString("MMMM dd, yyyy");
sheet["C6"].DecimalValue = 125000.50m;
sheet["C7"].DecimalValue = 98500.75m;

// Add a profit formula -- Excel recalculates automatically
sheet["C8"].Formula = "=C6-C7";

// Populate a column range with monthly 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 file
workbook.SaveAs("Q4_Sales_Report.xlsx");

using IronXL;

// Load the existing Excel template
WorkBook workbook = WorkBook.Load("ReportTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

// Write header values to named cells
sheet["B2"].Value = "Q4 2025 Sales Report";
sheet["C4"].StringValue = DateTime.Now.ToString("MMMM dd, yyyy");
sheet["C6"].DecimalValue = 125000.50m;
sheet["C7"].DecimalValue = 98500.75m;

// Add a profit formula -- Excel recalculates automatically
sheet["C8"].Formula = "=C6-C7";

// Populate a column range with monthly 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 file
workbook.SaveAs("Q4_Sales_Report.xlsx");

Imports IronXL

' Load the existing Excel template
Dim workbook As WorkBook = WorkBook.Load("ReportTemplate.xlsx")
Dim sheet As WorkSheet = workbook.DefaultWorkSheet

' Write header values to named cells
sheet("B2").Value = "Q4 2025 Sales Report"
sheet("C4").StringValue = DateTime.Now.ToString("MMMM dd, yyyy")
sheet("C6").DecimalValue = 125000.50D
sheet("C7").DecimalValue = 98500.75D

' Add a profit formula -- Excel recalculates automatically
sheet("C8").Formula = "=C6-C7"

' Populate a column range with monthly 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 file
workbook.SaveAs("Q4_Sales_Report.xlsx")

Ten kod ładuje gotowy szablon, zachowuje całe istniejące formatowanie i wypełnia określone komórki. Właściwość DecimalValue zapewnia, że dane liczbowe zachowują właściwe formatowanie waluty lub formatowanie dziesiętne. Komórki zawierające formuły są automatycznie przeliczane po zmianie sąsiednich danych, dzięki czemu logika obliczeniowa szablonu pozostaje nienaruszona.

Wskazówki dotyczące pracy z odwołaniami do komórek i zakresów w programie Excel można znaleźć w dokumentacji dotyczącej komórek i zakresów IronXL. Możesz również skorzystać ze strony z przykładami IronXL, aby zapoznać się z dodatkowymi wzorcami.

Jak zastąpić znaczniki zastępcze w szablonie?

Wiele szablonów wykorzystuje znaczniki tekstu zastępczego — na przykład {{CustomerName}} lub {{InvoiceDate}} — które należy zastąpić rzeczywistymi wartościami w czasie wykonywania. IronXL realizuje to poprzez iterację komórek w zdefiniowanym zakresie. Ten wzorzec jest szczególnie przydatny do generowania faktur, wypełniania umów i tworzenia spersonalizowanych raportów:

using IronXL;

// Load an invoice template containing placeholder markers
WorkBook workbook = WorkBook.Load("InvoiceTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

// Iterate over a range and replace placeholder text
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-2025-001");
}

// Append line items starting at row 15
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");

using IronXL;

// Load an invoice template containing placeholder markers
WorkBook workbook = WorkBook.Load("InvoiceTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

// Iterate over a range and replace placeholder text
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-2025-001");
}

// Append line items starting at row 15
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 IronXL

' Load an invoice template containing placeholder markers
Dim workbook As WorkBook = WorkBook.Load("InvoiceTemplate.xlsx")
Dim sheet As WorkSheet = workbook.DefaultWorkSheet

' Iterate over a range and replace placeholder text
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-2025-001")
    End If
Next

' Append line items starting at row 15
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 wyszukuje znaczniki w zdefiniowanym zakresie komórek i zastępuje je rzeczywistymi wartościami. Formatowanie szablonu — czcionki, kolory, obramowania i formaty liczb — pozostaje niezmienione w całym tekście. Aby uzyskać informacje na temat bardziej zaawansowanych zmian stylów w czasie wykonywania, zapoznaj się z przewodnikiem po stylach komórek IronXL, który obejmuje kolory tła, właściwości czcionek i style obramowań.

using IronXL;

WorkBook workbook = WorkBook.Load("InvoiceTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

var replacements = new Dictionary<string, string>
{
    { "{{CustomerName}}", "Acme Corporation" },
    { "{{InvoiceDate}}", DateTime.Now.ToShortDateString() },
    { "{{InvoiceNumber}}", "INV-2025-002" }
};

foreach (var cell in sheet["A1:H50"])
{
    if (string.IsNullOrEmpty(cell.Text)) continue;

    foreach (var replacement in replacements)
    {
        if (cell.Text.Contains(replacement.Key))
            cell.Value = cell.Text.Replace(replacement.Key, replacement.Value);
    }
}

workbook.SaveAs("GeneratedInvoice_Safe.xlsx");

using IronXL;

WorkBook workbook = WorkBook.Load("InvoiceTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

var replacements = new Dictionary<string, string>
{
    { "{{CustomerName}}", "Acme Corporation" },
    { "{{InvoiceDate}}", DateTime.Now.ToShortDateString() },
    { "{{InvoiceNumber}}", "INV-2025-002" }
};

foreach (var cell in sheet["A1:H50"])
{
    if (string.IsNullOrEmpty(cell.Text)) continue;

    foreach (var replacement in replacements)
    {
        if (cell.Text.Contains(replacement.Key))
            cell.Value = cell.Text.Replace(replacement.Key, replacement.Value);
    }
}

workbook.SaveAs("GeneratedInvoice_Safe.xlsx");

Imports IronXL

Dim workbook As WorkBook = WorkBook.Load("InvoiceTemplate.xlsx")
Dim sheet As WorkSheet = workbook.DefaultWorkSheet

Dim replacements As New Dictionary(Of String, String) From {
    {"{{CustomerName}}", "Acme Corporation"},
    {"{{InvoiceDate}}", DateTime.Now.ToShortDateString()},
    {"{{InvoiceNumber}}", "INV-2025-002"}
}

For Each cell In sheet("A1:H50")
    If String.IsNullOrEmpty(cell.Text) Then Continue For

    For Each replacement In replacements
        If cell.Text.Contains(replacement.Key) Then
            cell.Value = cell.Text.Replace(replacement.Key, replacement.Value)
        End If
    Next
Next

workbook.SaveAs("GeneratedInvoice_Safe.xlsx")

Jak wygenerować miesięczny raport na podstawie szablonu?

Oto praktyczny przykład generowania miesięcznego raportu sprzedaży na podstawie istniejącego szablonu Excel zawierającego wstępnie sformatowane komórki, wykresy i formuły procentowe. Kod wykorzystuje instrukcje najwyższego poziomu i akceptuje słownik mapowań produktów do sprzedaży:

using IronXL;

// Load the monthly report template
WorkBook workbook = WorkBook.Load("MonthlyReportTemplate.xlsx");
WorkSheet sheet = workbook.GetWorkSheet("Monthly Report");

// Build sample sales data
var salesData = new Dictionary<string, decimal>
{
    { "Product A", 42500.00m },
    { "Product B", 31750.50m },
    { "Product C", 18300.25m }
};

// Write report header
sheet["B2"].Value = $"Sales Report - {DateTime.Now:MMMM yyyy}";
sheet["B3"].Value = $"Generated: {DateTime.Now:g}";

// Write each product row starting at row 6
int currentRow = 6;
decimal totalSales = salesData.Values.Sum();

foreach (var sale in salesData)
{
    sheet[$"B{currentRow}"].Value = sale.Key;
    sheet[$"C{currentRow}"].DecimalValue = sale.Value;
    // Percentage of total formula
    sheet[$"D{currentRow}"].Formula = $"=C{currentRow}/C{currentRow + salesData.Count}*100";
    currentRow++;
}

// Write the total row and apply bold style
sheet[$"C{currentRow}"].DecimalValue = totalSales;
sheet[$"C{currentRow}"].Style.Font.Bold = true;

// Save with a date-stamped filename
string outputPath = $"Reports/Monthly_Report_{DateTime.Now:yyyyMMdd}.xlsx";
workbook.SaveAs(outputPath);

using IronXL;

// Load the monthly report template
WorkBook workbook = WorkBook.Load("MonthlyReportTemplate.xlsx");
WorkSheet sheet = workbook.GetWorkSheet("Monthly Report");

// Build sample sales data
var salesData = new Dictionary<string, decimal>
{
    { "Product A", 42500.00m },
    { "Product B", 31750.50m },
    { "Product C", 18300.25m }
};

// Write report header
sheet["B2"].Value = $"Sales Report - {DateTime.Now:MMMM yyyy}";
sheet["B3"].Value = $"Generated: {DateTime.Now:g}";

// Write each product row starting at row 6
int currentRow = 6;
decimal totalSales = salesData.Values.Sum();

foreach (var sale in salesData)
{
    sheet[$"B{currentRow}"].Value = sale.Key;
    sheet[$"C{currentRow}"].DecimalValue = sale.Value;
    // Percentage of total formula
    sheet[$"D{currentRow}"].Formula = $"=C{currentRow}/C{currentRow + salesData.Count}*100";
    currentRow++;
}

// Write the total row and apply bold style
sheet[$"C{currentRow}"].DecimalValue = totalSales;
sheet[$"C{currentRow}"].Style.Font.Bold = true;

// Save with a date-stamped filename
string outputPath = $"Reports/Monthly_Report_{DateTime.Now:yyyyMMdd}.xlsx";
workbook.SaveAs(outputPath);

Imports IronXL

' Load the monthly report template
Dim workbook As WorkBook = WorkBook.Load("MonthlyReportTemplate.xlsx")
Dim sheet As WorkSheet = workbook.GetWorkSheet("Monthly Report")

' Build sample sales data
Dim salesData As New Dictionary(Of String, Decimal) From {
    {"Product A", 42500.0D},
    {"Product B", 31750.5D},
    {"Product C", 18300.25D}
}

' Write report header
sheet("B2").Value = $"Sales Report - {DateTime.Now:MMMM yyyy}"
sheet("B3").Value = $"Generated: {DateTime.Now:g}"

' Write each product row starting at row 6
Dim currentRow As Integer = 6
Dim totalSales As Decimal = salesData.Values.Sum()

For Each sale In salesData
    sheet($"B{currentRow}").Value = sale.Key
    sheet($"C{currentRow}").DecimalValue = sale.Value
    ' Percentage of total formula
    sheet($"D{currentRow}").Formula = $"=C{currentRow}/C{currentRow + salesData.Count}*100"
    currentRow += 1
Next

' Write the total row and apply bold style
sheet($"C{currentRow}").DecimalValue = totalSales
sheet($"C{currentRow}").Style.Font.Bold = True

' Save with a date-stamped filename
Dim outputPath As String = $"Reports/Monthly_Report_{DateTime.Now:yyyyMMdd}.xlsx"
workbook.SaveAs(outputPath)

Ta metoda wypełnia standardowy szablon, automatycznie oblicza procentowy udział i zachowuje profesjonalny wygląd szablonu. Istniejące wykresy w szablonie aktualizują się na podstawie nowych wartości danych, ponieważ ich zakresy źródłowe pozostają niezmienione.

Podczas przenoszenia danych z DataTable lub DataSet należy zachować nazwy kolumn i traktować pierwszy wiersz jako nagłówki. Więcej informacji na temat importowania z obiektów DataTable można znaleźć w dokumentacji IronXL DataTable.

Jak rozwiązywać typowe błędy szablonów?

Podczas pracy z szablonami regularnie pojawia się kilka problemów. W poniższej tabeli przyporządkowano każdy objaw do jego przyczyny i rozwiązania:

W przypadku plików chronionych hasłem należy podać hasło jako drugi argument do WorkBook.Load. Jeśli formuły nie aktualizują się po zapisaniu danych, wywołaj sheet.Calculate() przed wywołaniem workbook.SaveAs(). W przypadku dużych zbiorów danych należy usunąć obiekt skoroszytu po zapisaniu, aby niezwłocznie zwolnić pamięć zarządzaną i niezarządzaną.

Dodatkowe zasoby dotyczące rozwiązywania problemów są dostępne w dokumentacji dotyczącej rozwiązywania problemów IronXL oraz w Dokumentacji API IronXL.

Jakie inne operacje w programie Excel obsługuje IronXL?

Oprócz wypełniania szablonów, IronXL oferuje szeroki zestaw funkcji do pracy z plikami Excel, które uzupełniają opisany powyżej proces:

• Odczyt plików Excel — wyodrębnianie danych z istniejących skoroszytów do obiektów C#, list lub tabel danych
• Twórz pliki Excel od podstaw — generuj nowe skoroszyty bez szablonu, gdy potrzebna jest pełna kontrola nad układem
• Eksportuj DataTable do Excela — konwertuj obiekty ADO.NET DataTable bezpośrednio na wiersze arkusza
• Stosowanie stylów komórek — programowe ustawianie kolorów tła, grubości czcionek, obramowań i formatów liczb
• Praca z formułami programu Excel — pisanie i obliczanie ciągów formuł, w tym SUM, VLOOKUP i formuł warunkówych
• Scałanie komórek — scałanie i rozdzielanie zakresów komórek dla nagłówków i układu raportu
• Zabezpiecz arkusze — zablokuj komórki lub arkusze, aby zapobiec przypadkowej edycji struktury szablonu
• Konwersja do formatu PDF — renderowanie wypełnionego szablonu bezpośrednio do formatu PDF w celu dystrybucji bez konieczności korzystania z programu Excel
• Eksportuj do pliku CSV — zapisz dane arkusza jako wartości rozdzielone przecinkami do dalszego przetwarzania

Funkcje te integrują się z wypełnianiem szablonów, dzięki czemu w ramach jednego przepływu pracy można załadować szablon, wypełnić go, zabezpieczyć komórki zawierające wrażliwe formuły oraz wyeksportować zarówno kopię w formacie XLSX, jak i wersję PDF w jednym przejściu.

IronXL dobrze integruje się również z innymi formatami wymiany danych, takimi jak XML, umożliwiając importowanie danych strukturalnych, ich przekształcanie oraz eksportowanie wyników do szablonu. Aby uzyskać informacje na temat bardziej zaawansowanej integracji z generowaniem raportów opartym na bazach danych, zapoznaj się z samouczkami społeczności na blogu IronXL.

Jak rozpocząć pracę z IronXL w środowisku produkcyjnym?

IronXL jest bezpłatny do celów programistycznych i testowych. Gdy będziesz gotowy do wdrożenia, wybierz jedną z elastycznych opcji licencyjnych, które obejmują indywidualnych programistów, zespoły oraz dystrybucję OEM. Odwiedź stronę licencyjną IronXL, aby znaleźć opcję odpowiednią dla Twojego projektu.

Aby rozpocząć pracę od razu, skorzystaj z bezpłatnej wersji próbnej i uruchom przykłady kodu z tego samouczka na własnych szablonach. Strona IronXL NuGet zawiera historię wersji i szczegóły pakietu. Dyskusja społecznościowa i dodatkowe przykłady są dostępne w repozytorium Iron Software na GitHubie. Aby zapoznać się z informacjami na temat formatu plików Open XML, na którym opierają się pliki XLSX, zobacz przegląd specyfikacji ECMA-376.

Dla organizacji oceniających IronXL wraz z alternatywnymi rozwiązaniami, przewodniki porównawcze IronXL obejmują różnice w funkcjach, modele licencjonowania oraz testy wydajności, aby pomóc w podjęciu świadomej decyzji.