IContainer Interface

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

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/container-definitions/legacy.

For more information about our API support guarantees, see here.

Signature

export interface IContainer extends IEventProvider<IContainerEvents>

Extends: IEventProvider<IContainerEvents>

Properties

Property	Alerts	Modifiers	Type	Description
attachState	Beta	readonly	AttachState	Indicates the attachment state of the container to a host service.
audience	Beta	readonly	IAudience	The audience information for all clients currently associated with the document in the current session.
clientId	Beta	optional, readonly	string | undefined	The server provided ID of the client. Set once connectionState is Connected, otherwise will be undefined.
closed	Beta	readonly	boolean	Returns true if the container has been closed and/or disposed, otherwise false.
connectionState	Beta	readonly	ConnectionState	Provides the current state of the container's connection to the ordering service.
containerMetadata	Beta		Record<string, string>	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.
deltaManager	Beta		IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>	The Delta Manager supporting the op stream for this Container
disposed	Beta	optional, readonly	boolean	Returns true if the container has been disposed, otherwise false.
isDirty	Beta	readonly	boolean	Whether or not there are any local changes that have not been saved.
readOnlyInfo	Beta	readonly	ReadOnlyInfo	Tells if container is in read-only mode.
resolvedUrl	Beta		IResolvedUrl | undefined	Represents the resolved url to the Container. Will be undefined only when the container is in the detached state.

Methods

Method	Alerts	Modifiers	Return Type	Description
attach(request, attachProps)	Beta		Promise<void>	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.
close(error)	Beta		void	Closes the container.
connect()	Beta		void	Attempts to connect the container to the delta stream and process ops.
disconnect()	Beta		void	Disconnects the container from the delta stream and stops processing ops.
dispose(error)	Beta		void	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.
forceReadonly(readonly)	Beta	optional	any	Allows the host to have the container force to be in read-only mode
getAbsoluteUrl(relativeUrl)	Beta		Promise<string | undefined>	Get an absolute URL for a provided container-relative request URL. If the container is not attached, this will return undefined.
getEntryPoint()	Beta		Promise<FluidObject>	Exposes the entryPoint for the container. Use this as the primary way of getting access to the user-defined logic within the container.
getLoadedCodeDetails()	Beta		IFluidCodeDetails | undefined	Get the code details that were used to load the container.
getQuorum()	Beta		IQuorumClients	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.
getSpecifiedCodeDetails()	Beta		IFluidCodeDetails | undefined	Get the code details that are currently specified for the container.
proposeCodeDetails(codeDetails)	Beta		Promise<boolean>	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.
serialize()	Beta		string	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.

Property Details

attachState

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

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly attachState: AttachState;

Type: AttachState

audience

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

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly audience: IAudience;

Type: IAudience

clientId

The server provided ID of the client.

Set once connectionState is Connected, otherwise will be undefined.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly clientId?: string | undefined;

Type: string | undefined

closed

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

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly closed: boolean;

Type: boolean

connectionState

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

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

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.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

containerMetadata: Record<string, string>;

Type: Record<string, string>

deltaManager

The Delta Manager supporting the op stream for this Container

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;

Type: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>

disposed

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

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly disposed?: boolean;

Type: boolean

isDirty

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

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly isDirty: boolean;

Type: boolean

readOnlyInfo

Tells if container is in read-only mode.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

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.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

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.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

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

Parameters

Parameter	Modifiers	Type	Description
request		IRequest
attachProps	optional	{ deltaConnection?: "none" | "delayed"; }

Returns

Return type: Promise<void>

close

Closes the container.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

close(error?: ICriticalContainerError): void;

Parameters

Parameter	Modifiers	Type	Description
error	optional	ICriticalContainerError	If the container is being closed due to error, this provides details about the error that resulted in closing it.

connect

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

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

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.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

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.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

dispose(error?: ICriticalContainerError): void;

Parameters

Parameter	Modifiers	Type	Description
error	optional	ICriticalContainerError	If the container is being disposed due to error, this provides details about the error that resulted in disposing it.

forceReadonly

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

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

forceReadonly?(readonly: boolean): any;

Parameters

Parameter	Type	Description
readonly	boolean	Boolean that toggles if read-only policies will be enforced

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.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

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

Parameters

Parameter	Type	Description
relativeUrl	string	A container-relative request URL.

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.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

getEntryPoint(): Promise<FluidObject>;

Returns

Return type: Promise<FluidObject>

getLoadedCodeDetails

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

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

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.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

getQuorum(): IQuorumClients;

Returns

Return type: IQuorumClients

getSpecifiedCodeDetails

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

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

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.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

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

Parameters

Parameter	Type	Description
codeDetails	IFluidCodeDetails

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.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

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