IContainer Interface

Packages > @fluidframework/container-definitions > IContainer

The Host’s view of a Container and its connection to storage

Signature

export interface IContainer extends IEventProvider<IContainerEvents>

Extends: IEventProvider <IContainerEvents >

Properties

Methods

Property Details

attachState

Indicates the attachment state of the container to a host service.

Signature

readonly attachState: AttachState;

Type: AttachState

audience

The audience information for all clients currently associated with the document in the current session.

Signature

readonly audience: IAudience;

Type: IAudience

clientId

The server provided ID of the client.

Set once connectionState is Connected , otherwise will be undefined.

Signature

readonly clientId?: string | undefined;

Type: string | undefined

closed

Returns true if the container has been closed and/or disposed, otherwise false.

Signature

readonly closed: boolean;

Type: boolean

connectionState

Provides the current state of the container’s connection to the ordering service.

Signature

readonly connectionState: ConnectionState;

Type: ConnectionState

Remarks

Consumers can listen for state changes via the “connected” and “disconnected” events.

containerMetadata

Exposes any metadata/props related to the container. This is full set of metadata props which the container wants to expose. Whenever container receives updates from IContainerEvents.metadataUpdate event, we overwrite only those updated props in the update and rest remains the same.

Signature

containerMetadata: Record<string, string>;

Type: Record<string, string>

deltaManager

The Delta Manager supporting the op stream for this Container

Signature

deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;

Type: IDeltaManager <ISequencedDocumentMessage , IDocumentMessage >

disposed

Returns true if the container has been disposed, otherwise false.

Signature

readonly disposed?: boolean;

Type: boolean

isDirty

Whether or not there are any local changes that have not been saved.

Signature

readonly isDirty: boolean;

Type: boolean

readOnlyInfo

Tells if container is in read-only mode.

Signature

readonly readOnlyInfo: ReadOnlyInfo;

Type: ReadOnlyInfo

Remarks

Data stores should listen for “readonly” notifications and disallow user making changes to data stores. Readonly state can be because of no storage write permission, or due to host forcing readonly mode for container.

We do not differentiate here between no write access to storage vs. host disallowing changes to container - in all cases container runtime and data stores should respect readonly state and not allow local changes.

It is undefined if we have not yet established websocket connection and do not know if user has write access to a file.

resolvedUrl

Represents the resolved url to the Container. Will be undefined only when the container is in the detached state.

Signature

resolvedUrl: IResolvedUrl | undefined;

Type: IResolvedUrl | undefined

Method Details

attach

When a container is created in Fluid it starts in detached state, which means it is not yet uploaded to server storage and unavailable for other users to open or collaborate with. A detached container can be serialized, stored, and rehydrated by the application.

To finish the creation of a container and make it available for other users to open and collaborate with it must be attached, which means it is uploaded to server storage. This function accomplishes that.

Use the functionality provided by the driver to craft the IRequest parameter. This is usually a free function called createCreateNewRequest, which takes strongly typed arguments related to your driver and server.

By default, the container will close if attach fails. However, closure can now be avoided in most cased by setting: Fluid.Container.RetryOnAttachFailure to true via the config provider passed to the loader.

If attach fails, check the closed property to discover if retry is possible. If the container is not closed, it is safe to continue editing the container, calling serialize to capture the container’s state, or try calling attach again.

Signature

attach(request: IRequest, attachProps?: {
        deltaConnection?: "none" | "delayed";
    }): Promise<void>;

Parameters

Returns

Return type: Promise<void>

close

Closes the container.

Signature

close(error?: ICriticalContainerError): void;

Parameters

connect

Attempts to connect the container to the delta stream and process ops.

Signature

connect(): void;

Remarks

connectionState will be set to Connected , and the “connected” event will be fired if/when connection succeeds.

disconnect

Disconnects the container from the delta stream and stops processing ops.

Signature

disconnect(): void;

Remarks

connectionState will be set to Disconnected , and the “disconnected” event will be fired when disconnection completes.

dispose

Disposes the container. If not already closed, this acts as a closure and then disposes runtime resources. The container is not expected to be used anymore once it is disposed.

Signature

dispose(error?: ICriticalContainerError): void;

Parameters

forceReadonly

Allows the host to have the container force to be in read-only mode

Signature

forceReadonly?(readonly: boolean): any;

Parameters

Returns

Return type: any

getAbsoluteUrl

Get an absolute URL for a provided container-relative request URL. If the container is not attached, this will return undefined.

Signature

getAbsoluteUrl(relativeUrl: string): Promise<string | undefined>;

Parameters

Returns

Return type: Promise<string | undefined>

getEntryPoint

Exposes the entryPoint for the container. Use this as the primary way of getting access to the user-defined logic within the container.

Signature

getEntryPoint(): Promise<FluidObject>;

Returns

Return type: Promise<FluidObject >

getLoadedCodeDetails

Get the code details that were used to load the container.

Signature

getLoadedCodeDetails(): IFluidCodeDetails | undefined;

Returns

The code details that were used to load the container if it is loaded, undefined if it is not yet loaded.

Return type: IFluidCodeDetails | undefined

getQuorum

The collection of write clients which were connected as of the current sequence number. Also contains a map of key-value pairs that must be agreed upon by all clients before being accepted.

Signature

getQuorum(): IQuorumClients;

Returns

Return type: IQuorumClients

getSpecifiedCodeDetails

Get the code details that are currently specified for the container.

Signature

getSpecifiedCodeDetails(): IFluidCodeDetails | undefined;

Returns

The current code details if any are specified, undefined if none are specified.

Return type: IFluidCodeDetails | undefined

proposeCodeDetails

Propose new code details that define the code to be loaded for this container’s runtime.

The returned promise will be true when the proposal is accepted, and false if the proposal is rejected.

Signature

proposeCodeDetails(codeDetails: IFluidCodeDetails): Promise<boolean>;

Parameters

Returns

Return type: Promise<boolean>

serialize

Capture the state of a container that is not attached or closed. This is useful in draft-like scenarios. For example, think of an email draft, where a user can make changes over time, but no other users can see or have access to that draft.

This method can only be called when the container’s closed property is false, and the attachState is not AttachState.Attached.

This method will return a string that includes the full serialized state of the container. This string must not be inspected or modified, as the format of the content is not guaranteed.

Signature

serialize(): string;

Remarks

Fluid supports rehydrating from strings generated by previous versions, but does not support the content itself being leveraged.

Consider storing this string somewhere durable (e.g. localStorage or IndexedDB) to enable your application to recover it after tab close.

To reload a container from a string your application previously stored, use the Loader method rehydrateDetachedContainerFromSnapshot. That method will create a new detached container which matches the state of the previously serialized container.

Returns

Return type: string