C# SDK Installation Guide

This guide covers the installation of the Spreadsheet C# SDK.

Project Structure

Recommended Directory Structure

my-csharp-project/
├── src/
│   └── Program.cs
├── SpreadsheetSDK/
│   ├── x64/
│   │   ├── SpreadsheetEngine.dll
│   │   ├── SpreadsheetSDK.deps.json
│   │   ├── SpreadsheetSDK.dll
│   │   ├── icuuc.dll
│   │   ├── libc++.dll
│   │   ├── lsapiw64.dll
│   │   ├── third_party_abseil-cpp_absl.dll
│   │   ├── third_party_icu_icui18n.dll
│   │   ├── third_party_zlib.dll
│   │   ├── v8.dll
│   │   ├── v8_libbase.dll
│   │   └── v8_libplatform.dll
│   └── x86/
│       ├── SpreadsheetEngine.dll
│       ├── SpreadsheetSDK.deps.json
│       ├── SpreadsheetSDK.dll
│       ├── icuuc.dll
│       ├── libc++.dll
│       ├── lsapiw32.dll
│       ├── third_party_abseil-cpp_absl.dll
│       ├── third_party_icu_icui18n.dll
│       ├── third_party_zlib.dll
│       ├── v8.dll
│       ├── v8_libbase.dll
│       └── v8_libplatform.dll
├── License/
│   └── License
├── my-csharp-project.csproj
└── README.md

.NET Project Configuration

Basic Project File

<!-- my-csharp-project.csproj example -->
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <Platforms>x64;x86</Platforms>
  </PropertyGroup>

  <!-- Add Spreadsheet SDK Reference -->
  <ItemGroup>
    <Reference Include="SpreadsheetSDK">
      <HintPath>$(ProjectDir)SpreadsheetSDK\$(Platform)\SpreadsheetSDK.dll</HintPath>
    </Reference>
  </ItemGroup>

  <!-- Spreadsheet SDK Dependencies Specification -->
  <ItemGroup>
    <None Include="$(ProjectDir)SpreadsheetSDK\$(Platform)\SpreadsheetSDK.deps.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Visible>false</Visible>
    </None>
  </ItemGroup>

  <!-- Libraries Used by Spreadsheet SDK -->
  <ItemGroup>
    <None Include="$(ProjectDir)SpreadsheetSDK\$(Platform)\SpreadsheetEngine.dll">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Visible>false</Visible>
    </None>
    <None Include="$(ProjectDir)SpreadsheetSDK\$(Platform)\icuuc.dll">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Visible>false</Visible>
    </None>
    <None Include="$(ProjectDir)SpreadsheetSDK\$(Platform)\libc++.dll">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Visible>false</Visible>
    </None>
    <None Include="$(ProjectDir)SpreadsheetSDK\$(Platform)\third_party_abseil-cpp_absl.dll">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Visible>false</Visible>
    </None>
    <None Include="$(ProjectDir)SpreadsheetSDK\$(Platform)\third_party_icu_icui18n.dll">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Visible>false</Visible>
    </None>
    <None Include="$(ProjectDir)SpreadsheetSDK\$(Platform)\third_party_zlib.dll">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Visible>false</Visible>
    </None>
    <None Include="$(ProjectDir)SpreadsheetSDK\$(Platform)\v8.dll">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Visible>false</Visible>
    </None>
    <None Include="$(ProjectDir)SpreadsheetSDK\$(Platform)\v8_libbase.dll">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Visible>false</Visible>
    </None>
    <None Include="$(ProjectDir)SpreadsheetSDK\$(Platform)\v8_libplatform.dll">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Visible>false</Visible>
    </None>
  </ItemGroup>

  <!-- Libraries for authentication are branched by platform -->
  <ItemGroup Condition="'$(Platform)'=='x86'">
    <None Include="$(ProjectDir)SpreadsheetSDK\$(Platform)\lsapiw32.dll">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Visible>false</Visible>
    </None>
  </ItemGroup>
  <ItemGroup Condition="'$(Platform)'=='x64'">
    <None Include="$(ProjectDir)SpreadsheetSDK\$(Platform)\lsapiw64.dll">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Visible>false</Visible>
    </None>
  </ItemGroup>

  <!-- License File -->
  <!-- Instead of including it in the build output like this, a separate path can be specified through the API -->
  <ItemGroup>
    <None Include="$(ProjectDir)License\License" TargetPath="License\License">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Visible>false</Visible>
    </None>
  </ItemGroup>

</Project>

Build Output Example

my-csharp-project/
├── bin/
│   └── x64/
│       └── Release/
│           └── net8.0/
│               ├── License/
│               │   └── License
│               ├── SpreadsheetEngine.dll
│               ├── SpreadsheetSDK.deps.json
│               ├── SpreadsheetSDK.dll
│               ├── icuuc.dll
│               ├── libc++.dll
│               ├── lsapiw64.dll
│               ├── my-csharp-project.deps.json
│               ├── my-csharp-project.dll
│               ├── my-csharp-project.exe
│               ├── my-csharp-project.pdb
│               ├── my-csharp-project.runtimeconfig.json
│               ├── third_party_abseil-cpp_absl.dll
│               ├── third_party_icu_icui18n.dll
│               ├── third_party_zlib.dll
│               ├── v8.dll
│               ├── v8_libbase.dll
│               └── v8_libplatform.dll
└── my-csharp-project.csproj

Spreadsheet SDK Initialization and Usage

// Program.cs

// Specify License Path
SpreadsheetSDK.License.FilePath = @"D:\License";
// Relative path is also possible
//HCellSDK.License.FilePath = @"License\License";

// Validate License
if (SpreadsheetSDK.License.Validate(out string reason) == false) {
    Console.WriteLine(reason);

    return;
}

// Initialize Spreadsheet SDK
//   cf) Must be synchronized with the application lifecycle
if (SpreadsheetSDK.Global.Initialize() == false) {
    Console.WriteLine("Failed to initialize Spreadsheet SDK.");

    return;
}

try {
    // Get Spreadsheet SDK Instance
    SpreadsheetSDK.Entity.SDKInstance instance = SpreadsheetSDK.Global.GetInstance();
    // Get Spreadsheet SDK Engine Object
    SpreadsheetSDK.Entity.Application application = instance.Application;
    // Create New Document
    SpreadsheetSDK.Entity.Workbook workbook = application.Workbooks.Add();

    string filename = @"D:\test.xlsx";

    // Save with Specified Filename
    workbook.SaveAs(filename);
    // Close Document
    workbook.Close();

    Console.WriteLine($"File {filename} has been created.");
} catch (Exception e) {
    Console.WriteLine(e.ToString());
}

// Dispose Spreadsheet SDK
//   cf) Must be synchronized with the application lifecycle
SpreadsheetSDK.Global.Dispose();

Troubleshooting

Common Issues

License Error

Unhandled exception. System.Exception: Error: Certification failed.
   at SpreadsheetSDK.Util.ExceptionUtil.ThrowIfError()
   at SpreadsheetSDK.Global.Initialize()
   at Program.<Main>$(String[] args) in D:\my-csharp-project\src\Program.cs:line 1

• When SpreadsheetSDK.License.FilePath is specified, verify that a valid license file exists at that path

Or

• Verify that a valid license file exists at $(Spreadsheet SDK Path)\License\License

Next Steps

• License Configuration - License Activation Guide