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

Dlaczego 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, zasady warunkowego formatowania oraz zweryfikowane struktury danych już zaakceptowane przez twoją organizację. Zespoły finansowe, działy operacyjne oraz grupy ds. zgodności często mają zstandardyzowane szablony dla faktur, pulpitów i zgłoszeń regulacyjnych, które muszą zachować swój projekt, jednocześnie włączając świeże dane z baz danych, API lub kolekcji 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 liczbowe pozostają dokładnie takie, jak zostały zaprojektowane
• Formatowanie warunkowe — 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.Excel

Lub użyj interfejsu CLI platformy .NET:

dotnet add package IronXL.Excel

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 używa markerów 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 przy generowaniu faktur, wypełnianiu umów i tworzeniu 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 liczbowe -- pozostaje nienaruszone przez cały czas. Dla bardziej zaawansowanych zmian stylizacji podczas wykonywania, zobacz przewodnik stylizacji komórek IronXL, który obejmuje kolory tła, właściwości czcionki i style obramowania.

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 zstandardyzowany szablon, automatycznie oblicza wkłady procentowe 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, zachowaj nazwy kolumn i potraktuj pierwszy wiersz jako nagłówki. Aby dowiedzieć się więcej o imporcie z obiektów DataTable, zobacz dokumentację 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:

Dla plików chronionych hasłem, podaj 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:

• Odczytuj pliki Excel -- wyodrębniaj dane z istniejących skoroszytów do obiektów C#, list lub DataTable
• Tworzenie plików Excel od zera -- generuj nowe skoroszyty bez szablonu, gdy potrzebujesz pełnej kontroli nad układem
• Eksportuj DataTable do Excela -- konwertuj obiekty DataTable ADO.NET bezpośrednio na wiersze arkusza
• Zastosuj style komórek -- ustawiaj kolory tła, ciężary czcionek, obramowania i formaty liczbowe programatycznie
• Praca z formułami Excel -- pisz i oceniaje formuły, w tym SUM, VLOOKUP i formuły warunkowe
• Scal komórki -- scalaj i rozdzielaj zakresy komórek dla układu nagłówków i raportów
• Chroń arkusze -- blokuj komórki lub arkusze, aby uniemożliwić przypadkową edycję struktury szablonu
• Konwertuj na PDF -- renderuj wypełniony szablon bezpośrednio do PDF do dystrybucji bez Excela
• Eksportuj do CSV -- zapisuj dane arkusza jako wartości rozdzielane 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 alternatywami, przewodniki porównawcze IronXL obejmują różnice w funkcjach, modele licencjonowania i punkty odniesienia wydajności, aby pomóc podjąć świadomą decyzję.