Skip to content

AGENTS.md

Latest commit

 

History

History
243 lines (170 loc) · 10.1 KB

AGENTS.md

File metadata and controls

243 lines (170 loc) · 10.1 KB
Raw

AGENTS.md — ASP.NET SignalR

Guidance for AI agents and contributors working in this repository.

What this project is

ASP.NET SignalR (Microsoft.AspNet.SignalR) is a real-time web library for .NET Framework apps using System.Web or OWIN/Katana. It lets servers push content to connected clients (browsers and .NET clients) over WebSockets, Server-Sent Events, Forever Frame, or long polling.

This is not ASP.NET Core SignalR. For ASP.NET Core, see aspnet/AspNetCore SignalR.

Fact Detail
Upstream SignalR/SignalR
This remote RWS/SignalR (fork)
Product status Maintenance mode — no new features; critical/security fixes only (announcement)
License Apache 2.0 (LICENSE.txt)
Docs ASP.NET SignalR docs
Consumer install Install-Package Microsoft.AspNet.SignalR
Latest NuGet stable 2.4.3 (nuget.org). Repo version.props may be ahead (e.g. 2.4.4-preview1)

Repository layout

src/           # Shipping libraries and utilities
samples/       # Sample host apps
test/          # Unit, functional, and JS client tests
build/         # MSBuild props/targets, signing, localization, symbols
.vsts-pipelines/  # Azure DevOps CI (public + official/1ES)
eng/           # Shared pipeline templates (SBOM, retain-build)
artifacts/     # Build output (gitignored)

Main shipping packages (src/)

Project Role
Microsoft.AspNet.SignalR Meta package (SystemWeb + JS client)
Microsoft.AspNet.SignalR.Core Server core (hubs, transports, messaging)
Microsoft.AspNet.SignalR.SystemWeb ASP.NET / System.Web host integration
Microsoft.AspNet.SignalR.SelfHost OWIN self-host meta package
Microsoft.AspNet.SignalR.Client .NET client (net40, net45, netstandard1.3, netstandard2.0)
Microsoft.AspNet.SignalR.JS Browser JS client (jquery.signalR*.js)
Microsoft.AspNet.SignalR.Redis / StackExchangeRedis Redis scale-out
Microsoft.AspNet.SignalR.SqlServer SQL Server scale-out
Microsoft.AspNet.SignalR.ServiceBus / ServiceBus3 Azure Service Bus scale-out
Microsoft.AspNet.SignalR.Utils signalr.exe helper (packable)

Non-shipping / excluded from pack: Crank, Stress, StressServer.

Versioning is centralized in version.props (VersionPrefix / VersionSuffix / PackageVersion). Dependencies are pinned in build/dependencies.props.

Prerequisites

  • Windows for a full product build (signing, loc, many tests, VS tooling). build.sh exists but the product targets .NET Framework and CI is Windows-only.
  • Visual Studio 2017+ (solution note: VS 2017; CI agents use VS 2019 Enterprise with Web workload).
  • .NET Framework targeting packs / MSBuild (net45 / net472 as used by projects and tests).
  • Node.js (CI uses 16.x) for JS client tests under test/Microsoft.AspNet.SignalR.Client.JS.Tests.
  • Network access to NuGet feeds in NuGet.config (dotnet-public, myget-legacy on Azure DevOps).

Build orchestration uses KoreBuild (ASP.NET BuildTools, channel release/2.1 per korebuild.json / korebuild-lock.txt), invoked via run.ps1 / run.sh.

Building

Full default build (compile + package + tests)

From the repo root on Windows:

build.cmd

Or explicitly:

build.cmd -ci /p:Configuration=Release

Cross-platform entry (still KoreBuild; limited usefulness for full Framework builds):

./build.sh

build.cmd / build.sh run the KoreBuild default-build command (restore → build → package → test).

Common MSBuild / KoreBuild switches

Pass properties after the script name:

REM Release configuration (CI default)
build.cmd /p:Configuration=Release

REM Skip tests if you only need binaries/packages (when supported by KoreBuild targets)
build.cmd /t:Package /p:Configuration=Release

REM Official-style attributes (Company/Copyright); CI sets OfficialBuild=true
build.cmd /p:OfficialBuild=true /p:Configuration=Release

REM Final release version shaping (see version.props)
build.cmd /p:IsFinalBuild=true /p:Configuration=Release

Historically, packaging without the full test suite has been done with a Package-focused target (e.g. /t:BuildPackages or /t:Package depending on KoreBuild version). Prefer /t:Package if BuildPackages is unknown; inspect KoreBuild help with:

.\run.ps1 help

Build a single project in Visual Studio

  1. Open Microsoft.AspNet.SignalR.sln in VS 2017+.
  2. Ignore unloadable legacy projects (UWP/Silverlight-era) if present.
  3. Build the project you need (e.g. Microsoft.AspNet.SignalR.Client).

Useful for local debugging with matching PDBs without a full KoreBuild run.

Artifact layout

Output Path
Assemblies artifacts/$(Configuration)/bin/<Project>/
NuGet packages artifacts/$(Configuration)/packages/
Symbols artifacts/$(Configuration)/symbols/
Intermediate artifacts/obj/
Logs / TRX artifacts/logs/ (CI moves .binlog here)

Testing

  • Default test TFM: net472 (Directory.Build.props).
  • .NET tests run via KoreBuild as part of default-build.
  • JS browser tests: npm ci then npm test in test/Microsoft.AspNet.SignalR.Client.JS.Tests (wired as RunBrowserTests in build/repo.targets). CI installs Chrome and Node 16.
  • UWP client tests are excluded from KoreBuild (build/repo.props).

Functional/integration tests may require IIS / SQL / other Windows features available on the VS Enterprise CI image.

CI and official builds

Pipeline File Purpose
Public .vsts-pipelines/builds/ci-public.yml PR/CI validation; SkipCodeSign: true
Official .vsts-pipelines/builds/ci-official.yml Signed, localized Release build (1ES); OfficialBuild, Localize, MicroBuild signing

Shared steps: .vsts-pipelines/templates/signalr-build.yml → .\build.cmd -ci /p:Configuration=Release.

Official extras: Component Governance, MicroBuild localization + signing plugins, optional SBOM + retain when IsFinalBuild=true.

Triggers typically cover main, release/*, vsts/*.

Re-publishing (packages)

What gets published

NuGet packages under IDs such as:

  • Microsoft.AspNet.SignalR
  • Microsoft.AspNet.SignalR.Core
  • Microsoft.AspNet.SignalR.SystemWeb
  • Microsoft.AspNet.SignalR.Client
  • Microsoft.AspNet.SignalR.JS
  • Microsoft.AspNet.SignalR.SelfHost
  • Scale-out: Redis, StackExchangeRedis, SqlServer, ServiceBus, ServiceBus3
  • Microsoft.AspNet.SignalR.Utils

Official Microsoft releases go to nuget.org. main historically tracks the shipped nuget.org release; releases are also GitHub-tagged.

Version rules (version.props):

  • Dev builds: $(VersionPrefix)-$(VersionSuffix)-$(BuildNumber) (e.g. 2.4.4-preview1-t000).
  • Final RTM: set IsFinalBuild=true and VersionSuffix=rtm → plain VersionPrefix.
  • Final non-RTM: IsFinalBuild=true → $(VersionPrefix)-$(VersionSuffix)-final.

Bump VersionPrefix / VersionSuffix in version.props before a release cut.

Local / private republish

  1. Build packages (Release recommended):

    build.cmd /p:Configuration=Release

  2. Packages appear in artifacts/Release/packages/.

  3. Push to a feed you control (do not push Microsoft-signed IDs to nuget.org unless you are the official publisher):

    nuget push artifacts\Release\packages\*.nupkg -Source https://your-feed -ApiKey <key>

    or:

    dotnet nuget push artifacts\Release\packages\*.nupkg --source https://your-feed --api-key <key>

For a fork/private fork republish, consider changing package IDs / authors in project metadata so packages do not collide with Microsoft’s Microsoft.AspNet.SignalR* on nuget.org.

Official Microsoft republish path

  1. Land changes on the release branch / main per team process.
  2. Run the official pipeline with signing (SignType=real), localization (Localize=true), and OfficialBuild=true.
  3. Queue with IsFinalBuild=true when cutting the shipping bits (enables final version shaping, SBOM, retain).
  4. Publish signed .nupkg artifacts from the pipeline drop to nuget.org (and any internal feeds) using Microsoft’s release tooling/process.
  5. Tag the release in GitHub and update release notes (PackageReleaseNotes points at GitHub releases).

Signing uses MicroBuild + build/sign.proj / SignToolData*.json. Local unsigned builds skip MicroBuild when plugins are absent (LocateMicroBuild in build/repo.targets).

Consuming a private build without republishing

Reference built assemblies from artifacts/$(Configuration)/bin/..., or add a local NuGet source:

<!-- NuGet.config -->
<add key="signalr-local" value="path\to\artifacts\Release\packages" />

Agent working notes

  • Prefer minimal, maintenance-safe changes (bug/security fixes). Do not add features unless explicitly requested.
  • Keep ASP.NET SignalR vs ASP.NET Core SignalR clear in docs and comments.
  • Prefer editing version.props and build/dependencies.props over scattering version numbers.
  • Treat warnings as errors (TreatWarningsAsErrors).
  • Strong-name / delay-sign behavior differs for CI (DelaySign / SignAssembly when CI=true); do not check in private keys.
  • JS client sources live under src/Microsoft.AspNet.SignalR.JS/; generated/minified scripts are build outputs.
  • Samples under samples/ illustrate hosting patterns; product code changes belong in src/.
  • Do not commit artifacts/, bin/, obj/, or generated jquery.signalR*.js outputs.
  • Security reports: follow SECURITY.md (MSRC), not public issues.

Quick reference commands

REM Clone & build
git clone https://github.com/RWS/SignalR.git
cd SignalR
build.cmd

REM Release packages only-oriented run (adjust target if needed)
build.cmd /p:Configuration=Release /t:Package

REM KoreBuild help
run.ps1 help