> ## Documentation Index
> Fetch the complete documentation index at: https://docs.foveus.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Dotnet

Use the Foveus .NET SDK to connect your .NET service to Foveus.

The SDK captures execution telemetry from your application and sends it to your Foveus workspace.

For an ASP.NET Core API, this usually means capturing one execution per HTTP request.

For workers and background services, Foveus can capture logs, exceptions, outbound HTTP telemetry, metrics, and trace propagation.

## Install the SDK

Install the package in your service.

```bash theme={null}
dotnet add package Foveus.SDK
```

<Note>
  During private beta, your package name or package source may be different. Use the package name and feed URL provided during onboarding.
</Note>

## Minimal setup

For most services, start with your test API key.

```csharp theme={null}
builder.Services.AddFoveus("fov_test_...");
```

Then add the middleware for ASP.NET Core APIs.

```csharp theme={null}
app.UseFoveus();
```

With this setup, Foveus uses safe defaults:

| Option        | Default                 |
| ------------- | ----------------------- |
| `ServiceName` | Project assembly name   |
| `Environment` | Current app environment |
| `Mode`        | `test`                  |

You can override these values later.

## Configuration-based setup

For most real applications, load configuration from `appsettings.json`, environment variables, or your secret manager.

```csharp theme={null}
builder.Services.AddFoveus(builder.Configuration);
```

Example configuration:

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_..."
  }
}
```

Override defaults when needed:

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ServiceName": "orders-api",
    "Environment": "staging"
  }
}
```

For production telemetry, use a live key and set `Mode` to `live`.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "ServiceName": "orders-api",
    "Environment": "production",
    "Mode": "live"
  }
}
```

## What the SDK captures

The exact data depends on your configuration and application type.

The SDK can capture:

* HTTP executions
* endpoint and method
* request query values
* request body context
* response body context
* execution duration
* outcome and failure evidence
* exception context
* logs, if logging integration is configured
* outbound HTTP telemetry
* metrics
* SDK health and performance signals

## HTTP executions

For ASP.NET Core APIs, the middleware captures requests as executions.

```csharp theme={null}
app.UseFoveus();
```

A request such as:

```text theme={null}
POST /orders
```

can appear in Foveus as an execution with:

* service name
* environment
* mode
* endpoint
* method
* duration
* status
* request context
* response context
* logs, if configured

## Worker services

Foveus can also be used in `.NET Worker Service` and `BackgroundService` apps.

Worker services use `builder.Services.AddFoveus(...)`, but they do not call `app.UseFoveus()` because workers do not have an ASP.NET HTTP middleware pipeline.

Basic worker setup:

```csharp theme={null}
var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddFoveus(builder.Configuration);

builder.Services.AddHostedService<Worker>();

var host = builder.Build();

await host.RunAsync();
```

Example configuration:

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ServiceName": "billing-worker",
    "Source": "worker"
  }
}
```

For worker services, Foveus can capture:

* `ILogger` logs
* logged exceptions
* outbound HTTP telemetry
* metrics
* trace propagation
* SDK shutdown flushing
* supported messaging instrumentation hooks

Full automatic per-job execution capture for arbitrary `BackgroundService` loops is not yet implemented.

See [Worker services](/sdk/worker-services).

## Request and response context

Foveus can capture structured request and response context.

For example, if your response includes:

```json theme={null}
{
  "orderStatus": {
    "value": 1,
    "label": "Confirmed"
  }
}
```

Foveus can index safe scalar fields for search.

```text theme={null}
service:orders-api context:orderStatus.value=1
```

Or:

```text theme={null}
service:orders-api context:orderStatus.label="Confirmed"
```

Strings should use quotes. Numbers and booleans do not need quotes.

<Note>
  Execution Context Search uses indexed context fields. It does not scan arbitrary raw request or response bodies.
</Note>

## Logs

If logging integration is enabled, Foveus can correlate logs with executions.

This helps you inspect logs for one request or operation instead of searching through unrelated log streams.

If your service uses Serilog, use the dedicated Serilog integration.

See [Serilog integration](/sdk/serilog).

## Capture profiles

Use `CaptureProfile` to tune how much telemetry the SDK captures.

| Profile          | Use for                                        |
| ---------------- | ---------------------------------------------- |
| `Balanced`       | Normal production usage.                       |
| `Debug`          | Local development or deep troubleshooting.     |
| `HighThroughput` | Busy services where low overhead matters most. |

Example:

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "CaptureProfile": "Balanced"
  }
}
```

## Redaction and safety

Foveus applies redaction and safety controls before storing or indexing context.

You can add domain-specific redacted fields.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "RedactedFields": ["nationalId", "accountNumber"]
  }
}
```

Sensitive values such as passwords, tokens, authorization headers, cookies, secrets, and card values should not be stored or indexed.

<Warning>
  Redaction is a safety layer. Do not intentionally send secrets, credentials, card data, or highly sensitive personal data to Foveus.
</Warning>

## Performance controls

The SDK is designed to keep overhead bounded.

You can tune:

* capture profile
* context sampling
* request and response body capture
* maximum body size
* path exclusions
* batch size
* batch interval
* retry settings
* queue size

For high-volume services, use `HighThroughput` or lower the sampling rate.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "CaptureProfile": "HighThroughput",
    "ContextSamplingRate": 0.001,
    "ExcludedPathPrefixes": ["/health", "/metrics"]
  }
}
```

## Common setup

### Local development

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_..."
  }
}
```

Foveus uses Test mode by default.

### Staging

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ServiceName": "orders-api",
    "Environment": "staging"
  }
}
```

### Production API

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "ServiceName": "orders-api",
    "Environment": "production",
    "Mode": "live",
    "CaptureProfile": "Balanced",
    "ExcludedPathPrefixes": ["/health", "/metrics"]
  }
}
```

### Production worker

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "ServiceName": "billing-worker",
    "Environment": "production",
    "Mode": "live",
    "Source": "worker",
    "CaptureProfile": "Balanced"
  }
}
```

## Troubleshooting

### No executions appear

Check that:

* the API key is configured
* the service can reach Foveus
* `app.UseFoveus()` is registered for ASP.NET Core APIs
* the dashboard is showing the right mode
* the time range includes the request
* your service name matches your search

### Worker logs appear, but jobs do not show as executions

That is expected for arbitrary `BackgroundService` loops today.

Foveus can capture worker logs, exceptions, outbound HTTP telemetry, metrics, and trace propagation, but full automatic per-job execution capture is still evolving.

Use structured lifecycle logs or supported messaging instrumentation.

### The service name looks wrong

If you did not set `ServiceName`, Foveus uses your project assembly name.

Override it if needed.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ServiceName": "orders-api"
  }
}
```

### Response context is missing

Check that:

* response body capture is enabled
* the response body is within the capture size limit
* the route is not excluded
* sampling did not skip the context snapshot
* redaction did not mask the field

### Too much context is being captured

Use:

* `ExcludedPathPrefixes`
* `ExcludedExactPaths`
* lower `ContextSamplingRate`
* `CaptureProfile: "HighThroughput"`
* lower body capture settings

## Next steps

* Configure the SDK: [SDK configuration](/sdk/configuration)
* Set up worker services: [Worker services](/sdk/worker-services)
* Review all options: [FoveusOptions](/sdk/foveus-options)
* Configure Serilog: [Serilog integration](/sdk/serilog)
* Configure redaction: [Redaction](/sdk/redaction)
* Review performance overhead: [Performance overhead](/sdk/performance-overhead)
* Send your first execution: [Send your first execution](/get-started/send-first-execution)