## So how do I start?

### Installation

EPPlus is distributed via Microsofts package manager [Nuget](<https://www.nuget.org/>). We refer to [Microsoft's official documentation](<https://docs.microsoft.com/en-us/nuget/>) for detailed descriptions on how to get started/use Nuget. Here is a link to the [EPPlus Nuget package](<https://www.nuget.org/packages/EPPlus/>).

For supported .NET frameworks, see [this link](<https://www.nuget.org/packages/EPPlus/#supportedframeworks-body-tab>).

### Configure licensing information

Note that this is done differently depending on which major version of EPPlus you are using. - [EPPlus 8 and above](<#epplus-8-and-above-set-the-excelpackagelicense-property>) - [EPPlus 7 and below](<#epplus-7-and-below-set-the-licensecontext>)

### EPPlus 8 and above - Set the `ExcelPackage.License` property

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. Note that EPPlus only validates if the license is expired 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

```csharp
using OfficeOpenXml;
// If you have purchased an EPPlus license for commerical use
var yourLicenseKey = "Replace this with your license key";
ExcelPackage.License.SetCommercial(yourLicenseKey);  //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.
```

```vbnet
Imports OfficeOpenXml
' If you have purchased an EPPlus license for commerical use
Dim yourLicenseKey = "Replace this with your license key"
ExcelPackage.License.SetCommercial(yourLicenseKey)  '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

##### Config file

Up until version 8.2.0 EPPlus assumes that the name of the config file is `appSettings.json` and that the file is located in the current folder of the application. You can change the name and location of the config file via the [`ExcelPackage.Configure`](<https://epplussoftware.com/docs/getting-started/configuration/index.md>) method.

From version 8.2.1 you can provide an `IConfiguration` instance from the hosting application, either via many of the constructors or via the [`ExcelPackage.Configure`](<https://epplussoftware.com/docs/getting-started/configuration/index.md>).

Example:

```csharp
var builder = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true);

IConfiguration config = builder.Build();

// EPPlus will now try to read the license information via the supplied IConfiguration.
var package = new ExcelPackage(config);
// or...
ExcelPackage.Configure(x => x.Configuration = config);
var package = new ExcelPackage();
```

```vbnet
Dim builder = New ConfigurationBuilder() _
    .SetBasePath(Directory.GetCurrentDirectory()) _
    .AddJsonFile("appsettings.json", optional:=False, reloadOnChange:=True)

Dim config As IConfiguration = builder.Build()

' EPPlus will now try to read the license information via the supplied IConfiguration.
Dim package = New ExcelPackage(config)
' or...
ExcelPackage.Configure(Sub(x) x.Configuration = config)
Dim package = New ExcelPackage()
```

#### Appsettings examples

```text
// Commercial use
{
    "EPPlus": {
        "ExcelPackage": {
            "License": "Commercial: Replace this with your license key"
        }
    }
}
// Noncommercial use
{
    "EPPlus": {
        "ExcelPackage": {
            "License": "NonCommercialOrganization: Replace this with the name of your noncommercial organization" //Please provide the name of the noncommercial organization you represent.
        }
    }
}
// Personal/noncommercial use
{
    "EPPlus": {
        "ExcelPackage": {
            "License": "NonCommercialPersonal:Replace this with your name"     //Please provide your name.
        }
    }
}
```

#### 3\. Via app.config

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

#### 4\. Set the Environment variable 'EPPlusLicense'

Commerical use:

```console
> SETX EPPlusLicense "Commercial: Replace this with your license key"
```

Noncommercial organization:

```console
> SETX EPPlusLicense "NonCommercialOrganization:Replace this with the name of your Noncommercial organization"
```

Personal/noncommercial use:

```console
> SETX EPPlusLicense "NonCommercialPersonal:Replace this with your Name"
```

### EPPlus 7 and below - Set the LicenseContext

*N.B. Note that the `LicenseContext` property is obsolete from version 8 and up.*

Before you start to code against EPPlus you need to set the static `ExcelPackage.LicenseContext` property. This can have two different values: `NonCommercial` if you use EPPlus for noncommercial purposes (see the [Polyform Noncommercial 1.0 license](<https://polyformproject.org/licenses/noncommercial/1.0.0/>)) or `Commercial` if you have a commercial license. If the `LicenseContext` is not set EPPlus will throw a `LicenseException`, this happens only when a debugger is attached.  
Commercial licenses can be purchased at our website: [https://epplussoftware.com](<https://epplussoftware.com/>).  
For more details on how to configure EPPlus see our [Configuration](<https://epplussoftware.com/docs/getting-started/configuration/index.md>) wiki page.

Here are the options for how you can set the license context.

#### 1\. Via code

```csharp
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;
```

```vbnet
Imports 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

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

#### 3\. Via app/web.config

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

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

#### 4\. Via environment variable EPPlusLicenseContext

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

## Start writing code

### The ExcelPackage class

The first thing you do is to create an instance to the `ExcelPackage` class. To do that you first need to add a `using` directive to `OfficeOpenXml` namespace in the top of your file. This is the top namespace in EPPlus;

```csharp
using OfficeOpenXml;
```

```vbnet
Imports OfficeOpenXml
```

You can now reference the `ExcelPackage` class directly for your class. Remember that the `ExcelPackage` class implements the `System.IDisposable` interface, so you should add a `using`-statement when declaring instances of it (alternatively make sure to call its `Dispose()` method when you are done with it). Below are some simple examples of common tasks.

#### Working with files

```csharp
//Creates a blank workbook. Use the using statment, so the package is disposed when we are done.
using (var p = new ExcelPackage())
{
   // A workbook must have at least one worksheet, so lets add one... 
   var ws=p.Workbook.Worksheets.Add("MySheet");
   // To set values in the spreadsheet use the Cells indexer.
   ws.Cells["A1"].Value = "This is cell A1";
   // Save the new workbook. We haven't specified the filename in the constructor,
   // so use the SaveAs method.
   p.SaveAs(@"c:\workbooks\myworkbook.xlsx");
}
```

```vbnet
'Creates a blank workbook. Use the using statment, so the package is disposed when we are done.
Using p As New ExcelPackage()
    ' A workbook must have at least one worksheet, so lets add one... 
    Dim ws = p.Workbook.Worksheets.Add("MySheet")
    ' To set values in the spreadsheet use the Cells indexer.
    ws.Cells("A1").Value = "This is cell A1"
    ' Save the new workbook. We haven't specified the filename in the constructor,
    ' so use the SaveAs method.
    p.SaveAs("c:\workbooks\myworkbook.xlsx")
End Using
```

You can also specify a the path of a workbook directly in the constructor.

```csharp
// Open the workbook (or create it if it doesn't exist)
using (var p = new ExcelPackage(@"c:\workbooks\myworkbook.xlsx"))
{
   // Get the Worksheet created in the previous codesample. 
   var ws=p.Workbook.Worksheets["MySheet"];
   // Set the cell value using row and column.
   ws.Cells[2, 1].Value = "This is cell A2. Its font style is now set to bold";
   // The style object is used to access most cells formatting and styles.
   ws.Cells[2, 1].Style.Font.Bold=true;
   // Save and close the package.
   p.Save();
}
```

```vbnet
' Open the workbook (or create it if it doesn't exist)
Using p As New ExcelPackage("c:\workbooks\myworkbook.xlsx")
    ' Get the Worksheet created in the previous codesample. 
    Dim ws = p.Workbook.Worksheets("MySheet")
    ' Set the cell value using row and column.
    ws.Cells(2, 1).Value = "This is cell A2. Its font style is now set to bold"
    ' The style object is used to access most cells formatting and styles.
    ws.Cells(2, 1).Style.Font.Bold = True
    ' Save and close the package.
    p.Save()
End Using
```

#### Working with streams

Besides reading/writing files, EPPlus can also handle workbooks as streams. This can be useful when creating workbooks on a web server or whenever you want to create/read workbooks without having a physical file.

```csharp
// Create a new workbook and save it to a System.IO.MemoryStream
using var ms = new MemoryStream();
using var p = new ExcelPackage(ms);
var sheet = p.Workbook.Worksheets.Add("Sheet1");
sheet.Cells["A1"].Value = "Hello world!";
// write the workbook bytes to the stream
p.Save();

// Open a new ExcelPackage from the MemoryStream...
using var p2 = new ExcelPackage(ms);
var helloWorld = p2.Workbook.Worksheets[0].Cells["A1"].Value;
```

```vbnet
' Create a new workbook and save it to a System.IO.MemoryStream
Using ms As New MemoryStream()
    Using p As New ExcelPackage(ms)
        Dim sheet = p.Workbook.Worksheets.Add("Sheet1")
        sheet.Cells("A1").Value = "Hello world!"
        ' write the workbook bytes to the stream
        p.Save()

        ' Open a new ExcelPackage from the MemoryStream...
        Using p2 As New ExcelPackage(ms)
            Dim helloWorld = p2.Workbook.Worksheets(0).Cells("A1").Value
        End Using
    End Using
End Using
```

Besides writing to a `System.IO.Stream`, you can also get the workbook as an array of bytes.

```csharp
using var p = new ExcelPackage();
var sheet = p.Workbook.Worksheets.Add("Sheet1");
sheet.Cells["A1"].Value = "Hello world!";
byte[] workbookBytes = p.GetAsByteArray();
```

```vbnet
Using p As New ExcelPackage()
    Dim sheet = p.Workbook.Worksheets.Add("Sheet1")
    sheet.Cells("A1").Value = "Hello world!"
    Dim workbookBytes As Byte() = p.GetAsByteArray()
End Using
```

#### Password protection/encryption

You can also [pass a password to the constructor](<https://epplussoftware.com/docs/vba-and-protection/encrypt-and-protect-your-workbook/#encryption>), if the workbook is encrypted.

### Good to know

In most cases you probably have some data that you want to move to an Excel spreadsheet, do some styling, maybe add a formula or a chart.

But before we get started, here are some things to keep in mind when you work with EPPlus:  
\- ***Cell addresses***, ***number formats*** and ***formulas*** are culture-insensitive, meaning that these might look a little bit different when you write your code compared with how they appear in your spreadsheet application. This is the way OOXML is stored and is then translated to your culture when the workbook is opened in Excel (or whatever spreadsheet application you are using).

- ***Addresses*** are separated by a comma (,).  
  Example `worksheet.Cells["A1:C1,C3"].Style.Font.Bold = true`.
- ***Numberformats*** use dot for decimal (.) and comma (,) for thousand separator.  
  Example `worksheet.Cells["B2:B3"].Style.NumberFormat.Format = "#,##0.00";`.
- ***Formulas*** use comma (,) to separate parameters. And you should not add the leading equal sign as you do in spreadsheet applications. Here is an example: `worksheet.Cells["C11"].Formula="SUBTOTAL(9,\"C1:C10\")";`.

## What's next?

This wiki contains many examples and introductions to EPPlus functionality. Another good way to learn more about the library is to clone one of our [sample projects](<https://epplussoftware.com/docs/getting-started/the-sample-project/index.md>) and explore the code. You can also have a look at our [web sample project](<https://samples.epplussoftware.com/>) to learn more about how you can use EPPlus in web apps.

## See also

- [The Sample Project](<https://epplussoftware.com/docs/getting-started/the-sample-project/index.md>)
- [EPPlus and Docker](<https://epplussoftware.com/docs/getting-started/epplus-and-docker/index.md>)
- [EPPlus and Blazor](<https://epplussoftware.com/docs/getting-started/epplus-and-blazor/index.md>)
- [EPPlus and Linux](<https://epplussoftware.com/docs/getting-started/epplus-and-linux/index.md>)
- [Security](<https://epplussoftware.com/docs/about-epplus/security/index.md>)
- [Configuration](<https://epplussoftware.com/docs/getting-started/configuration/index.md>)
- [Releases/versioning](<https://epplussoftware.com/docs/versions/releases-versioning/index.md>)