Skip to content

3.7.0

Release Date: June 5, 2026

✨ New Features

NuGet Packages

Startup ActivitySource Tracing and EF Environment Handling 🔭

Packages: SAIF.Platform, SAIF.Platform.Authentication, SAIF.Platform.Azure, SAIF.Platform.EntityFramework, SAIF.Platform.Kiota.HttpClientLibrary

Commit: 4f29a31d

Adds startup ActivitySource tracing with XML documentation and environment handling updates for Entity Framework integration. Startup activities now carry configuration context visible in local trace tooling and OTLP-based APM dashboards. The entityframework.is_development tag has been replaced with entityframework.environment to report the exact environment value.

Key Features:

  • ✅ Startup ActivitySource - Structured tracing for application startup phases
  • ✅ XML Documentation - Comprehensive XML docs for public tracing APIs
  • ✅ EF Environment Tagging - Reports exact environment value instead of boolean is_development flag

Benefits:

  • 🔍 Better visibility into startup behavior via distributed tracing
  • 📊 Accurate environment identification in Entity Framework telemetry
  • 📖 Improved developer experience with IntelliSense documentation

Project Templates

Mosaic Design System Integration 🎨

Template: saif-api-exp

Commit: 0e813051

Integrates the Mosaic design system into the Forge frontend React template, replacing the previous basic layout with Mosaic's navigation, theming, and component patterns. This brings the Golden Path frontend template in line with the organization's design system standards.

Key Features:

  • ✅ AppLayout with Mosaic - Sidenav, header, breadcrumbs, and theming out of the box
  • ✅ Localization Infrastructure - i18next with translation sync support
  • ✅ Error Handling - Error page and route error handling built-in
  • ✅ Zero-Dependency Git Hooks - Replaced husky with .hooks/ directory
  • ✅ PowerShell Core Prepare Script - Converted from vite-node to cross-platform PowerShell

Usage:

dotnet new saif-api-exp

Benefits:

  • 🎨 Consistent look and feel with Mosaic design system across all new apps
  • 🌐 Localization-ready from day one
  • 🚀 Faster project bootstrap with pre-configured navigation and theming
  • 🔧 Simplified Git hooks with no external dependencies

🔧 Enhancements

NuGet Packages

Structured Token Error Telemetry in Kiota Providers 📊

Package: SAIF.Platform.Kiota.HttpClientLibrary

Commit: c61fb7df

Replaces raw SetStatus calls with a structured AddTokenError Activity extension in both Kiota token providers. Token failures now emit filterable telemetry tags and structured events for improved APM observability in Dynatrace and other OTLP-compatible backends.

Changes:

  • Added ActivityExtensions.AddTokenError shared extension method
  • Records ActivityEvent("authentication.token_error") with structured tags
  • Always emits http.response.status_code (including 0 for non-HTTP paths)
  • Both providers now use null-safe span?.AddTokenError(token, projectId) invocation

Example:

// Before — opaque free-text only
span?.SetStatus(ActivityStatusCode.Error, $"{token.ErrorType}: {token.ErrorDescription}");

// After — structured, filterable event + exception when present
if (token.IsError)
{
    span?.AddTokenError(token, projectId);
}

Benefits:

  • 🔍 error.type separates protocol failures from exception-based failures
  • 🏷️ error.code is filterable in Dynatrace (invalid_client, access_denied, etc.)
  • 📊 http.response.status_code is always present for consistent querying
  • 🎯 authentication.project_id enables per-project failure aggregation
  • 🐛 Stack traces surfaced for exception-based errors

🐛 Bug Fixes

Terraform Modules

Sanitize Deployed-By Tag for Dependabot Builds 🏷️

Commit: 2bdd3ed3

Sanitizes the deployed_by tag value to strip parentheses that appear in Dependabot build identities. Azure resource tags do not allow parentheses, causing deployment failures when Dependabot triggers infrastructure pipelines.

Remove Duplicate <base /> from APIM Operation Policies 🔌

Module: saif-apim

Commit: fbc98e7c

Removes duplicate <base /> elements from operation-level API Management policies. The duplication caused policy evaluation to run base policies twice, potentially leading to unexpected behavior in request/response processing.

Grant OTEL Header KV Secret Access to UAMI Instead of SP 🔒

Module: saif-identity

Commit: 74d6a2b3

Fixes the Key Vault secret access role assignment for OTEL header configuration to target the User-Assigned Managed Identity (UAMI) instead of the Service Principal. This ensures the application runtime identity has proper access to retrieve OpenTelemetry ingestion headers.

📝 Documentation

Auth Documentation Overhaul 📋

Commit: 6d7135b7

Audited and clarified authentication documentation to distinguish Entra ID and Okta scope and app role differences. Ensures teams understand which identity provider patterns apply to their deployment scenarios.

Golden Path Homepage Elevation 🏠

Commit: f1253505

Elevated the Golden Path on the Forge documentation homepage and reorganised contributing docs under the "About" section. Makes the recommended application development path more discoverable for new developers.

Technology Vision North Star 🌟

Commit: aaf07199

Added a technology vision north star document outlining the platform's strategic direction and long-term architectural goals.

Commit: b7081f5a

Replaced Azure DevOps wiki links with internal Forge documentation references, consolidating documentation discoverability within the Forge docs site.

Guided "Build on Your App" Path 🛤️

Commit: 692a0b3b

Added a guided "Build on Your App" tutorial path after the first application tutorial, helping developers transition from the initial Golden Path walkthrough to customising their own applications.

🔄 Breaking Changes

None in this release ✅

📋 Additional Notes

  • Total commits: 26
  • Files changed: 1,320
  • Contributors: Emmitt Johnson, Gabe Higginbotham, Copilot

Support

  • 📧 Teams Support Channel: Support