AGENT SKILL

vscode-webview-trpc-messaging

Implements tRPC-based communication between the Rayfin VS Code extension host and React webviews (packages/tools/vscode). Use when creating new webview procedures (queries, mutations, subscriptions), adding a new webview router, wiring up a webview controller, using the tRPC client from React components, applying telemetry middleware (trpcToTelemetry), or supporting AbortSignal-based cancellation in webview operations.

License 许可
MIT
所属仓库
microsoft/rayfin
最近更新
2026-11-12
Stars
★ 662
Forks
77

01 前言 Front Matter

name
vscode-webview-trpc-messaging
description
Implements tRPC-based communication between the Rayfin VS Code extension host and React webviews (packages/tools/vscode). Use when creating new webview procedures (queries, mutations, subscriptions), adding a new webview router, wiring up a webview controller, using the tRPC client from React components, applying telemetry middleware (trpcToTelemetry), or supporting AbortSignal-based cancellation in webview operations.

02 资源文件 4

03 SKILL.md 正文

Webview tRPC Messaging

Type-safe RPC communication between the VS Code extension host (server) and React webviews (client) using tRPC.

Architecture Overview

React Webview (client)                    Extension Host (server)
─────────────────────                     ──────────────────────
useTrpcClient() hook                      WebviewController
  └─ createTRPCClient                       └─ setupTrpc()
       └─ vscodeLink ──── postMessage ────►     ├─ callerFactory(appRouter)
            (send/onReceive)              ◄─────┤   └─ procedure(input)
                                                └─ abort/subscription.stop

Key files (read as needed for implementation details):

File Purpose
packages/tools/vscode/src/webviews/api/extension-server/trpc.ts tRPC init, publicProcedure, publicProcedureWithTelemetry
packages/tools/vscode/src/webviews/api/configuration/appRouter.ts Root router bundling all view routers + commonRouter
packages/tools/vscode/src/webviews/api/extension-server/WebviewController.ts WebviewPanel lifecycle, tRPC message dispatcher (queries, mutations, subscriptions, abort)
packages/tools/vscode/src/webviews/api/webview-client/useTrpcClient.ts React hook providing the tRPC client
packages/tools/vscode/src/webviews/api/webview-client/vscodeLink.ts Custom tRPC link bridging postMessage transport

Creating a New Router

Each webview maintains its own router. Follow this pattern:

1. Define the router context

Extend BaseRouterContext with view-specific fields:

// packages/tools/vscode/src/webviews/myView/myViewRouter.ts
import { type BaseRouterContext } from '../api/configuration/appRouter';

export type RouterContext = BaseRouterContext & {
  clusterId: string;
  viewId: string;
  databaseName: string;
  // add view-specific fields
};

2. Define procedures

import { z } from 'zod';
import { publicProcedureWithTelemetry, router, type WithTelemetry } from '../../api/extension-server/trpc';

export const myViewRouter = router({
  // Query with telemetry (preferred for operations that touch external services)
  getData: publicProcedureWithTelemetry.input(z.object({ id: z.string() })).query(async ({ input, ctx }) => {
    const myCtx = ctx as WithTelemetry<RouterContext>;
    // myCtx.telemetry is guaranteed present
    // myCtx.signal is the AbortSignal for cancellation
    return { data: 'result' };
  }),

  // Mutation without telemetry (rare, use for fire-and-forget)
  doAction: publicProcedure.input(z.string()).mutation(({ input }) => {
    // lightweight operation
  }),
});

3. Register in appRouter

// packages/tools/vscode/src/webviews/api/configuration/appRouter.ts
import { myViewRouter } from '../../myView/myViewRouter';

export const appRouter = router({
  common: commonRouter,
  myView: myViewRouter, // <-- add here
});

4. Create the controller

// packages/tools/vscode/src/webviews/myView/myViewController.ts
import { WebviewController } from '../api/extension-server/WebviewController';
import { type RouterContext } from './myViewRouter';

export class MyViewController extends WebviewController<MyViewConfig> {
  constructor(initialData: MyViewConfig) {
    super(ext.context, title, 'myViewName', initialData);

    const trpcContext: RouterContext = {
      webviewName: 'myView',
      clusterId: initialData.clusterId,
      viewId: initialData.viewId,
    };

    this.setupTrpc(trpcContext);
  }
}

Important: The webviewName in the WebviewController constructor is the registry key (must match a key in WebviewRegistry, e.g. myViewName). The webviewName in the tRPC context is a telemetry label used in telemetry event names (e.g. myView). These are intentionally different values — do not confuse them.

5. Register in WebviewRegistry

Add your React component to the registry. The key must match the webviewName passed to WebviewController's constructor. The WebviewName type (exported from the same file) ensures compile-time validation of webview names.

// packages/tools/vscode/src/webviews/api/configuration/WebviewRegistry.ts
import { MyView } from '../../myView/MyView';

export const WebviewRegistry = {
  myViewName: MyView, // <-- add your entry
} as const;

export type WebviewName = keyof typeof WebviewRegistry;

Telemetry: publicProcedure vs publicProcedureWithTelemetry

Base When to use ctx.telemetry
publicProcedure Fire-and-forget, no external calls, telemetry reported separately undefined
publicProcedureWithTelemetry Default choice. Any procedure touching DB, network, or user-visible work Guaranteed via trpcToTelemetry middleware

trpcToTelemetry (file-local, not exported) wraps the procedure in callWithTelemetryAndErrorHandling, auto-generating a telemetry event named rayfin.rpc.{type}.{path} and recording errors, duration, and abort status.

Access telemetry safely:

const myCtx = ctx as WithTelemetry<RouterContext>;
myCtx.telemetry.properties.myCustomProp = 'value';
myCtx.telemetry.measurements.itemCount = items.length;

AbortSignal Support

Every tRPC operation (query, mutation, subscription) receives its own AbortController. Cancellation flows:

Client (React)                              Server (Extension Host)
──────────────                              ──────────────────────
// Queries/Mutations:
ac = new AbortController()
trpcClient.myProc.query(input,
  { signal: ac.signal })
ac.abort()  →  sends 'abort' msg  →  abortController.abort()
                                        → ctx.signal.aborted = true

// Subscriptions:
sub = trpcClient.mySub.subscribe(...)
sub.unsubscribe()  →  'subscription.stop'  →  abortController.abort()

Using abort in procedures

getData: publicProcedureWithTelemetry
    .input(z.object({ filter: z.record(z.unknown()) }))
    .query(async ({ input, ctx }) => {
        const myCtx = ctx as WithTelemetry<RouterContext>;

        // Option 1: Pass to APIs that accept AbortSignal
        const response = await fetch(url, { signal: myCtx.signal });

        // Option 2: Manual check in loops
        for (const item of items) {
            if (myCtx.signal?.aborted) return;
            await processItem(item);
        }
    }),

Client-side abort

const { trpcClient } = useTrpcClient();
const abortControllerRef = useRef<AbortController>();

const runQuery = async () => {
  abortControllerRef.current?.abort(); // cancel previous
  const ac = new AbortController();
  abortControllerRef.current = ac;

  const result = await trpcClient.myView.myQuery.query(input, { signal: ac.signal });
};

When trpcToTelemetry detects an aborted signal, it sets telemetry.properties.aborted = 'true' and result = 'Canceled' automatically.

Subscriptions

Subscriptions stream multiple values from server to client using async generators:

// Server (router)
streamData: publicProcedureWithTelemetry
    .input(z.object({ batchSize: z.number() }))
    .subscription(async function* ({ input, ctx }) {
        const myCtx = ctx as WithTelemetry<RouterContext>;

        for (let i = 0; i < total; i += input.batchSize) {
            if (myCtx.signal?.aborted) return; // check before each yield
            const batch = await fetchBatch(i, input.batchSize);
            yield batch;
        }
    }),

// Client (React)
const sub = trpcClient.myView.streamData.subscribe(
    { batchSize: 100 },
    {
        onData(batch) { /* handle each batch */ },
        onComplete() { /* all done */ },
        onError(err) { /* handle error */ },
    },
);

// To stop:
sub.unsubscribe();

Client-Side Hook Usage

import { useTrpcClient } from '../api/webview-client/useTrpcClient';
import { useConfiguration } from '../api/webview-client/useConfiguration';

export const MyComponent = () => {
  const { trpcClient } = useTrpcClient();
  const config = useConfiguration<MyViewConfig>();

  useEffect(() => {
    trpcClient.myView.getData.query({ id: config.documentId }).then(setData);
  }, []);
};

useConfiguration<T>() retrieves the initial config passed to WebviewController constructor (serialized via encodeURIComponent(JSON.stringify(...))).

Common Pitfalls

  • Never use any in procedure context casts — use WithTelemetry<RouterContext> or RouterContext
  • Always prefer publicProcedureWithTelemetry unless you have a specific reason not to
  • Always check myCtx.signal?.aborted in long-running loops — not checking causes wasted work after client cancels
  • Do not mutate the shared context object — WebviewController clones it per-operation already, but router code should treat ctx as read-only
  • Input validation uses zod — always define .input(z.object({...})) for type safety
  • The commonRouter handles cross-cutting concerns (error reporting, telemetry events, surveys, URL opening) — do not duplicate these in view-specific routers

04 同仓库更多 Skills

microsoft
microsoft/rayfin

rayfin-getting-started

Use when starting or creating a NEW Rayfin app, or when a Rayfin task comes up and you are not yet inside a Rayfin project. Gets you into a project with the Rayfin CLI, then hands off to the authoritative, version-locked in-project rayfin skill/docs that own all in-project work. Triggers: build a Rayfin app, start a Rayfin project, create a new Rayfin app, create-rayfin, npm create @microsoft/rayfin, rayfin init, scaffold rayfin, rayfin CLI, rayfin template, universal app, awesome-rayfin gallery, get started with Rayfin

★ 662
microsoft
microsoft/rayfin

visuals

Use when user wants to incorporate charts, graphs, data grid, or other visual representations of data into their project. Use VegaVisual and DataGrid components to create these visuals, utilizing the shared DataTable input, formatting, theme, and interactivity. Covers the onInteraction selection/click events host apps consume, named multi-table data input for layered overlays and reference lines, and Vega-Lite native selections. Triggers: chart, graph, plot, dashboard, KPI, metric, trend, scorecard, data grid, visualize.

数据分析师分析与可视化
★ 662
microsoft
microsoft/rayfin

schema-discovery

Explore Power BI semantic model schemas using DAX INFO functions. Progressive metadata discovery strategy, scope estimation, and narrowing techniques for tables, columns, measures, and relationships.

★ 662
microsoft
microsoft/rayfin

query-design

Separates DAX data-fetching from TypeScript presentation. Guides when to use DAX vs. TypeScript vs. Vega-Lite for aggregation, total rows, FORMAT(), SELECTCOLUMNS, BLANK handling, filtering, multi-grain queries, cross-filtering and cross-highlight subset/overlay queries, and format strings.

设计师演示文稿视觉设计
★ 662
microsoft
microsoft/rayfin

functions-capability

Apply and build the Universal App functions capability. Use for trusted server-side logic, secrets, external APIs, custom model endpoints, published Fabric data agents, webhooks, or privileged operations.

★ 662
microsoft
microsoft/rayfin

fabric-sdk

How to query Fabric data from a running app through the Rayfin connectors client. Use getRayfinClient().connectors.<name>.executeQuery to run DAX against a semantic model, and toQueryResult to normalize the response.

★ 662