# IAttachmentStore

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.iattachmentstore/
> Summary: IAttachmentStore: The contract for attachment metadata and for the default (database) content storage.

<div class="api-provenance">Namespace Tracon · Assembly <code>Tracon.Abstractions.dll</code></div>

The contract for attachment metadata and for the default (database) content storage.

```csharp
public interface IAttachmentStore
```

## Remarks

When [IAttachmentStorage](/api/tracon.iattachmentstorage/) is registered the content lives there and this
store keeps the metadata only; when it is not registered the content is stored
directly in the database (`bytea`).

**DI lifetime — singleton.** Registered as a singleton with
`TryAdd`; a consumer's own registration wins.

## Methods

### <a id="Tracon_IAttachmentStore_DeleteAsync_System_String_System_Guid_System_Threading_CancellationToken_"></a> DeleteAsync\(string, Guid, CancellationToken\)

Deletes an attachment.

```csharp
ValueTask<bool> DeleteAsync(string tenantId, Guid id, CancellationToken cancellationToken = default)
```

#### Parameters

`tenantId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The tenant id.

`id` [Guid](https://learn.microsoft.com/dotnet/api/system.guid)

The attachment id.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[bool](https://learn.microsoft.com/dotnet/api/system.boolean)\>

[true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) when a record was deleted.

#### Remarks

When the content lives in [IAttachmentStorage](/api/tracon.iattachmentstorage/), the content is
deleted first and the record second. If the content delete throws, the
record stays and the exception propagates: the record is the only place
that says where the content is, so a retry can still find it.

### <a id="Tracon_IAttachmentStore_DeleteBySessionAsync_System_String_System_String_System_Threading_CancellationToken_"></a> DeleteBySessionAsync\(string, string, CancellationToken\)

Deletes every attachment of a session.

```csharp
ValueTask<int> DeleteBySessionAsync(string tenantId, string sessionId, CancellationToken cancellationToken = default)
```

#### Parameters

`tenantId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The tenant id.

`sessionId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The session id.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[int](https://learn.microsoft.com/dotnet/api/system.int32)\>

The number of records deleted.

#### Remarks

It is called when a session is deleted; it keeps orphaned attachments from piling
up.

Each attachment follows the order of [IAttachmentStore.DeleteAsync](/api/tracon.iattachmentstore/#Tracon_IAttachmentStore_DeleteAsync_System_String_System_Guid_System_Threading_CancellationToken_): content first,
record second. The first content delete that throws stops the call; that
record and every record not yet reached stay, so a retry deletes the rest.

### <a id="Tracon_IAttachmentStore_GetAsync_System_String_System_Guid_System_Threading_CancellationToken_"></a> GetAsync\(string, Guid, CancellationToken\)

Reads the metadata of a single attachment.

```csharp
ValueTask<AttachmentDescriptor?> GetAsync(string tenantId, Guid id, CancellationToken cancellationToken = default)
```

#### Parameters

`tenantId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The tenant id.

`id` [Guid](https://learn.microsoft.com/dotnet/api/system.guid)

The attachment id.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[AttachmentDescriptor](/api/tracon.attachmentdescriptor/)?\>

The record, or [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) when it does not exist or belongs to another tenant.

### <a id="Tracon_IAttachmentStore_ListAsync_Tracon_AttachmentQuery_System_Threading_CancellationToken_"></a> ListAsync\(AttachmentQuery, CancellationToken\)

Lists the attachments through a filter.

```csharp
ValueTask<IReadOnlyList<AttachmentDescriptor>> ListAsync(AttachmentQuery query, CancellationToken cancellationToken = default)
```

#### Parameters

`query` [AttachmentQuery](/api/tracon.attachmentquery/)

The filter.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[AttachmentDescriptor](/api/tracon.attachmentdescriptor/)\>\>

The records ordered from newest to oldest.

### <a id="Tracon_IAttachmentStore_OpenReadAsync_System_String_System_Guid_System_Threading_CancellationToken_"></a> OpenReadAsync\(string, Guid, CancellationToken\)

Opens the raw content of an attachment as a stream.

```csharp
ValueTask<Stream?> OpenReadAsync(string tenantId, Guid id, CancellationToken cancellationToken = default)
```

#### Parameters

`tenantId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The tenant id.

`id` [Guid](https://learn.microsoft.com/dotnet/api/system.guid)

The attachment id.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[Stream](https://learn.microsoft.com/dotnet/api/system.io.stream)?\>

A readable stream, or [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) when the record does not exist or
belongs to another tenant.

#### Remarks

**Stream ownership.** The CALLER owns the returned stream and must
dispose it; this store does not dispose it and does not keep a reference to it
after returning.

### <a id="Tracon_IAttachmentStore_SaveAsync_Tracon_AttachmentContent_System_Threading_CancellationToken_"></a> SaveAsync\(AttachmentContent, CancellationToken\)

Saves a new attachment.

```csharp
ValueTask<AttachmentDescriptor> SaveAsync(AttachmentContent content, CancellationToken cancellationToken = default)
```

#### Parameters

`content` [AttachmentContent](/api/tracon.attachmentcontent/)

The content and metadata to save.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[AttachmentDescriptor](/api/tracon.attachmentdescriptor/)\>

The attachment record with its id and digest assigned.