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
License	No default value, must be set.	N.B. This property must be used from version 8 and above. License configuration. Specifies if EPPlus is used in a commercial, noncommercial or personal/noncommercial context.	x	x	x
LicenseContext	No default value, must be set.	N.B. This property is obsolete from version 8 and above. 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;
   }
}

License

Use this property for licensing configuration from version 8 and up.

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

Note that the string <Your license key> in the examples below should be replaced by your license key.

1. Via code

using OfficeOpenXml;
// If you have purchased an EPPlus license for commerical use
ExcelPackage.License.SetCommercial("<Your license key>");  //Sets your license key in code.
// If you are a Noncommercial organization.
ExcelPackage.License.SetNonCommercialOrganization("<My Noncommercial organization>"); //This will also set the Company property to the organization name provided in the argument.
// If you use EPPlus for Noncommercial personal use.
ExcelPackage.License.SetNonCommercialPersonal("<My Name>"); //This will also set the Author property to the name provided in the argument.

2. Via appSettings.json

// Commercial use
{
    "EPPlus": {
        "ExcelPackage": {
            "License": "Commercial:<Your license key>"
        }
    }
}
// Noncommercial use
{
    "EPPlus": {
        "ExcelPackage": {
            "LicenseContext": "NonCommercialOrganization:<The noncommercial organization>" //Please provide the name of the noncommercial organization you represent.
        }
    }
}
// Personal/noncommercial use
{
    "EPPlus": {
        "ExcelPackage": {
            "LicenseContext": "NonCommercialPersonal:<Your Name>"     //Please provide your name.
        }
    }
}

3. Via app.config

<appSettings>
    <!--For noncommerical and personal use, replace the value with the corresponding values from the example above -->
    <add key="EPPlus:ExcelPackage:License" value="Commercial,<Your license key>" />
</appSettings>

4. Set the Environment variable 'EPPlusLicense'

Commerical use:

> SETX EPPlusLicense "Commercial:<Your license key>"

Noncommercial organization:

> SETX EPPlusLicense "NonCommercialOrganization:<The Noncommercial organization>"

Personal/noncommercial use:

> SETX EPPlusLicense "NonCommercialPersonal:<Your Name>"

Please note that the environment variable might be case-sensitive depending on your environment.

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>