Skip to main content

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 Alpha readonly AttachState Indicates the attachment state of the container to a host service.
audience Alpha readonly IAudience The audience information for all clients currently associated with the document in the current session.
clientId Alpha optional, readonly string | undefined

The server provided ID of the client.

Set once connectionState is Connected, otherwise will be undefined.
closed Alpha readonly boolean Returns true if the container has been closed and/or disposed, otherwise false.
connectionState Alpha readonly ConnectionState Provides the current state of the container's connection to the ordering service.
containerMetadata Alpha 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 Alpha IDeltaManager<ISequencedDocumentMessage, IDocumentMessage> The Delta Manager supporting the op stream for this Container
disposed Alpha optional, readonly boolean Returns true if the container has been disposed, otherwise false.
isDirty Alpha readonly boolean Whether or not there are any local changes that have not been saved.
readOnlyInfo Alpha readonly ReadOnlyInfo Tells if container is in read-only mode.
resolvedUrl Alpha 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) Alpha 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) Alpha void Closes the container.
connect() Alpha void Attempts to connect the container to the delta stream and process ops.
disconnect() Alpha void Disconnects the container from the delta stream and stops processing ops.
dispose(error) Alpha 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) Alpha optional any Allows the host to have the container force to be in read-only mode
getAbsoluteUrl(relativeUrl) Alpha 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() Alpha 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() Alpha IFluidCodeDetails | undefined Get the code details that were used to load the container.
getQuorum() Alpha 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() Alpha IFluidCodeDetails | undefined Get the code details that are currently specified for the container.
proposeCodeDetails(codeDetails) Alpha 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() Alpha 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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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 as an alpha preview and may change without notice.

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

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