docs: Rewrite Settings and Workspaces documentation

common/changes/@itwin/core-backend/nam-settings-workspace-docs_2026-04-15-20-20.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Updated TSDoc for Settings and IModelDb to reference current EditTxn APIs instead of deprecated methods.",
+      "type": "none",
+      "packageName": "@itwin/core-backend"
+    }
+  ],
+  "packageName": "@itwin/core-backend",
+  "email": "50554904+hl662@users.noreply.github.com"
+}

core/backend/src/IModelDb.ts

@@ -2259,6 +2259,7 @@ export abstract class IModelDb extends IModel {
    * @param name The name for the SettingDictionary. If a dictionary by that name already exists in the iModel, its value is replaced.
    * @param dict The SettingDictionary object to stringify and save.
    * @note All saved `SettingDictionary`s are loaded into [[workspace.settings]] every time an iModel is opened.
+   * @see [[Settings.addDictionary]] to register a dictionary for the current session only without persisting it.
    * @beta @deprecated Use EditTxn.saveSettingDictionary instead, within an explicit EditTxn scope (or via withEditTxn). See EditTxn documentation for migration help.
    */
   public saveSettingDictionary(name: string, dict: SettingsContainer) {

core/backend/src/workspace/Settings.ts

@@ -207,7 +207,7 @@ export interface SettingsDictionaryProps extends SettingsDictionarySource {
  * [[SettingGroupSchema]]s) at this time.
  *
  * iModel-specific settings are stored in the iModel's property table and loaded into [[IModelDb.workspace]] when the iModel is first opened.
- * You can add and remove a [[SettingsDictionary]] from the property table using [[IModelDb.saveSettingDictionary]] and [[IModelDb.deleteSettingDictionary]].
+ * You can add and remove a [[SettingsDictionary]] from the property table using [[EditTxn.saveSettingDictionary]] and [[EditTxn.deleteSettingDictionary]].
  *
  * iTwin-specific settings are stored in a [[CloudSqliteContainer]] in the cloud.
  * When [[IModelHost.getITwinWorkspace]] is invoked, the container is accessed using the iTwinId and the settings are loaded into the returned [[Workspace]].
@@ -256,6 +256,7 @@ export interface Settings {
 
   /** Add a new [[SettingsDictionary]] with the priority, name, and [[WorkspaceDb]] specified by `props` and setting values supplied by `settings`.
    * @note If a dictionary with the same name and [[WorkspaceDb]] already exists, it will be replaced.
+   * @note Values added via this method exist only for the current session. They are not persisted and will be lost when the host shuts down.
    * @see [[addFile]], [[addJson]], and [[addDirectory]] for convenient ways to add dictionaries from various sources.
    */
   addDictionary(props: SettingsDictionaryProps, settings: SettingsContainer): void;

docs/changehistory/5.8.0.md

@@ -100,7 +100,7 @@ Previously, settings and binary resources (fonts, textures, templates) were stor
 
 ##### Creating a local SettingsDb
 
-See [SettingsDb]($docs/learning/backend/Workspace.md#settingsdb) for full documentation.
+See [Settings containers]($docs/learning/backend/Settings.md#settings-containers) for full documentation.
 
 #### Container type convention
 

docs/changehistory/NextVersion.md

@@ -249,7 +249,7 @@ Delete it:
 
 To use iTwin-scoped settings dictionaries, configure [IModelHost.authorizationClient]($backend) and [BlobContainer.service]($backend) so the backend can query and update the iTwin settings workspace container.
 
-See the [Workspace documentation]($docs/learning/backend/Workspace.md) for full details.
+See the [Settings documentation]($docs/learning/backend/Settings.md#itwin-settings) for full details on iTwin-scoped settings and the [Workspace documentation]($docs/learning/backend/Workspace.md) for workspace resources.
 
 ## Quantity Formatting
 

docs/learning/backend/WorkspacesAndSettings.md

@@ -0,0 +1,110 @@
+# Workspaces and Settings
+
+Every non-trivial iTwin.js application needs two things at run-time: **configuration** (which tools are available, what units to use, which data sources are active) and **resources** (binary assets like fonts, textures, and templates). iTwin.js provides two complementary systems to address these needs:
+
+- **[Settings]($backend)** — a priority-ordered stack of key-value configuration pairs. Configuration flows from cloud-hosted settings containers into the active [Settings]($backend) runtime, where values can be read by name.
+- **[Workspace resources](./Workspace.md)** — versioned binary assets stored in [WorkspaceDb]($backend) containers. Settings tell the application *which* `WorkspaceDb`s to load; the application then retrieves resources from them.
+
+These two systems are deliberately separate. Settings containers are discoverable without opening an iModel. `WorkspaceDb` containers are referenced *by* settings. This separation eliminates the circular dependency that would arise if settings had to be loaded from a `WorkspaceDb` just to discover which `WorkspaceDb` to open.
+
+At runtime, settings and resources are accessed through one of three workspace scopes:
+
+| Workspace | Scope | Access |
+|---|---|---|
+| [IModelHost.appWorkspace]($backend) | Application-wide defaults and configuration | Available immediately after [IModelHost.startup]($backend) |
+| [IModelHost.getITwinWorkspace]($backend) | iTwin-scoped settings shared across all iModels in an iTwin | Requires an iTwinId; no iModel needed |
+| [IModelDb.workspace]($backend) | iModel-specific overrides; falls back to `appWorkspace` for unresolved settings. Does **not** automatically include iTwin-scoped settings | Available when an iModel is open |
+
+`appWorkspace` and `IModelDb.workspace` share the same priority stack, so iModel-level settings automatically override application defaults. `getITwinWorkspace` is independent — its settings are only available to an iModel if explicitly referenced (see [Referencing iTwin settings from an iModel](./Settings.md#referencing-itwin-settings-from-an-imodel)). See [Choosing the right workspace](./Workspace.md#choosing-the-right-workspace) for guidance on when to use each scope.
+
+## The two container types
+
+Both container types are built on [CloudSqlite]($backend) with [WorkspaceDb]($backend) as the underlying database, but they serve different roles and are discovered differently.
+
+```mermaid
+graph LR
+    subgraph CloudSqlite["CloudSqlite"]
+        direction TB
+        note["Versioned · Immutable once published<br/>Semver-based · Container-scoped"]
+    end
+
+    subgraph SettingsContainer["Settings container (containerType: &quot;settings&quot;)"]
+        SDB["<b>Settings</b><br/>Key-value config<br/>JSON dictionaries<br/>Priority-based merge"]
+    end
+
+    subgraph WorkspaceContainer["Workspace container (containerType: &quot;workspace&quot;)"]
+        WDB["<b>Resources</b><br/>Named resources<br/>Strings, blobs, files<br/>On-demand lookup"]
+    end
+
+    CloudSqlite --- SettingsContainer
+    CloudSqlite --- WorkspaceContainer
+    SDB -->|"settings point to"| WDB
+```
+
+| | **Settings container** | **Workspace container** |
+|---|---|---|
+| **Purpose** | Application configuration | Data resources |
+| **Content** | JSON key-value dictionaries | Strings, blobs, embedded files |
+| **Container type** | `"settings"` | `"workspace"` |
+| **Discovery** | Automatic via [IModelHost.getITwinWorkspace]($backend) — no iModel needed | Referenced from settings values |
+| **Resolution order** | Loaded first | Loaded second, via settings pointers |
+| **Write API** | [WorkspaceEditor]($backend) with `containerType: "settings"` | [WorkspaceEditor]($backend) |
+| **Versioning** | Semver — immutable once published | Semver — immutable once published |
+
+## How settings and resources connect
+
+At runtime the flow always starts from settings:
+
+1. **Discover and load** — call [IModelHost.getITwinWorkspace]($backend) with an iTwinId. This automatically discovers settings containers for the iTwin, loads their dictionaries into the [Settings priority stack](./Settings.md#settings-priorities), and returns a [Workspace]($backend) ready to use. No iModel is required.
+2. **Resolve resources** — read settings values that point to [WorkspaceDb]($backend) containers, then open those containers to access resources.
+
+> For advanced scenarios (admin tooling, custom discovery logic), [WorkspaceEditor.queryContainers]($backend) provides lower-level access to enumerate containers by iTwinId and `containerType`.
+
+## Scope and priority
+
+Settings from multiple sources are merged using a priority stack. A higher-priority dictionary overrides a lower-priority one for any given setting name.
+
+```mermaid
+graph TD
+    subgraph AppWorkspace["IModelHost.appWorkspace"]
+        D["defaults (100)"]
+        A["application (200)"]
+        O["organization/iTwin (400)"]
+    end
+
+    subgraph IModelWorkspace["IModelDb.workspace"]
+        B["branch (500)"]
+        M["iModel (600)"]
+    end
+
+    D -->|"overridden by"| A
+    A -->|"overridden by"| O
+    O -->|"overridden by"| B
+    B -->|"overridden by"| M
+
+    style M fill:#d4edda,stroke:#28a745
+    style D fill:#f8f9fa,stroke:#6c757d
+```
+
+In practice:
+- **Organization-wide defaults** are stored in a settings container and loaded at [SettingsPriority.iTwin]($backend) (400).
+- **iModel-specific overrides** are loaded at [SettingsPriority.iModel]($backend) (600) — iModel wins over iTwin.
+- **Application defaults** are loaded at [SettingsPriority.application]($backend) (200) — overrideable by any cloud-backed settings.
+
+> **Note:** The diagram above simplifies organization and iTwin into one level. The full priority stack includes a separate [SettingsPriority.organization]($backend) (300) level — see [Settings priorities](./Settings.md#settings-priorities) for details.
+
+`IModelHost.appWorkspace` holds dictionaries at `application` priority or lower. `IModelDb.workspace` holds higher-priority dictionaries and falls back to `appWorkspace` when a setting is not found.
+
+## Container discovery
+
+[IModelHost.getITwinWorkspace]($backend) handles settings container discovery automatically — it queries for containers tagged with `containerType: "settings"`, loads their dictionaries, and returns a ready-to-use [Workspace]($backend). Most application code does not need to interact with the discovery layer directly.
+
+[WorkspaceDb]($backend) containers (`containerType: "workspace"`) are discovered *indirectly* — by reading settings values that point to them. See [Workspace resources](./Workspace.md) for details.
+
+> For admin tooling or custom workflows, [WorkspaceEditor.queryContainers]($backend) provides direct access to enumerate containers by iTwinId and `containerType`. See [Settings containers](./Settings.md#settings-containers) for examples.
+
+## Recommended reading order
+
+1. **This overview** — understand the two systems and three workspace scopes.
+2. **[Settings](./Settings.md)** — how to define settings schemas, load dictionaries, read values, and create/manage settings containers in the cloud.
+3. **[Workspace resources](./Workspace.md)** — how to create, version, and access binary resources stored in [WorkspaceDb]($backend) containers.

docs/learning/backend/index.md

@@ -54,6 +54,11 @@ These packages provide the following functions to support backend operations:
 - Change Summary
   - [Change Summary Overview](../ChangeSummaries)
 
+- Workspaces and Settings
+  - [Workspaces and Settings overview](./WorkspacesAndSettings.md)
+  - [Settings](./Settings.md)
+  - [Workspace resources](./Workspace.md)
+
 For services and app backends:
 
 - Exposing the operations of the backend as RpcInterfaces

docs/learning/frontend/Preferences.md

@@ -2,6 +2,6 @@
 
 User preferences allow applications to persist settings across a user's sessions, where the settings can be customized by the user of the application. The preferences may be applicable for the application itself or dependent on a specific iTwin or iModel.
 
-User preferences are separate from any iTwin or iModel configuration intended to be shared across multiple users and administered by an admin rather than each individual user. See [Workspace](../backend/Workspace.md) for more details on shared workspace and settings.
+User preferences are separate from any iTwin or iModel configuration intended to be shared across multiple users and administered by an admin rather than each individual user. See [Workspaces and Settings](../backend/WorkspacesAndSettings.md) for an overview, [Settings](../backend/Settings.md) for configuration details, and [Workspace resources](../backend/Workspace.md) for binary data assets.
 
 Examples of user preferences include tool settings; recently accessed models, views, or projects; user interface state; etc.

example-code/snippets/src/backend/WorkspaceExamples.test.ts

@@ -231,7 +231,7 @@ describe("Workspace Examples", () => {
 
       // __PUBLISH_EXTRACT_START__ WorkspaceExamples.QuerySettingDictionary
       const hardinessRange = iModel.workspace.settings.getObject<HardinessRange>("landscapePro/hardinessRange");
-      // returns { minimum: 8, maximum: 10 }
+      // returns { minimum: 6, maximum: 8 }
       defaultTool = iModel.workspace.settings.getString("landscapePro/ui/defaultTool");
       // returns "place-koi-pond" as specified by IModelHost.appWorkspace.settings.
       // __PUBLISH_EXTRACT_END__
@@ -262,18 +262,18 @@ describe("Workspace Examples", () => {
       // __PUBLISH_EXTRACT_START__ WorkspaceExamples.GetITwinWorkspace
       const iTwinWorkspace = await IModelHost.getITwinWorkspace(iTwinId);
       const defaultView = iTwinWorkspace.settings.getString("myApp/defaultView");
+      iTwinWorkspace.close();
       // __PUBLISH_EXTRACT_END__
       expect(defaultView).to.equal("plan");
 
       // __PUBLISH_EXTRACT_START__ WorkspaceExamples.ReadITwinSettings
       const workspace = await IModelHost.getITwinWorkspace(iTwinId);
       const defaultViewFromRead = workspace.settings.getString("myApp/defaultView");
       const maxItems = workspace.settings.getNumber("myApp/maxDisplayedItems");
+      workspace.close();
       // __PUBLISH_EXTRACT_END__
       expect(defaultViewFromRead).to.equal("plan");
       expect(maxItems).to.equal(100);
-      iTwinWorkspace.close();
-      workspace.close();
 
       // __PUBLISH_EXTRACT_START__ WorkspaceExamples.DeleteITwinSetting
       await IModelHost.deleteSettingDictionary(iTwinId, "myApp/settings");
@@ -431,6 +431,7 @@ describe("Workspace Examples", () => {
 
       const workspaceForTreeDbs = await IModelHost.getITwinWorkspace(iTwinId);
       const workspaceTreeDbs = await workspaceForTreeDbs.getWorkspaceDbs({ settingName: "landscapePro/flora/treeDbs" });
+      workspaceForTreeDbs.close();
       // __PUBLISH_EXTRACT_END__
       expect(workspaceTreeDbs.length).to.equal(2);
 
@@ -536,6 +537,7 @@ describe("Workspace Examples", () => {
       await withEditTxn(iModel, async (txn) => txn.saveSettingDictionary("landscapePro/iModelSettings", {
         "landscapePro/itwinSettingsRef": settingsSourcesForModelRef,
       }));
+      iTwinWorkspaceForModelRef.close();
       // __PUBLISH_EXTRACT_END__
 
       // __PUBLISH_EXTRACT_START__ WorkspaceExamples.OverrideITwinSettingAtIModelLevel
@@ -567,6 +569,85 @@ describe("Workspace Examples", () => {
       // __PUBLISH_EXTRACT_END__
     });
 
+    it("SettingsDb discover, find, create, update, and read", async () => {
+      IModelHost.authorizationClient = new AzuriteTest.AuthorizationClient();
+      AzuriteTest.userToken = AzuriteTest.service.userToken.admin;
+      const iTwinId = Guid.createValue();
+
+      // __PUBLISH_EXTRACT_START__ SettingsContainer.discoverContainers
+      // Query the BlobContainer service for settings containers associated with an iTwin.
+      const containerMetadata = await WorkspaceEditor.queryContainers({ iTwinId, containerType: "settings" });
+      // Each entry includes a containerId and label that can be displayed in an admin UI.
+      for (const entry of containerMetadata) {
+        console.log(`Container: ${entry.containerId}, label: ${entry.label}`); // eslint-disable-line no-console
+      }
+      // __PUBLISH_EXTRACT_END__
+      expect(containerMetadata).to.be.an("array");
+
+      // __PUBLISH_EXTRACT_START__ SettingsContainer.findContainers
+      // Find and open settings containers for a given iTwin in a single call.
+      // This queries the BlobContainer service for settings containers matching the iTwinId,
+      // requests write access tokens, and opens each matching container.
+      const settingsEditor = WorkspaceEditor.construct();
+      const settingsContainers = await settingsEditor.findContainers({ iTwinId, containerType: "settings" });
+      expect(settingsContainers).to.not.be.undefined;
+      // __PUBLISH_EXTRACT_END__
+      settingsEditor.close();
+
+      // __PUBLISH_EXTRACT_START__ SettingsContainer.createLocal
+      // Create a new cloud container for settings, write initial values, and publish them.
+      const editor = WorkspaceEditor.construct();
+      const container: EditableWorkspaceContainer = await editor.createNewCloudContainer({
+        metadata: { label: "Project Settings", description: "Settings for this iTwin" },
+        scope: { iTwinId },
+        manifest: { workspaceName: "settings", description: "iTwin settings container" },
+      });
+
+      // Acquire the write lock — only one user can hold it at a time.
+      container.acquireWriteLock("admin");
+
+      // Open an editable WorkspaceDb inside the container.
+      const settingsDb = container.getEditableDb({});
+
+      // Write settings as a named resource.
+      const settings: SettingsContainer = {
+        "myApp/theme": "dark",
+        "myApp/maxItems": 50,
+      };
+      settingsDb.updateSettingsResource(settings);
+
+      // Release the lock to publish the changes.
+      container.releaseWriteLock();
+      editor.close();
+      // __PUBLISH_EXTRACT_END__
+
+      // Re-open for update and read tests
+      const editor2 = WorkspaceEditor.construct();
+      const containers2 = await editor2.findContainers({ iTwinId, containerType: "settings" });
+      const container2 = containers2[0];
+
+      // __PUBLISH_EXTRACT_START__ SettingsContainer.updateSetting
+      // Update a single setting without affecting others.
+      // Acquire the write lock, read existing settings, change one entry, and publish.
+      await container2.withEditableDb("admin", (db) => {
+        const current = JSON.parse(db.getString("settingsDictionary") ?? "{}") as SettingsContainer;
+        current["myApp/maxItems"] = 100;
+        db.updateSettingsResource(current);
+      });
+      // __PUBLISH_EXTRACT_END__
+
+      // __PUBLISH_EXTRACT_START__ SettingsContainer.getSettings
+      // Read all settings stored in a settings container.
+      const readDb: WorkspaceDb = container2.getEditableDb({});
+      const raw = readDb.getString("settingsDictionary");
+      const allSettings = raw ? JSON.parse(raw) as SettingsContainer : {};
+      // __PUBLISH_EXTRACT_END__
+      expect(allSettings["myApp/maxItems"]).to.equal(100);
+      expect(allSettings["myApp/theme"]).to.equal("dark");
+
+      editor2.close();
+    });
+
     it("Find and open a workspace container by iTwinId", async () => {
       IModelHost.authorizationClient = new AzuriteTest.AuthorizationClient();
       AzuriteTest.userToken = AzuriteTest.service.userToken.admin;