Skip to content

Adds mapping fields capability#931

Merged
michelebastione merged 4 commits intomini-software:masterfrom
michelebastione:field-mapping
Mar 8, 2026
Merged

Adds mapping fields capability#931
michelebastione merged 4 commits intomini-software:masterfrom
michelebastione:field-mapping

Conversation

@michelebastione
Copy link
Contributor

Resolves #273 by adding the capability of mapping public fields of a class when importing or exporting an Excel file, by decorating them with MiniExcelColumnAttribute or any of the other MiniExcel attributes. To do this it was necessary to refactor the mapping utilities to include such fields, and I took this as an opportunity to also restructure and clean up other parts of the library, like attributes, exceptions and some extensions.

- Added `MiniExcelAttributeBase` abstract class and made the other attributes inherit it
- Added feature for public fields of a class to be mapped alongside its properties if decorated with one of the attributes inheriting from afermonetioned base attribute
- Renamed all mapping utilities to reflect their mapping functionality and the custom accessors to reflect the shift from only properties to members
- Moved the `GetEmptyExpandoObject` methods to dedicated new class `ExpandoHelper`
Refactored `OpenXmlImporter` and `CsvImporter` removing redundant logic and moving duplicate method in shared extension helper
@michelebastione michelebastione changed the title Adds mapping fields enhancement Adds mapping fields capability Mar 8, 2026
@gemini-code-assist
Copy link
Contributor

Summary of Changes

Hello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the MiniExcel library by introducing the capability to map public fields of a class during Excel import and export operations. Previously, only properties were supported, but now, by decorating public fields with MiniExcelColumnAttribute or other MiniExcel attributes, developers can seamlessly include them in their data mappings. This change involved a comprehensive refactoring of the core mapping utilities, along with a general restructuring and cleanup of related components such as attributes, exceptions, and helper extensions, leading to a more robust and flexible library.

Highlights

  • Public Field Mapping: Introduced the capability to map public fields of a class during Excel import and export operations, in addition to existing property mapping. Fields can now be decorated with MiniExcelColumnAttribute or other MiniExcel attributes to enable mapping.
  • Refactoring of Mapping Utilities: Refactored core mapping utilities to support the new field mapping functionality, leading to a more unified and flexible reflection mechanism.
  • Attribute Hierarchy and Cleanup: Restructured MiniExcel attributes by introducing a common MiniExcelAttributeBase class, simplifying attribute definitions and improving code organization.
  • Exception Handling Improvements: Renamed and introduced new exception types (ColumnNotFoundException, InvalidMappingException, MemberNotSerializableException, ValueNotAssignableException) for clearer error reporting during mapping and data conversion.
  • Documentation Update: Updated the README-V2.md to include examples and explanations for the new public field mapping feature.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog
  • README-V2.md
    • Added documentation for public field mapping with MiniExcelColumnAttribute.
  • src/MiniExcel.Core/Abstractions/IMiniExcelWriteAdapter.cs
    • Updated method signatures and CellWriteInfo struct to use MiniExcelColumnMapping instead of MiniExcelColumnInfo.
  • src/MiniExcel.Core/Abstractions/IMiniExcelWriteAdapterAsync.cs
    • Updated method signatures to use MiniExcelColumnMapping instead of MiniExcelColumnInfo.
  • src/MiniExcel.Core/Attributes/MiniExcelAttributeBase.cs
    • Added new abstract base class MiniExcelAttributeBase for MiniExcel attributes.
  • src/MiniExcel.Core/Attributes/MiniExcelColumnAttribute.cs
    • Modified MiniExcelColumnAttribute to inherit from MiniExcelAttributeBase and removed AttributeUsage.
    • Updated CustomFormatter type from Func<object, object> to Func<object?, object?>.
  • src/MiniExcel.Core/Attributes/MiniExcelColumnIndexAttribute.cs
    • Modified MiniExcelColumnIndexAttribute to inherit from MiniExcelAttributeBase and removed AttributeUsage.
  • src/MiniExcel.Core/Attributes/MiniExcelColumnNameAttribute.cs
    • Modified MiniExcelColumnNameAttribute to inherit from MiniExcelAttributeBase and removed AttributeUsage.
  • src/MiniExcel.Core/Attributes/MiniExcelColumnWidthAttribute.cs
    • Modified MiniExcelColumnWidthAttribute to inherit from MiniExcelAttributeBase and removed AttributeUsage.
  • src/MiniExcel.Core/Attributes/MiniExcelFormatAttribute.cs
    • Modified MiniExcelFormatAttribute to inherit from MiniExcelAttributeBase and removed AttributeUsage.
  • src/MiniExcel.Core/Attributes/MiniExcelIgnoreAttribute.cs
    • Modified MiniExcelIgnoreAttribute to inherit from MiniExcelAttributeBase and removed AttributeUsage.
  • src/MiniExcel.Core/Exceptions/ColumnNotFoundException.cs
    • Renamed MiniExcelColumnNotFoundException to ColumnNotFoundException and updated its constructor.
  • src/MiniExcel.Core/Exceptions/InvalidMappingException.cs
    • Added new exception class InvalidMappingException.
  • src/MiniExcel.Core/Exceptions/MemberNotSerializableException.cs
    • Renamed MiniExcelNotSerializableException to MemberNotSerializableException and updated its constructor.
  • src/MiniExcel.Core/Exceptions/ValueNotAssignableException.cs
    • Renamed MiniExcelInvalidCastException to ValueNotAssignableException, updated its constructor parameters, and changed the InvalidCastType property to ColumnType.
  • src/MiniExcel.Core/Helpers/AsyncEnumerableExtensions.cs
    • Added new extension method CastToDictionary for IAsyncEnumerable<dynamic>.
  • src/MiniExcel.Core/Helpers/ExpandoHelper.cs
    • Added new static helper class ExpandoHelper with methods to create empty IDictionary<string, object?> from indices or headers.
  • src/MiniExcel.Core/Helpers/ListExtensions.cs
    • Renamed ListHelper to ListExtensions.
  • src/MiniExcel.Core/Reflection/ColumnMappingsProvider.cs
    • Added new static class ColumnMappingsProvider to centralize logic for retrieving and sorting column mappings for both import and export, handling properties and fields.
  • src/MiniExcel.Core/Reflection/CustomPropertyHelper.cs
    • Removed this file, as its functionality was moved to ExpandoHelper and ColumnMappingsProvider.
  • src/MiniExcel.Core/Reflection/MemberGetter.cs
    • Modified MemberGetter to work with MemberInfo (properties or fields) instead of just PropertyInfo.
  • src/MiniExcel.Core/Reflection/MemberSetter.cs
    • Modified MemberSetter to work with MemberInfo (properties or fields) instead of just PropertyInfo.
  • src/MiniExcel.Core/Reflection/MiniExcelColumnMapping.cs
    • Renamed MiniExcelColumnInfo to MiniExcelColumnMapping and updated its structure to include MemberAccessor and remove Property.
  • src/MiniExcel.Core/Reflection/MiniExcelMapper.cs
    • Updated MiniExcelMapper to use MiniExcelColumnMapping instead of MiniExcelColumnInfo and ColumnMappingsProvider instead of CustomPropertyHelper for mapping logic.
    • Updated MapValue to use MemberAccessor for setting values and changed the exception type to ValueNotAssignableException.
  • src/MiniExcel.Core/Reflection/MiniExcelProperty.cs
    • Removed this file, as its functionality was replaced by MiniExcelMemberAccessor.
  • src/MiniExcel.Core/WriteAdapters/AsyncEnumerableWriteAdapter.cs
    • Updated to use MiniExcelColumnMapping and ColumnMappingsProvider for column information.
  • src/MiniExcel.Core/WriteAdapters/DataReaderWriteAdapter.cs
    • Updated to use MiniExcelColumnMapping and ColumnMappingsProvider for column information.
  • src/MiniExcel.Core/WriteAdapters/DataTableWriteAdapter.cs
    • Updated to use MiniExcelColumnMapping and ColumnMappingsProvider for column information.
  • src/MiniExcel.Core/WriteAdapters/EnumerableWriteAdapter.cs
    • Updated to use MiniExcelColumnMapping and ColumnMappingsProvider for column information.
  • src/MiniExcel.Csv/Api/CsvImporter.cs
    • Simplified dynamic object creation by removing GetNewExpandoObject and AddPairToDict, and used the new CastToDictionary extension.
  • src/MiniExcel.Csv/CsvReader.cs
    • Updated to use ColumnNotFoundException and ExpandoHelper for creating empty expando objects.
    • Removed unused ConvertXyToCell method.
  • src/MiniExcel.Csv/CsvWriter.cs
    • Updated ToCsvString and GetHeader methods to use MiniExcelColumnMapping.
  • src/MiniExcel.OpenXml/Api/OpenXmlImporter.cs
    • Simplified dynamic object creation by removing GetNewExpandoObject and AddPairToDict, and used the new CastToDictionary extension.
  • src/MiniExcel.OpenXml/FluentMapping/MappingCellStreamAdapter.cs
    • Updated to use MiniExcelColumnMapping.
  • src/MiniExcel.OpenXml/Models/ExcelColumnWidth.cs
    • Updated GetFromMappings to use MiniExcelColumnMapping.
  • src/MiniExcel.OpenXml/OpenXmlReader.cs
    • Updated to use ExpandoHelper for creating empty expando objects.
  • src/MiniExcel.OpenXml/OpenXmlWriter.DefaultOpenXml.cs
    • Updated GetCellValue to use MiniExcelColumnMapping and refined enum description retrieval logic.
  • src/MiniExcel.OpenXml/OpenXmlWriter.cs
    • Updated to use MiniExcelColumnMapping for column information.
  • src/MiniExcel.OpenXml/Templates/OpenXmlTemplate.Impl.cs
    • Refined enum description retrieval logic.
  • tests/MiniExcel.Csv.Tests/AsyncIssueTests.cs
    • Updated expected exception types from InvalidOperationException to InvalidMappingException in tests.
  • tests/MiniExcel.Csv.Tests/IssueTests.cs
    • Updated expected exception types from MiniExcelInvalidCastException to ValueNotAssignableException and InvalidOperationException to InvalidMappingException in tests.
    • Updated CsvReader usage in tests.
  • tests/MiniExcel.Csv.Tests/MiniExcelCsvTests.cs
    • Updated CsvReader usage in tests.
    • Added new tests for field mapping: ExportAndQueryFieldsStrongMappingTest, QueryFieldsAsDynamicTest, ExportAndQueryMixedFieldAndPropertyTest, ExportAndQueryFieldsWithoutAttributeTest.
    • Updated expected exception types in tests.
  • tests/MiniExcel.OpenXml.Tests/MiniExcelIssueAsyncTests.cs
    • Updated expected exception types from ArgumentException to InvalidMappingException in tests.
  • tests/MiniExcel.OpenXml.Tests/MiniExcelIssueTests.cs
    • Updated expected exception types from MiniExcelInvalidCastException to ValueNotAssignableException, MiniExcelNotSerializableException to MemberNotSerializableException, and InvalidOperationException to InvalidMappingException in tests.
  • tests/MiniExcel.OpenXml.Tests/MiniExcelOpenXmlAsyncTests.cs
    • Updated expected exception types from InvalidOperationException to InvalidMappingException in tests.
  • tests/MiniExcel.OpenXml.Tests/MiniExcelOpenXmlTests.cs
    • Updated expected exception types from InvalidOperationException to InvalidMappingException in tests.
    • Removed redundant .Select(x => (IDictionary<string, object>)x) call.
    • Added new tests for field mapping: ExportAndQueryFieldsStrongMappingTest, QueryFieldsAsDynamicTest, ExportAndQueryMixedFieldAndPropertyTest, ExportAndQueryFieldsWithoutAttributeTest.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a great new feature by adding support for mapping public fields, which increases the flexibility of the library. The extensive refactoring to centralize mapping logic, rename classes for clarity (e.g., MiniExcelColumnInfo to MiniExcelColumnMapping), and introduce a base attribute class are all excellent improvements for maintainability.

However, I've found a few issues in the new mapping logic that could lead to incorrect behavior or confusing error messages. My review includes suggestions to fix these bugs. Please take a look at the detailed comments.

@michelebastione michelebastione merged commit 2f0bc52 into mini-software:master Mar 8, 2026
3 checks passed
@michelebastione michelebastione deleted the field-mapping branch March 8, 2026 22:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Option for supporting mapping to fields

1 participant