# Use the C# workspace builder

Source: https://libtmux.org/en/csharp/latest/workspace/internals/guides/

> Parse a workspace, build it on an owned server, and handle partial failures.

Use [`WorkspaceFile.Parse`](<https://libtmux.org/en/csharp/latest/workspace/reference/libtmux-workspace-workspacefile-parse/>) to read workspace YAML and [`WorkspaceBuilder.BuildAsync`](<https://libtmux.org/en/csharp/latest/workspace/reference/libtmux-workspace-workspacebuilder-buildasync/>)
to create its session, windows, and panes. Parsing needs no running tmux server;
building requires tmux on a Unix host.

Start with the [complete workspace example](https://libtmux.org/en/csharp/latest/workspace/internals/examples/). It includes the
program, project file, dependency checkout, and run command for the .NET 10 SDK.
The example creates a private server and removes it when the owned scope ends.

## Create an isolated workspace

Parse the YAML before opening the server. Create an owned scope with
[`Server.CreateOwnedAsync`](<https://libtmux.org/en/csharp/latest/reference/libtmux-server-createownedasync/>), passing a [`ServerConnectionOptions`](<https://libtmux.org/en/csharp/latest/reference/libtmux-serverconnectionoptions/>) object with
the fresh socket name and configuration file. Pass the scope's server to
[`WorkspaceBuilder`](<https://libtmux.org/en/csharp/latest/workspace/reference/libtmux-workspace-workspacebuilder/>), then await [`BuildAsync`](<https://libtmux.org/en/csharp/latest/workspace/reference/libtmux-workspace-workspacebuilder-buildasync/>) with a cancellation token. Use
`await using` so the scope is disposed even when building throws.

The returned [`WorkspaceResult`](<https://libtmux.org/en/csharp/latest/workspace/reference/libtmux-workspace-workspaceresult/>) identifies the session and its windows.
Inspect [`Unsupported`](<https://libtmux.org/en/csharp/latest/workspace/reference/libtmux-workspace-workspaceresult-unsupported/>) for layouts that tmux rejected after creating their
windows. Keep the owned scope alive while your application uses the workspace;
disposing it removes its server and the sessions on that server.

## Read a file and handle errors

Read the YAML file as text and pass it to [`WorkspaceFile.Parse`](<https://libtmux.org/en/csharp/latest/workspace/reference/libtmux-workspace-workspacefile-parse/>).
Resolve relative working directories yourself if they
should be based on that file's location.

For an existing application server, pass its handle to [`WorkspaceBuilder`](<https://libtmux.org/en/csharp/latest/workspace/reference/libtmux-workspace-workspacebuilder/>)
instead of creating an owned scope. A failed build can leave a partial session.
Inspect [`WorkspaceBuildException.PartialResult`](<https://libtmux.org/en/csharp/latest/workspace/reference/libtmux-workspace-workspacebuildexception-partialresult/>) and decide what to remove;
the builder does not roll back changes automatically.

The [builder source](https://github.com/libtmux/libtmux-dotnet/blob/320dc64f4b8b7815842471327a5e6b84a1499bf8/src/LibTmux.Workspace/WorkspaceBuilder.cs)
describes the build result and partial-failure behavior. See
[owned server lifetime](https://github.com/libtmux/libtmux-dotnet/blob/320dc64f4b8b7815842471327a5e6b84a1499bf8/src/LibTmux/Server.Lifecycle.cs)
for scope cleanup.