ReportViewer 教程：从入门到精通

目录

1. 什么是 ReportViewer？
2. 在哪些 .NET 框架中可用？
3. 准备工作：安装和配置
4. 核心教程：创建并显示第一个报表
   • 步骤 1：创建报表文件
   • 步骤 2：配置数据源
   • 步骤 3：设计报表布局
   • 步骤 4：在 WinForms/WPF 项目中添加 ReportViewer 控件
   • 步骤 5：加载并显示报表
5. ReportViewer 核心功能详解
   • 工具栏功能
   • 参数化查询
   • 交互功能（钻取、链接、书签）
   • 导出功能
6. 高级主题
   • 动态数据绑定
   • 本地模式 vs. 远程模式
   • 处理报表事件
   • 自定义外观
7. 常见问题与最佳实践
8. 总结与资源

什么是 ReportViewer？

ReportViewer 是一个由 Microsoft 提供的免费控件，允许你在 Windows Forms (WinForms)、WPF (Windows Presentation Foundation) 和 ASP.NET 应用程序中无缝集成和显示 SQL Server Reporting Services (SSRS) 报表。

你可以把它想象成一个“报表浏览器”，它被嵌入到你的应用程序界面中，用户可以直接在你的软件里查看、打印、导出和与报表进行交互，而无需离开应用程序。

在哪些 .NET 框架中可用？

• Windows Forms (WinForms): 功能最全面，支持所有本地模式功能。
• WPF: 功能与 WinForms 类似，但利用了 WPF 的数据绑定和样式化能力。
• ASP.NET Web Forms: 早期 Web 开发框架中的标准报表控件。
• ASP.NET MVC: 注意： 官方没有直接为 MVC 提供 ReportViewer 控件，通常通过在视图中使用 WebForms 控件（@Html.RenderPartial）或创建一个专门的控制器来返回报表流来实现。

重要提示： Microsoft 已经停止了对 ReportViewer 的积极开发，最新的版本是 2012 版，但它仍然可以在现代 .NET Framework (如 4.8) 和 .NET 5/6/7/8 (通过兼容模式) 中使用，对于新项目，如果不需要复杂的交互，可以考虑使用更轻量级的解决方案，如直接生成 PDF 或使用第三方库。

准备工作：安装和配置

1. 安装 Visual Studio: 确保你安装了支持 WinForms 或 WPF 的 Visual Studio 版本。
2. 安装 .NET Framework (如果使用): ReportViewer 2012 需要 .NET Framework 4.5 或更高版本。
3. 安装 ReportViewer 运行时:
   • 如果你使用的是 Visual Studio 2012 或更高版本，ReportViewer 控件通常已经包含在开发环境中。
   • 如果你的目标机器上没有安装 Visual Studio，你需要单独安装 Microsoft Report Viewer 2012 Redistributable，你可以从 Microsoft 官网下载。
4. 创建项目: 创建一个新的 "Windows Forms App (.NET Framework)" 或 "WPF App (.NET Framework)" 项目。

核心教程：创建并显示第一个报表 (以 WinForms 为例)

我们将创建一个简单的报表,从 Northwind 数据库中显示客户列表。

步骤 1：创建报表文件

1. 在你的解决方案资源管理器中,右键点击项目 -> 添加 -> 新建项。
2. 选择 报表 -> 报表向导 (或者直接选择 报表，然后手动设计)。
3. 给报表文件命名,CustomerReport.rdlc，然后点击“添加”。rdlc 是 "Report Definition Language Client-side" 的缩写。

步骤 2：配置数据源

1. 报表向导启动后,第一步是选择数据源，点击 “新建数据源”。
2. 选择 “对象” 作为数据源类型，然后点击“下一步”。（另一种常见选择是“数据库”，但对象模式更灵活，因为它不依赖于数据库连接字符串）。
3. 点击 “添加对象”，然后选择或浏览到你项目中定义的模型类，为了简单起见，我们可以创建一个简单的 Customer 类：

   // 在项目中创建一个 Models 文件夹，并添加 Customer.cs
   public class Customer
   {
       public string CustomerID { get; set; }
       public string CompanyName { get; set; }
       public string ContactName { get; set; }
       public string City { get; set; }
       public string Country { get; set; }
   }

4. 选择 Customer 类，点击“确定”和“完成”。
5. 在向导中,选择要显示的字段，CustomerID, CompanyName, ContactName，然后点击“下一步”。
6. 选择表格作为报表布局,点击“下一步”，然后点击“完成”。

步骤 3：设计报表布局

报表设计器会自动为你生成一个表格,你可以：

• 拖拽字段到表格中。
• 右键点击字段,设置格式（如货币、日期）。
• 修改文本框的 Name 属性，使其更具描述性（txtCompanyName）。
• 、页眉和页脚。

步骤 4：在 WinForms 项目中添加 ReportViewer 控件

1. 打开你的主窗体（Form1.cs [Design]）。
2. 从 工具箱 中，找到 “报表” 选项卡。
3. 将 Microsoft ReportViewer Control 拖放到窗体上。
4. ReportViewer 控件会自动调整大小以填充窗体，你可以调整其大小和 Dock 属性（Fill）。

步骤 5：加载并显示报表

这是最关键的一步：将数据绑定到 ReportViewer。

1. 双击窗体,进入 Form1_Load 事件。
2. 编写代码来准备数据并将其传递给报表。

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows.Forms;
namespace WinFormsReportViewerDemo
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
        }
        private void Form1_Load(object sender, EventArgs e)
        {
            // 1. 准备数据
            List<Customer> customers = GetCustomersFromDatabaseOrService();
            // 2. 创建数据源
            ReportDataSource reportDataSource = new ReportDataSource();
            reportDataSource.Name = "CustomerDataSource"; // 这个名称必须与 .rdlc 文件中定义的数据源名称完全一致
            reportDataSource.Value = customers;
            // 3. 将数据源分配给 ReportViewer
            this.reportViewer1.LocalReport.DataSources.Clear(); // 清除旧数据源
            this.reportViewer1.LocalReport.DataSources.Add(reportDataSource);
            // 4. (可选) 设置报表路径
            // 如果报表文件是项目资源，可以这样做
            this.reportViewer1.LocalReport.ReportPath = "CustomerReport.rdlc";
            // 5. 刷新报表
            this.reportViewer1.RefreshReport();
        }
        // 模拟从数据库或服务获取数据的方法
        private List<Customer> GetCustomersFromDatabaseOrService()
        {
            // 在实际应用中，这里会调用数据库或API
            //  using (var context = new NorthwindDbContext()) { return context.Customers.ToList(); }
            var mockData = new List<Customer>
            {
                new Customer { CustomerID = "ALFKI", CompanyName = "Alfreds Futterkiste", ContactName = "Maria Anders", City = "Berlin", Country = "Germany" },
                new Customer { CustomerID = "ANATR", CompanyName = "Ana Trujillo", ContactName = "Ana Trujillo", City = "México D.F.", Country = "Mexico" },
                new Customer { CustomerID = "ANTON", CompanyName = "Antonio Moreno", ContactName = "Antonio Moreno", City = "México D.F.", Country = "Mexico" }
            };
            return mockData;
        }
    }
}

运行项目，你应该能看到窗体中加载了你的报表，并且数据已经成功显示。

ReportViewer 核心功能详解

工具栏功能

ReportViewer 自带一个工具栏，提供以下功能：

• 导出: 将报表导出为 PDF、Excel、Word、CSV、TIFF 等格式。
• 打印: 打印报表。
• 页面导航: 翻页。
• 缩放: 放大/缩小报表视图。
• 刷新: 重新加载数据。
• 查找: 在报表中搜索文本。

参数化查询

报表通常需要根据用户输入动态显示数据,这通过报表参数实现。

1. 在报表中定义参数:

   • 在报表设计器中,右键点击报表背景 -> 报表参数。
   • 添加一个新参数,CountryParam，设置数据类型为 String。

2. 修改数据查询:

   • 在你的数据源（无论是对象还是数据库查询）中，添加一个筛选条件，如果你使用 DataTable，可以修改 GetCustomers 方法：

     private DataTable GetCustomers(string country)
     {
         // ... 从数据库获取所有数据 ...
         // 然后根据 country 参数进行筛选
         if (!string.IsNullOrEmpty(country))
         {
             DefaultView.RowFilter = $"Country = '{country}'";
         }
         return DefaultView.ToTable();
     }

3. 在代码中传递参数:

   private void Form1_Load(object sender, EventArgs e)
   {
       // ... 准备数据 ...
       // 创建参数集合
       ReportParameter param = new ReportParameter("CountryParam", "Mexico");
       this.reportViewer1.LocalReport.SetParameters(new ReportParameter[] { param });
       // ... 加载报表 ...
   }

交互功能

• 钻取: 点击报表中的某个字段（如客户ID），可以跳转到另一个显示该客户详细信息的报表。
  • 在报表设计器中,右键点击文本框 -> 属性 -> 操作 -> 选择“跳转到报表”，并指定目标报表和参数。
• 超链接: 将文本或图片链接到外部URL或执行一个命令。

  在属性窗口的“导航”选项卡中设置。

• 书签: 在报表的某个部分设置书签，然后可以从其他地方创建链接跳转到该部分。

导出功能

用户可以直接通过工具栏导出,作为开发者，你也可以通过代码以编程方式导出：

// 将报表导出为 PDF 文件并保存
byte[] bytes = this.reportViewer1.LocalReport.Render("PDF");
string filePath = "C:\\Reports\\CustomerReport.pdf";
System.IO.File.WriteAllBytes(filePath, bytes);

高级主题

动态数据绑定

数据不一定非要在 Form_Load 时加载，你可以根据用户操作（如点击按钮、选择下拉框）来重新绑定数据。

private void btnRefresh_Click(object sender, EventArgs e)
{
    string selectedCountry = cbCountry.SelectedItem.ToString();
    // 重新获取数据并加载报表
    // ... (代码与 Form_Load 类似)
    this.reportViewer1.RefreshReport();
}

本地模式 vs. 远程模式

教程中的例子是本地模式。 要切换到远程模式，需要在 ReportViewer 控件属性中设置 ServerReport 对象的 ReportServerUrl 和 ReportPath。

处理报表事件

ReportViewer 控件提供了一些事件，让你可以在报表生命周期的特定节点执行代码。

• ReportRefresh: 在报表刷新前或后执行。
• Drillthrough: 在用户点击钻取链接时触发，可以在这里获取被钻取的报表参数。

自定义外观

你可以通过设置 ReportViewer 控件的 ToolbarBackground、ToolbarForeground 等属性来自定义工具栏的外观，对于更复杂的自定义，可能需要重写控件或使用样式。

常见问题与最佳实践

常见问题:

• Q: "无法找到数据源 'XXX'" 错误？
  • A: 检查代码中 ReportDataSource.Name 属性的值是否与 .rdlc 文件中数据源的名称完全一致（区分大小写）。
• Q: 报表不显示数据，但数据源不为空？
  • A: 检查字段绑定是否正确，在报表设计器中，确保文本框的 Value 属性绑定到了正确的字段（=Fields!CompanyName.Value）。
• Q: 在 .NET Core/.NET 5+ 项目中使用？
  • A: 官方不支持，最简单的方法是创建一个 .NET Framework 类库来封装报表逻辑，然后在你的 .NET Core 项目中引用这个类库，另一种方法是使用第三方库如 FastReport 或 Stimulsoft Reports。

最佳实践:

1. 使用 MVVM 模式 (WPF): 将报表数据准备和加载逻辑放在 ViewModel 中，保持 View（XAML）的简洁。
2. 分离数据访问层: 不要在 UI 事件中直接写数据库查询，创建一个 ReportService 或 Repository 类来处理数据获取。
3. 重用报表: 如果多个窗体需要显示同一个报表，考虑将报表加载逻辑封装在一个公共方法中。
4. 性能考虑: 对于大型数据集，在数据库端进行筛选和分页，而不是将所有数据加载到内存中再筛选。

总结与资源

ReportViewer 是一个强大且成熟的工具，非常适合在桌面和 Web 应用程序中集成报表，尽管它不再是 Microsoft 的重点开发产品，但其稳定性和功能使其在许多遗留项目和中小型应用中仍然非常有用。

推荐资源:

• Microsoft 官方文档 (经典但有效):
  • ReportViewer 控件概述 (MSDN)
  • 演练：在 Windows 应用程序中嵌入本地报表
• SSRS 官方文档 (如果你需要了解报表设计本身):
  • SQL Server Reporting Services 文档
• 社区和教程:
  • Stack Overflow: 搜索 c# reportviewer 或 vb.net reportviewer，你能找到几乎所有遇到的问题的答案。
  • C# Corner, CodeProject: 等技术社区有大量关于 ReportViewer 的分步教程和示例项目。

希望这份详细的教程能帮助你快速上手 ReportViewer！