Skip to content
| Marketplace
Sign in
Visual Studio Code>Programming Languages>Smart AssistNew to Visual Studio Code? Get it now.
Smart Assist

Smart Assist

Smart Assist

|
4 installs
| (1) | Free
Build, run, debug, validate, pack and install Smart Assist modules: a thin shell over the sa CLI.
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

Smart Assist for VS Code

Build, run, debug, validate, pack and install Smart Assist modules from VS Code. The extension is a thin shell over the sa CLI (ARCHITECTURE.md 13.3), so it does exactly what sa does on the command line and in CI. The framework itself is described in the repository's README and CONTRIBUTING; modules are explained in docs/sdk/GETTING_STARTED.md.

Install

What you need: VS Code 1.100 or newer, the .NET 9 SDK and, for debugging, the C# extension (ms-dotnettools.csharp).

code --install-extension extensions/vscode/smart-assist.vsix  # this extension

Build the .vsix yourself:

cd extensions/vscode
# Check out the revision in devhost-source.json at the repository root as .devhost-source
# (or set SA_DEV_HOST_SOURCE to that checkout). CI performs this checkout automatically.
npm ci
npm run package          # smart-assist.vsix (copies SmartAssist.UI's gallery, CSS and JS into media/ui first)

The VSIX includes its matching CLI and a portable development host. Leave smartAssist.cliPath and smartAssist.hostDir empty for the default setup. Module authors need the .NET 9 SDK; they do not need the Smart Assist source, a separate host installation, or GitHub credentials. Explicit CLI and host overrides remain supported. The development bundle omits the built-in tutorial-video library; module-owned assets are loaded from their own packages as usual.

The editor-extensions workflow builds the .vsix and publishes it to GitHub Releases for vscode/v* tags. After merging an extension PR into extension/vscode, push vscode/v<package-version> at that component commit and let the GitHub Action publish the release. Do not create a VSIX release or upload its assets manually.

Development uses the permanent extension/vscode branch. Create feature branches from it and target it in extension PRs; use main only for a necessary shared framework change.

Workspace modules and publishing

Workspace modules automatically lists Smart Assist projects in the open workspace/solution. It refreshes when projects, module source or workspace folders change. Add or open a module lists those projects first, followed by Browse for another module and Create a new module. Closing the active module leaves the workspace list available. Discovery reads project/source files with bounded concurrency and skips build, dependency and test folders.

Use Signing and Marketplace → Open signing key to select an Ed25519 private key file (base64, as produced by sa keygen) or an Azure Key Vault secret. Enter the publisher ID and signing key ID registered in your marketplace account. Copy the public key from this section to register it with that publisher. Key Vault uses the CLI's Azure credentials. The extension stores the selected location and public metadata in VS Code SecretStorage; the CLI reads the private value for signing.

Publish module to Marketplace opens an editor tab. Choose the next version and marketplace HTTPS address, save your module documents, then select Build, sign and verify. This updates the project version, stops its local dev host, builds the saved code and signs a package. Review the module ID, version, publisher/key, SHA-256 and validation checks, then select Publish verified package. The upload uses a separate verified copy so another pack operation cannot replace it.

Enter a marketplace API token from your marketplace profile when prompted; it is kept in the OS keychain, passed to the CLI through its environment and redacted from output. The publicly known development key is reserved for development packages. Use Forget marketplace token to change accounts. Marketplace publishing makes the signed module available for download; use Install to a Smart Assist host when you want to install a module. The existing development-key pack option remains available, and selecting your publisher key also enables packing/signing for production hosts.

Guided module authoring

Open your module and use Tools and views or the Smart Assist: Add… commands. Each editor stays in a VS Code tab. Complete the form, choose Preview files, inspect the source, then Generate and build. The extension stops the local dev host before generation. Save dirty documents first; a changed project requires a fresh preview.

Editor What it generates
Add table Product-owned entity, typed columns, context/DbSet/model configuration and a real EF Baseline or incremental migration
Add column Columns in an existing product-owned entity/context and an incremental EF migration; required columns need explicit defaults for existing rows
Add page Drag/resize Smart Assist controls on a 12-column grid; Razor .cshtml, C# .cshtml.cs, shared form and responsive CSS; choose a table and Create controls from table for a working record-creation form
Add menu item Category and menu section with the chosen existing page, or a new page designed in the same editor
Add API List/get/create/update/delete records or a custom-message starter; descriptions, product filtering, Read/Write access and input validation; optionally expose it through MCP
Add MCP tool Expose an existing REST operation with an AI-facing name, title and description; its parameters and access rules come from that API
Add help article Markdown with a help preview and the title/category/summary metadata that sa pack includes in help/Articles

The page designer marks the shell header and menu Disabled. Integration modules open the My Profile preview automatically after creation: profile details, preferences, security and existing integrations are locked; new controls belong only to the Integrations grid. Generated profile placements use the additive profile.integrations slot on host 4.3.1+ and raise the module's minimum host version accordingly. The generated integration handler validates the form; a provider-specific connection/service call still belongs in OnPostAsync. Unbound ordinary forms also validate without storing data. Table-bound forms include the save handler automatically.

New pages use Razor/C#; the visual editor is TypeScript. No handwritten JavaScript page is generated. Designer definitions are saved under .sa/designer alongside source; tab drafts also survive webview reloads. Add protects existing files; generated code remains normal editable module source.

After a build, click Pages, Widgets or Tables entries in the Module tree to edit them. Saved designer pages reopen their grid and properties. Existing hand-written Razor pages and widget views open a source-aware control editor: select literal controls to edit text/properties, follow local partials using the file tabs, or edit Razor/C# source in the same tab. Module scripts and dynamic Razor expressions are never executed in the editor. Custom handlers remain intact. Custom form markup or layout CSS requires the source editor to avoid replacing manual work. Existing table edits preview a real migration; keys, types, column removal, text narrowing and nullable-to-required conversions are protected. Saving builds the module and rolls back its changes on failure. Reopen an element if another editor changes it while your draft is open.

Tables support text, integer, long, decimal, double, boolean, date/time, date/time-offset and GUID properties, optional/required values, text length, defaults and product-scoped indexes/uniqueness. The CLI restores a project-local EF 9 tool in obj/sa/tools on first use. It creates and builds migration source; it never runs database update. Existing pending model changes must be migrated first. Review and package migrations through the usual Smart Assist module install process.

Add job and Add rules workflow open a visual workflow canvas. Drag conditions, wait timers, value assignments, product-owned record counts, notifications or logging onto it. Connect the Next/Then and Otherwise outputs by selecting destination steps, or use their property dropdowns. Arrange steps lays out the graph. Sample JSON previews the path; it does not execute handlers, query a database, send notifications or wait.

Job timer properties control the SDK scheduler's interval (10 seconds to 30 days), per-product scope and setup requirement. Wait steps share a 180-second limit and honour cancellation. Notifications use a configured recipient user ID; their subject and text can include values such as {{count}}. Record counts always filter to the host's current product. Rules workflows are compiled conditional flows for the module, exposed through Write-protected REST/MCP operations when enabled.

Existing jobs reopen with their original C# handler as a required step. The first save retains that method as RunExistingAsync; conditions and actions can run around it. Custom schedule expressions remain in source. The designer rejects cyclic, disconnected or incomplete graphs, protects manually modified generated files and offers the C# source editor for custom changes. Saved graphs live in .sa/designer; saving builds code and rolls back failed writes.

The same authoring API is available to automation:

sa design inspect --project path/to/Module.csproj
sa design preview --project path/to/Module.csproj --spec table.json
sa design apply --project path/to/Module.csproj --spec table.json --expected <preview-hash>

The VSIX bundles the matching CLI. New modules use public NuGet.org SDK packages by default; clear an older smartAssist.cliPath override to use the bundled CLI.

The Smart Assist view

The Smart Assist icon in the activity bar opens three views:

  • Module - what sa build --json says the module has: sections (with their menu group and route), pages, REST operations, MCP tools, widgets, jobs, tables and dependencies. A section or page opens in the browser while the dev host runs; a REST operation or MCP tool opens the tool explorer. The title bar has Run / Stop, Build, Add/open, Switch and Close. The overflow menu offers Add item and Refresh.
  • Dev host - Run state, the URL, the demo sign-in, the modules in the run set and why each is there, Stop.
  • Click Sign in as Alex Morgan in Dev host to sign your default browser in and open the module. This uses the existing login form and a single-use loopback handoff; no password or session cookie is included in the link.
  • Tools and views - the component gallery, menu placement preview, tool explorer, Validate, Pack, Sign, Install, Status, Clean and New module.

The status bar shows Smart Assist: Run (click to run; while running it shows the address and stops on click).

Commands (command palette, "Smart Assist: ...")

Command What it does (the sa command)
Add or open a module Open an existing module .csproj and add its folder to the workspace, or create a new module
Switch module Choose another workspace module or browse for one; stops the old dev host first
Close module Stop the local host and clear the active module; source files and dev data remain, and the module stays closed after reload
New module from template Picks sa-module, sa-widget, sa-studio or sa-integration, a <Company>.<Module> name and a folder (sa new; the templates are installed on first use)
Add to module Opens guided table/column/page/menu/API/MCP/help editors; sections/widgets/jobs/dependencies keep the existing CLI wizard
Build sa build --json: the module tree; compiler errors in the Problems panel
Run (dev host, debugger, rebuild on save) sa run --watch --events (below); also F5 with a smartassist launch configuration, or Cmd+Alt+R / Ctrl+Alt+R
Run without debugging The same without attaching the debugger
Stop the dev host Ends sa run and the host it started (only that process)
Validate (Problems panel) sa pack --dev-key then sa validate --json: every failed install rule as an error, capabilities as information
Pack (.samodule) sa pack, signed with the dev key or unsigned
Sign with the dev key sa sign --dev-key on the newest package in bin/sa
Install to a Smart Assist host Picks a host (or the running dev host), asks once for a System Administrator's personal access token (kept in VS Code's SecretStorage, the OS keychain), sa install --apply none/now/quiet
Status of a host sa status
Clean (fresh demo data next run) Stops the dev host, sa clean: the next Run starts from fresh demo data
Forget a host's token Removes a saved host and its token
Component gallery SmartAssist.UI components with a live preview (the library's own CSS and JS), Copy and Insert Razor, Copy JS. From the running dev host when it serves the gallery, else the copy shipped in the extension
Menu placement preview Where the module's sections land: main menu, Administration, System configuration, Profile, Help, by order and category
MCP / REST tool explorer The dev host's generated MCP catalog (/api/v1/modules/mcp-catalog): this module's tools (or every module's), a form from the input schema, Run against the dev host with the dev token

Run

Run does everything with no setup (ARCHITECTURE.md 13.3):

  1. Selects the bundled development host, saves all files and starts sa run --project <module> --watch --events --no-browser.
  2. sa builds the module (Debug) and packs a dev package (dev key, marked dev in its manifest).
  3. It adds exactly the modules the project declares with <SaDependency>, and theirs, transitively: from a local module folder (smartAssist.modulePaths, or a modules/ folder above the module) or the module feed (smartAssist.moduleFeed). Nothing else is installed; a module an earlier run installed that isn't in the set any more is removed. The output lists what was included and why.
  4. The dev host's data is obj/sa-devhost/data, created on the first Run and kept between runs until Clean (or sa clean, or a Clean task). Optional demo data is copied there; otherwise a new local database and demo administrator are created. The extension installation contains only host binaries and static assets, never your module data.
  5. It starts Smart Assist (Development: the dev key is trusted, a newer build of the same version installs), waits for /healthz, prints the module states and makes a personal access token for the demo System Administrator in the dev data only (obj/sa-devhost/token), used by the tool explorer and Status.
  6. The browser opens on the module's first section (sign in as alex.morgan@example.com / Admin-Pass-123!, product "300 People"). The CLI ensures that login in the managed local copy only, without changing the source demo data. An empty database seeds Alex as its initial administrator. If a copied database has no active Alex account, the Dev host view asks you to use an existing account instead. The C# debugger attaches to the host process (coreclr attach; the dev package carries the PDB, so breakpoints in the module's code bind).
  7. On save, sa rebuilds; when the build is good it stops the old host before replacing module files and restarts the host (a controlled restart, the safe-mode counter isn't touched) and the debugger attaches again. A failed build leaves the old build running and puts the errors in the Problems panel.

Settings

Setting Default
smartAssist.cliPath (empty) sa executable or sa.dll (run with dotnet). Empty: the CLI included in this VSIX. Clear older overrides to use the bundled fixes
smartAssist.hostDir (empty) Optional host override: a src/SmartAssist.Web folder or published build. Empty: SMARTASSIST_HOST_DIR when set, otherwise the development host included in the extension
smartAssist.demoData (empty) The demo data copied into the dev host. Empty: SMARTASSIST_DEMO_DATA (without it the host starts on an empty database)
smartAssist.modulePaths [] Folders of local modules for dependencies
smartAssist.moduleFeed (empty) A folder of released .samodule packages for dependencies
smartAssist.port 5300 The dev host's port
smartAssist.watch true Rebuild, reinstall and restart on save
smartAssist.attachDebugger true Attach the .NET debugger on Run
smartAssist.browser external external, simple (VS Code's Simple Browser) or none
smartAssist.sdkFeed https://api.nuget.org/v3/index.json Public NuGet.org by default; an explicit local/custom feed is supported
smartAssist.sdkVersion 1.11.2 SmartAssist SDK version for new modules
smartAssist.validateOnBuild false Validate after every Build

Tests

npm test runs the integration tests in a real VS Code (@vscode/test-electron; the installed VS Code when there is one, else a downloaded build) with a fresh profile: a module from the template in a temp folder, items added, Build, a broken build in Problems, Validate, Run (the module plus its dependency sa.badges from modules/), the module's page signed in over HTTP, its REST operation and MCP tool with the dev token, a save restarting the host, Stop and Clean. SA_TEST_DEBUG=1 npm test also attaches the real C# debugger (copied into the test profile) and stops at a breakpoint in the module. They expect the repository's CLI built (dotnet build src/SmartAssist.Cli), the SDK packed into ../sdk-feed-ext (or SA_SDK_FEED) and the demo data (SMARTASSIST_DEMO_DATA); SA_TEST_PORT (default 5331).

The release workflow also runs SA_TEST_SUITE=workflow npm test against the bundled host, with a standalone module in a temporary workspace and no host override. It checks first-run database creation, demo login, module loading, rebuild-on-save and shutdown. The packaged VSIX is separately checked for host binaries and native assets.

Troubleshooting

  • "The sa CLI isn't installed" - dotnet tool install -g SmartAssist.Cli, or set smartAssist.cliPath. Typing sa in a macOS terminal runs /usr/sbin/sa; use ~/.dotnet/tools/sa.
  • "Where is Smart Assist?" - update to 1.6.4 or newer and clear old smartAssist.cliPath and smartAssist.hostDir overrides to use the bundled CLI and host. An explicit SMARTASSIST_HOST_DIR environment variable also overrides the bundled host. Reinstall if the bundled host is missing.
  • "Port 5300 is in use" - another Run (or something else) holds it: Stop it or change smartAssist.port.
  • The module is Faulted - the Run output shows the host's reason (for example "Needs sa.badges >=1.0.0"): add the dependency's folder to smartAssist.modulePaths or its package to smartAssist.moduleFeed.
  • Everything shows "Skipped - safe mode" - the host failed to start twice in a row (a crash at start-up, not a Run restart). Fix the cause in the output, then Clean (fresh demo data) or run again.
  • The debugger doesn't attach - install the C# extension; breakpoints need the Debug build Run makes (they bind a few seconds after the host is ready, once the module's PDB is loaded).
  • The sign-in page asks for a product - choose "300 People" (the demo product).
  • Stale demo data - Clean, then Run.

Public package downloads

The bundled CLI installs SmartAssist.Templates from NuGet.org by default and creates a public-only nuget.config for each new module, including when older templates are already installed. SDK, data, testing, UI and transitive NuGet dependencies restore from that configuration without GitHub package credentials. Explicit local/custom SDK feeds remain supported.

For an existing module, remove the old GitHub package source from its own nuget.config, keep NuGet.org, and update its SmartAssist package references (or SaSdkVersion) to 1.11.2. This does not modify machine-level NuGet sources used by other repositories.

  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
  • Your Privacy Choices
  • Consumer Health Privacy
© 2026 Microsoft