Configuration

Some properties that controls how EPPlus behaves can be configured via different ways of configuration.
This can be done via configuration files, environment variables or via code.

Configurable properties

Name	Default value	Description	Via config file	Via environment variable	Via code
LicenseContext	No default value, must be set.	Indicates if EPPlus is used in a commercial or noncommercial context. Value must either be Commercial or NonCommercial	x	x	x
JsonConfigBasePath	Current directory of the hosting app	Path to the folder where the json config file is located.			x
JsonConfigFileName	appsettings.json	File name of the json config file.			x
SuppressInitializationExceptions	false	The default behaviour of EPPlus is that Exceptions occurring during intialization (in the ExcelPackage constructor) are not caught by EPPlus. If this variable is set to true, these Exceptions will be caught and logged (unless they are catastrophic). If this value is true logged errors will be available in the ExcelPackage.InitializationErrors property.			x
IsWorksheets1Based	false	Controls whether the worksheets collection of the ExcelWorkbook class is 1 based or not. Use for backward compatibility reasons only!	x		x
PrecisionAndRoundingStrategy	Excel (v7 and up) DotNet (v6 and below)	Used in calculation, see this wiki page for more details	x		x
AllowCircularReferences	false	Used in calculation, see this wiki page for more details	x (json config only for .NET Core, 6+)		x

The ExcelPackage.Configure method

This method - added in EPPlus 6.0.7 - is a static method that should be called before the ExcelPackage constructor is called for the first time. With this method you can specify the location and name of the json configuration file. You can also configure EPPlus to catch Exceptions that are thrown if this file cannot be found or if your process doesn't have privileges to access the filesystem or environment variables.

These configuration values can only be set via code.

Example:

// set epplus to catch and log Exceptions when the constructor of ExcelPackage executes. Read config values from c:\config\myappsettings.json
ExcelPackage.Configure(x => { 
    x.SuppressInitializationExceptions = true;
    x.JsonConfigFileName = "myappsettings.json";
    x.JsonConfigBasePath = "c:\\config";
});

using(var package = new ExcelPackage())
{
   // if SuppressInitializationExceptions is true you can read logged errors via this property
   var errors = package.InitializationErrors;
   foreach(var error in errors)
   {
      var t = error.TimestampUtc;
      var m = error.ErrorMessage;
      var e = error.Exception;
   }
}

LicenseContext

This property must be set before the ExcelPackage class is instantiated, if not a LicenseException will be thrown when a debugger is attached.

1. Via code

using OfficeOpenXml;
// if you have a commercial license
ExcelPackage.LicenseContext = LicenseContext.Commercial;
// if you are using epplus for noncommercial purposes, see https://polyformproject.org/licenses/noncommercial/1.0.0/
ExcelPackage.LicenseContext = LicenseContext.NonCommercial;

2. Via appSettings.json

{
   "EPPlus": {
      "ExcelPackage": {
      "LicenseContext": "Commercial"
      }
   }
}

3. Via app/web.config

For environments where System.Configuration.ConfigurationManager.Appsettings is supported.

<appSettings>
    <add key="EPPlus:ExcelPackage.LicenseContext" value="NonCommercial" />
</appSettings>

4. Via environment variable EPPlusLicenseContext

Set this variable to either NonCommercial or Commercial. The variable should be set on user- or process-level.

IsWorksheets1Based

Controls whether the worksheets collection of the ExcelWorkbook class is 1 based or not. Use for backward compatibility reasons only!

1. Via code

using(var package = new ExcelPackage())
{
   package.Compatibility.IsWorksheets1Based = false;
}

2. Via appSettings.json

{
   "EPPlus": {
      "ExcelPackage": {
         "LicenseContext": "Commercial",
         "Compatibility": {
            "IsWorksheets1Based": "true"
         }
      }
   }
}

3. Via app/web.config

For environments where System.Configuration.ConfigurationManager.Appsettings is supported.

<appSettings>
    <add key="EPPlus:ExcelPackage.Compatibility.IsWorksheets1Based" value="true" />
</appSettings>