Example applications

Choose by the result you need#

Path 1: the .NET-first stack#

Run one command from the repository root:

dotnet run --project examples/SqlOS.Todo.AppHost/SqlOS.Todo.AppHost.csproj

This starts a persistent SQL Server container, the Todo API and embedded SqlOS host at http://localhost:5080, and the Razor Pages client at http://localhost:5090. Aspire reports resource health at its authenticated https://localhost:18890 dashboard.

The browser journey is deliberately ordinary ASP.NET Core:

1. the application issues an authentication challenge;
2. the generic OAuth handler creates protected state, a correlation cookie, and PKCE material;
3. SqlOS hosts user and organization sign-in;
4. middleware owns the /signin-sqlos callback and code exchange;
5. the application calls protected /api/me and creates its encrypted cookie;
6. logout revokes the remote refresh token and session, then removes the local cookie.

Read the ASP.NET Core sample guide on GitHub for the source tour, security decisions, and troubleshooting.

Path 2: compare application architectures#

The full stack adds the broader example API, Next.js, and Angular:

npm ci --prefix examples/SqlOS.Example.Web
npm ci --prefix examples/SqlOS.Example.AngularWeb
dotnet run --project examples/SqlOS.Example.AppHost/SqlOS.Example.AppHost.csproj

Use it to compare a server-rendered .NET client with hosted and headless browser flows, optional social/OTP providers, multi-client registration, retail resource hierarchies, and identity-dependent EF results.

For the source-guided browser implementation, follow Build your own login and signup UI, then compare its focused flow with the complete Next.js and Angular clients below.

The AppHost starts these user-facing surfaces:

The authenticated Aspire dashboard URL is printed at startup; its configured listener is https://localhost:18888.

Complete catalog#

The root example catalog documents every project, port, provider setting, persistence rule, and test command.

What the examples intentionally do not hide#

• Password sign-in works without a third-party provider. Email, phone, social, and calendar flows require the provider settings named in each README.
• AppHost SQL data persists between runs. A stale user, client, or grant may be database state rather than a seeding failure.
• The ASP.NET Core sample stores tokens in its encrypted authentication ticket for teaching clarity; larger deployments should consider a server-side ITicketStore.
• Expo is not launched by Aspire and needs simulator/device callback and network configuration.
• Backend protocol and authorization paths have real-SQL integration tests. The JavaScript client builds are checked, but the repository does not currently claim browser-automation coverage for every frontend journey.

Those boundaries are part of the reference implementation. They tell you which code is a trustworthy integration contract and which choices you still need to make for your own deployment.

Verify before you copy#

dotnet build SqlOS.sln
dotnet test examples/SqlOS.Example.Tests/SqlOS.Example.Tests.csproj
dotnet test examples/SqlOS.Todo.IntegrationTests/SqlOS.Todo.IntegrationTests.csproj
dotnet test examples/SqlOS.Example.IntegrationTests/SqlOS.Example.IntegrationTests.csproj

Continue with production readiness before adapting a local callback, cookie, secret, key ring, or persistent sample database to a deployed environment.