> For the complete documentation index, see [llms.txt](https://docs.apryse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apryse.com/uwp/get-started/winui.md).
# Integrate the WinUI PDF Library into Windows Apps
Integrate a free trial of Apryse WinUI SDK into your WinUI 3 desktop application on Windows. Get unlimited usage & support. Prerequisites: Visual Studio 2019 16.8+, .NET 5+. Follow step-by-step guide
This guide will help you to [integrate a free trial of the Apryse WinUI SDK into WinUI 3 desktop application](#integrate-into-your-application) on Windows. Your free trial includes unlimited trial usage and support from solution engineers.
## Prerequisites
* [Visual Studio](https://visualstudio.microsoft.com/vs/older-downloads/) 2019 16.8 or higher.**Note:** This guide will use Visual Studio 2019.
* [.NET 5+](https://dotnet.microsoft.com/en-us/download/dotnet/) installed.
* Apryse's WinUI PDF library for Windows:
Download the SDK
Download
{% hint style="info" %}
**No trial license key required.**
The trial of Apryse Mobile SDK does not require a trial key. A commercial license key is required for use in a production environment. Please [contact sales](https://apryse.com/form/contact-sales) to purchase a commercial key or if you need any other license key assistance.
{% endhint %}
{% hint style="warning" %}
**Keep your license keys confidential.**
License keys are uniquely generated. Please make sure that it is not publicly available (e.g. in your public GitHub).
{% endhint %}
## Create a WinUI 3 desktop application
1. Open a new instance of Visual Studio and create a new Project `(File -> New -> Project...)`. In the new project dialog, select C# and WinUI development. Call the application `SimplePDFViewer`.
1. During the creation make sure to choose one of the templates that uses MVVM for easy setup
## Integrate into your application
You can follow a manual or nuget integration as described below.
### Manually
1. In your WinUI 3 application project right-click on `Dependencies` and `Add Project Reference...`. Navigate to `PDFNET_BASE/Lib/` and choose folder with project's .NET version (.NET 5 or 6) and add `PDFNetWinUI.dll`.
`PDFNetWinUI.dll` is an interop module that allows different version of projects using .NET to consume native libraries, which will be added to the solution next.
1. Now we will add the native librar to the project by right-clicling on the project and selecting `Add` -> `Existing item`, then navitate to `PDFNET_BASE/Lib/` and select which platform (x64 or x86) the project is targeting and select `pdftron.dll` native library.
Once the `pdftron.dll` is added to the project, clikc on it and under it's properties change `Copy to Output Directory` to `Copy always`
1. The result for your project should look similar to the image below.
### NuGet using Visual Studio
This section will go through the nuget integration steps.
1. Find your project in the Solution Explorer. Right Click on the project and click on `Manage NuGet Packages...`. In the package manager, select the Browse tab and search for `PDFTron.WinUI`. Install this package.
You can also find the package on [nuget.org](https://www.nuget.org/packages/PDFTron.WinUI/).
1. Done integrating Apryse WinUI SDK to your WinUI 3 desktop app. Now you can go to the next step `View a document` below.
## Viewing a document in your WinUI 3 desktop application
These steps must be follow reusing the aplication created above for either Manual or NuGet integration.
### Step 1: Update xaml
Using the `MainPage.xaml` of your WinUI 3 application project create a `Border` and a `Button` in the `Grid` We will use the `Border` to host the `PDFViewCtrl` which will be used to view the PDF document. The `Button` will be used to open the PDF document using WinRT calls.
Your XAML should look like the following:
{% tabs %}
{% tab title="XML" %}
{% code lineNumbers="true" %}
```xml
```
{% endcode %}
{% endtab %}
{% endtabs %}
Note we added a `OpenButton_Click` event to the button which will be used to write the logic to open a document. We will get to it later in the guide.
### Step 2: Add the viewer
Now, we want to add the `PDFViewCtrl` to the app. We do this in `MainPage.xaml.cs` (code-behind). Create a `PDFViewCtrl` variable to be used in the scope of this page:
{% tabs %}
{% tab title="C#" %}
{% code lineNumbers="true" %}
```csharp
public sealed partial class MainPage : Page
{
pdftron.PDF.PDFViewCtrl MyPDFViewCtrl;
...
```
{% endcode %}
{% endtab %}
{% endtabs %}
Next, we need to initialize `PDFNet` and create a `PDFViewCtrl`, so let's do this in the constructor of the MainPage. We also need to make the PDFViewCtrl the child of the PDFViewBorder to it can be host and rendered properly.
{% tabs %}
{% tab title="C#" %}
{% code lineNumbers="true" %}
```csharp
public MainPage()
{
this.InitializeComponent();
pdftron.PDFNet.Initialize("YOUR_APRYSE_LICENSE_KEY");
MyPDFViewCtrl = new pdftron.PDF.PDFViewCtrl();
PDFViewBorder.Child = MyPDFViewCtrl;
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
We also have to add a handler for the Open button. Let's do that in MainPage's constructor after we have created a PDFViewCtrl. Make sure to make the event `async`:
{% tabs %}
{% tab title="C#" %}
{% code lineNumbers="true" %}
```csharp
private async void OpenButton_Click(object sender, Microsoft.UI.Xaml.RoutedEventArgs e)
{
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
Before we add the proper logic, ensure to add the following namespaces:
{% tabs %}
{% tab title="C#" %}
{% code lineNumbers="true" %}
```csharp
using System;
using System.Runtime.InteropServices; // used to make WinRT calss
using WinRT; // this namespace must be added in roder to use WinRT classes
using Microsoft.UI.Xaml;
using Windows.Storage;
using Windows.Storage.Pickers;
```
{% endcode %}
{% endtab %}
{% endtabs %}
Now we need to add the logic to open a document, in this case we are using the `FileOpenPicker` from WinRT and using interop to ensure the logic works properly. Below we have also added a helper logic to make sure the file picker will run on a win32 desktop app by setting the proper handle (HWND).
{% tabs %}
{% tab title="C#" %}
{% code lineNumbers="true" %}
```csharp
private async void OpenButton_Click(object sender, Microsoft.UI.Xaml.RoutedEventArgs e)
{
// Get a file from the file picker.
FileOpenPicker fileOpenPicker = new FileOpenPicker();
fileOpenPicker.ViewMode = PickerViewMode.List;
fileOpenPicker.FileTypeFilter.Add(".pdf");
// When running on win32, FileOpenPicker needs to know the top-level hwnd via IInitializeWithWindow::Initialize.
if (Window.Current == null)
{
IInitializeWithWindow initializeWithWindowWrapper = fileOpenPicker.As();
IntPtr hwnd = GetActiveWindow();
initializeWithWindowWrapper.Initialize(hwnd);
}
var file = await fileOpenPicker.PickSingleFileAsync();
// Create a PDFDocument and use it as the source for the PDFViewCtrl
if (file != null)
{
Windows.Storage.Streams.IRandomAccessStream stream = await file.OpenAsync(FileAccessMode.ReadWrite);
pdftron.PDF.PDFDoc doc = pdftron.PDF.PDFDoc.CreateFromStream(stream);
MyPDFViewCtrl.SetDoc(doc);
}
}
///
/// "In Desktop, or Win32, it's required to specify which Window Handle (HWND) owns the File/Folder Picker"
/// Github issue: https://github.com/microsoft/microsoft-ui-xaml/issues/4100
///
[ComImport, System.Runtime.InteropServices.Guid("3E68D4BD-7135-4D10-8018-9FB6D9F33FA1"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface IInitializeWithWindow
{
void Initialize([In] IntPtr hwnd);
}
[DllImport("user32.dll", ExactSpelling = true, CharSet = CharSet.Auto, PreserveSig = true, SetLastError = false)]
public static extern IntPtr GetActiveWindow();
```
{% endcode %}
{% endtab %}
{% endtabs %}
Now you can build and launch the app and we should now have a very basic PDF document viewer.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.apryse.com/uwp/get-started/winui.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.