Electron.NET/docs/API/WebContents.md

# Electron.WebContents

Render and control web pages.

## Overview

The `Electron.WebContents` API provides control over web page content within Electron windows. It handles page loading, navigation, JavaScript execution, and web page lifecycle events.

## Properties

#### 📋 `int Id`
Gets the unique identifier for this web contents.

#### 📋 `Session Session`
Manage browser sessions, cookies, cache, proxy settings, etc.

## Methods

#### 🧊 `void ExecuteJavaScriptAsync(string code, bool userGesture = false)`
Evaluates script code in page.

In the browser window some HTML APIs like `requestFullScreen` can only be invoked by a gesture from the user. Setting `userGesture` to `true` will remove this limitation.

Code execution will be suspended until web page stop loading.

**Parameters:**
- `code` - The code to execute
- `userGesture` - if set to `true` simulate a user gesture

**Returns:**

The result of the executed code.

#### 🧊 `Task<PrinterInfo[]> GetPrintersAsync()`
Get system printers.

**Returns:**

Array of available printers.

#### 🧊 `Task<string> GetUrl()`
Get the URL of the loaded page.

It's useful if a web-server redirects you and you need to know where it redirects. For instance, It's useful in case of Implicit Authorization.

**Returns:**

URL of the loaded page.

#### 🧊 `void InsertCSS(bool isBrowserWindow, string path)`
Inserts CSS into the web page.

See: https://www.electronjs.org/docs/api/web-contents#contentsinsertcsscss-options

Works for both BrowserWindows and BrowserViews.

**Parameters:**
- `isBrowserWindow` - Whether the webContents belong to a BrowserWindow or not (the other option is a BrowserView)
- `path` - Absolute path to the CSS file location

#### 🧊 `Task LoadURLAsync(string url)`
Loads the url in the window. The url must contain the protocol prefix.

The async method will resolve when the page has finished loading, and rejects if the page fails to load.

A noop rejection handler is already attached, which avoids unhandled rejection errors.

Loads the `url` in the window. The `url` must contain the protocol prefix, e.g. the `http://` or `file://`. If the load should bypass http cache then use the `pragma` header to achieve it.

**Parameters:**
- `url` - URL to load

#### 🧊 `Task LoadURLAsync(string url, LoadURLOptions options)`
Loads the url with additional options.

The async method will resolve when the page has finished loading, and rejects if the page fails to load.

A noop rejection handler is already attached, which avoids unhandled rejection errors.

Loads the `url` in the window. The `url` must contain the protocol prefix, e.g. the `http://` or `file://`. If the load should bypass http cache then use the `pragma` header to achieve it.

**Parameters:**
- `url` - URL to load
- `options` - Loading options

#### 🧊 `void OpenDevTools()`
Opens the devtools.

#### 🧊 `void OpenDevTools(OpenDevToolsOptions openDevToolsOptions)`
Opens the devtools with options.

**Parameters:**
- `openDevToolsOptions` - Developer tools options

#### 🧊 `Task<bool> PrintAsync(PrintOptions options = null)`
Prints window's web page.

**Parameters:**
- `options` - Print options

**Returns:**

Whether the print operation succeeded.

#### 🧊 `Task<bool> PrintToPDFAsync(string path, PrintToPDFOptions options = null)`
Prints window's web page as PDF with Chromium's preview printing custom settings.The landscape will be ignored if @page CSS at-rule is used in the web page. By default, an empty options will be regarded as: Use page-break-before: always; CSS style to force to print to a new page.

**Parameters:**
- `path` - Output file path
- `options` - PDF generation options

**Returns:**

Whether the PDF generation succeeded.

#### 🧊 `Task<double> GetZoomFactorAsync()`
Returns the current zoom factor. A factor of `1.0` means 100%.

#### 🧊 `void SetZoomFactor(double factor)`
Changes the zoom factor to the specified factor. The zoom factor is the zoom percent divided by 100, so 300% = `3.0`. The factor must be greater than `0.0`.

**Parameters:**
- `factor` - The zoom factor

#### 🧊 `Task<double> GetZoomLevelAsync()`
Returns the current zoom level.

#### 🧊 `void SetZoomLevel(double level)`
Changes the zoom level to the specified level. The original size is `0` and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of the original size, respectively.

**Parameters:**
- `level` - The zoom level

#### 🧊 `Task SetVisualZoomLevelLimitsAsync(double minimumLevel, double maximumLevel)`
Sets the maximum and minimum pinch-to-zoom level.

**Parameters:**
- `minimumLevel` - The minimum pinch-to-zoom level
- `maximumLevel` - The maximum pinch-to-zoom level

## Events

#### ⚡ `InputEvent`
Emitted when an input event is sent to the WebContents.

#### ⚡ `OnCrashed`
Emitted when the renderer process crashes or is killed.

#### ⚡ `OnDidFailLoad`
Emitted when the load failed.

#### ⚡ `OnDidFinishLoad`
Emitted when the navigation is done, i.e. the spinner of the tab has stopped spinning, and the onload event was dispatched.

#### ⚡ `OnDidNavigate`
Emitted when a main frame navigation is done.

#### ⚡ `OnDidRedirectNavigation`
Emitted after a server side redirect occurs during navigation.

#### ⚡ `OnDidStartNavigation`
Emitted when any frame (including main) starts navigating.

#### ⚡ `OnDomReady`
Emitted when the document in the top-level frame is loaded.

#### ⚡ `OnWillRedirect`
Emitted when a server side redirect occurs during navigation.

#### ⚡ `OnZoomChanged`
Emitted when the user changes the zoom level using the mouse wheel or the keyboard. The handler receives the `ZoomDirection` (`In` or `Out`).

## Usage Examples

### Page Loading

```csharp
// Load URL with options
await webContents.LoadURLAsync("https://example.com", new LoadURLOptions
{
    UserAgent = "MyApp/1.0",
    ExtraHeaders = "Authorization: Bearer token123"
});

// Load local file
await webContents.LoadURLAsync("file://" + Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "app/index.html"));

// Get current URL
var currentUrl = await webContents.GetUrl();
Console.WriteLine($"Current URL: {currentUrl}");
```

### JavaScript Execution

```csharp
// Execute simple JavaScript
var result = await webContents.ExecuteJavaScriptAsync("document.title");
Console.WriteLine($"Page title: {result}");

// Execute with user gesture simulation
await webContents.ExecuteJavaScriptAsync("document.requestFullscreen()", true);

// Execute complex code
var userAgent = await webContents.ExecuteJavaScriptAsync("navigator.userAgent");
Console.WriteLine($"User agent: {userAgent}");
```

### Developer Tools

```csharp
// Open dev tools
webContents.OpenDevTools();

// Open with specific options
webContents.OpenDevTools(new OpenDevToolsOptions
{
    Mode = DevToolsMode.Detached,
    Activate = true
});
```

### CSS Injection

```csharp
// Inject CSS file
webContents.InsertCSS(true, "styles/custom-theme.css");

// Inject CSS for BrowserView
webContents.InsertCSS(false, "styles/browser-view.css");
```

### Printing Operations

```csharp
// Print web page
var printSuccess = await webContents.PrintAsync(new PrintOptions
{
    Silent = false,
    PrintBackground = true,
    DeviceName = "My Printer"
});

if (printSuccess)
{
    Console.WriteLine("Print job sent successfully");
}
```

### PDF Generation

```csharp
// Generate PDF
var pdfSuccess = await webContents.PrintToPDFAsync("document.pdf", new PrintToPDFOptions
{
    MarginsType = PrintToPDFMarginsType.None,
    PageSize = PrintToPDFPageSize.A4,
    PrintBackground = true,
    Landscape = false
});

if (pdfSuccess)
{
    Console.WriteLine("PDF generated successfully");
}
```

### Navigation Monitoring

```csharp
// Monitor navigation events
webContents.OnDidStartNavigation += (url) =>
{
    Console.WriteLine($"Starting navigation to: {url}");
};

webContents.OnDidNavigate += (navInfo) =>
{
    Console.WriteLine($"Navigated to: {navInfo.Url}");
};

webContents.OnDidFinishLoad += () =>
{
    Console.WriteLine("Page finished loading");
};

webContents.OnDidFailLoad += (failInfo) =>
{
    Console.WriteLine($"Page failed to load: {failInfo.ErrorCode} - {failInfo.ErrorDescription}");
};
```

### Content Interaction

```csharp
// Wait for DOM ready
webContents.OnDomReady += () =>
{
    Console.WriteLine("DOM is ready");
    // Safe to execute DOM-related JavaScript now
};

// Handle page crashes
webContents.OnCrashed += (killed) =>
{
    Console.WriteLine($"Renderer crashed, killed: {killed}");
    // Optionally reload the page
};
```

### Zoom Control

```csharp
// Set the zoom to 150%
webContents.SetZoomFactor(1.5);

var factor = await webContents.GetZoomFactorAsync();
Console.WriteLine($"Current zoom: {factor * 100}%");

// Zoom levels are relative: each step is 20% larger/smaller, 0 is the original size
webContents.SetZoomLevel(2);

// Restrict pinch-to-zoom
await webContents.SetVisualZoomLevelLimitsAsync(1, 3);

// React to zoom changes triggered by the user
webContents.OnZoomChanged += (direction) =>
{
    Console.WriteLine($"User zoomed {direction}");
};
```

> **Note:** The zoom factor is shared by all windows using the same session partition. Assign a unique `WebPreferences.Partition` per window if each window should keep its own zoom.

## Related APIs

- [Electron.WindowManager](WindowManager.md) - Windows containing web contents
- [Electron.Session](Session.md) - Session management for web contents
- [Electron.IpcMain](IpcMain.md) - Communication with web contents

## Additional Resources

- [Electron WebContents Documentation](https://electronjs.org/docs/api/web-contents) - Official Electron web contents API
- [Web Content Management](../Core/What's-New.md) - Understanding web content handling
- [Security Considerations](../Using/Configuration.md) - Secure web content integration