> For the complete documentation index, see [llms.txt](https://easyauth.papelship.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://easyauth.papelship.com/csharp-document/setup-project/installation.md).

# Installation

This guide details how to integrate the qPapel EasyAuth C# managed wrapper into your .NET solution and configure the automated packaging pipeline.

## Prerequisites

* **Target OS**: Windows 10 / Windows 11 (64-bit `x64` only)
* **.NET SDK**: .NET 8.0, .NET 7.0, .NET 6.0, or .NET Framework 4.8+
* **IDE**: Visual Studio 2022 / JetBrains Rider / VS Code
* **Configuration**: Release `x64` platform target

{% hint style="warning" %}
qPapel EasyAuth strictly runs under 64-bit (`x64`) runtimes. Compiling for `x86` or `Any CPU` with 32-bit enabled will prevent the native in-memory core from loading.
{% endhint %}

## SDK & Wrapper Options

{% tabs %}
{% tab title="Option A: Managed Wrapper DLL (wrapper/)" %}
Place `qPapelEasyAuth.NET.dll` in your project's `wrapper/` or `libs/` folder and reference it:

```xml
<ItemGroup>
  <Reference Include="qPapelEasyAuth.NET">
    <HintPath>wrapper\qPapelEasyAuth.NET.dll</HintPath>
  </Reference>
</ItemGroup>
```

{% endtab %}

{% tab title="Option B: Project Reference" %}
If you have the full SDK source tree, reference `qPapelLibCsharp.csproj` directly in your solution:

```xml
<ItemGroup>
  <ProjectReference Include="..\qPapelLibCsharp\qPapelLibCsharp.csproj" />
</ItemGroup>
```

{% endtab %}

{% tab title="Option C: NuGet Package" %}
Install the pre-built NuGet package (`qPapelEasyAuth.NET.2.0.0.nupkg`) into your package feed:

```powershell
dotnet add package qPapelEasyAuth.NET --version 2.0.0
```

{% endtab %}
{% endtabs %}

## Solution Structure

A typical C# integration project looks like this:

```
YourProject/
├── bin/x64/Release/net8.0/
│   ├── YourApp.exe
│   ├── YourApp.dll
│   ├── YourApp_packed.exe                     <-- Distribute this
│   ├── YourApp_packed.dll                     <-- Distribute this
│   └── YourApp_packed.runtimeconfig.json      <-- Distribute this
├── qPapelTools/
│   ├── qPapelPacker.exe                       <-- Native section injector
│   └── qPapelEasyAuth.dll                     <-- In-memory security core
├── wrapper/
│   └── qPapelEasyAuth.NET.dll                 <-- Managed C# wrapper assembly
├── Program.cs
└── YourProject.csproj
```

## Automated MSBuild Post-Build Event

Add the following post-build target to your `.csproj` file to automatically run `qPapelPacker` and copy the required runtime configuration companion files on every Release build:

```xml
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Platforms>x64</Platforms>
    <PlatformTarget>x64</PlatformTarget>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\qPapelLibCsharp\qPapelLibCsharp.csproj" />
  </ItemGroup>

  <Target Name="ResolveQPapelTools" BeforeTargets="PostBuild">
    <PropertyGroup>
      <QPapelPacker Condition="Exists('$(ProjectDir)qPapelTools\qPapelPacker.exe')">$(ProjectDir)qPapelTools\qPapelPacker.exe</QPapelPacker>
      <QPapelCoreDll Condition="Exists('$(ProjectDir)..\EasyAuthLib\x64\Release\csharp\qPapelEasyAuth.vxlang.dll')">$(ProjectDir)..\EasyAuthLib\x64\Release\csharp\qPapelEasyAuth.vxlang.dll</QPapelCoreDll>
      <QPapelCoreDll Condition="'$(QPapelCoreDll)' == '' And Exists('$(ProjectDir)qPapelTools\qPapelEasyAuth.dll')">$(ProjectDir)qPapelTools\qPapelEasyAuth.dll</QPapelCoreDll>
    </PropertyGroup>
  </Target>

  <Target Name="PostBuild" AfterTargets="PostBuildEvent" Condition="'$(Configuration)' == 'Release'">
    <MakeDir Directories="$(ProjectDir)wrapper" />
    <Copy SourceFiles="$(TargetDir)qPapelEasyAuth.NET.dll" DestinationFiles="$(ProjectDir)wrapper\qPapelEasyAuth.NET.dll" SkipUnchangedFiles="true" Condition="Exists('$(TargetDir)qPapelEasyAuth.NET.dll')" />

    <Exec Condition="Exists('$(ProjectDir)qPapelTools\qPapelPacker.exe') And Exists('$(ProjectDir)qPapelTools\qPapelEasyAuth.dll')"
          Command="echo [*] Packing C# binary with qPapelPacker...&#xD;&#xA;&quot;$(ProjectDir)qPapelTools\qPapelPacker.exe&quot; --dll &quot;$(ProjectDir)qPapelTools\qPapelEasyAuth.dll&quot; --input &quot;$(TargetDir)$(TargetName).exe&quot; --output &quot;$(TargetDir)$(TargetName)_packed.exe&quot;&#xD;&#xA;copy /y &quot;$(TargetDir)$(TargetName).runtimeconfig.json&quot; &quot;$(TargetDir)$(TargetName)_packed.runtimeconfig.json&quot; &gt;nul&#xD;&#xA;copy /y &quot;$(TargetDir)$(TargetName).deps.json&quot; &quot;$(TargetDir)$(TargetName)_packed.deps.json&quot; &gt;nul&#xD;&#xA;copy /y &quot;$(TargetDir)$(TargetName).dll&quot; &quot;$(TargetDir)$(TargetName)_packed.dll&quot; &gt;nul" />
  </Target>

</Project>
```

## Distribution Checklist

When publishing your application to end users, distribute the packed binary and its .NET companion files from the `bin/x64/Release/net8.0/` directory:

| File                                | Required | Purpose                                                   |
| ----------------------------------- | -------- | --------------------------------------------------------- |
| `YourApp_packed.exe`                | Yes      | The packed main executable containing the in-memory core. |
| `YourApp_packed.dll`                | Yes      | The compiled managed application assembly.                |
| `YourApp_packed.runtimeconfig.json` | Yes      | .NET runtime resolution configuration.                    |
| `YourApp_packed.deps.json`          | Yes      | Dependency manifest file.                                 |
| `qPapelEasyAuth.NET.dll`            | Yes      | The managed C# wrapper assembly.                          |

{% hint style="danger" %}
Do **not** distribute `qPapelTools/` or standalone `qPapelEasyAuth.dll` files to end users. The security engine is already securely embedded inside `YourApp_packed.exe`.
{% endhint %}