# 2.1.21

**Release Date:** November 19, 2025

---

## ✨ New Features

### NuGet Packages

#### Scalar API Documentation Integration 🎨

**Package:** `SAIF.Platform.Aspire.Hosting`

Added support for Scalar, a modern interactive API documentation tool that provides a beautiful and user-friendly interface for exploring OpenAPI specifications.

**Key Features:**

- ✅ **Scalar Resource** - First-class Aspire resource for Scalar documentation
- ✅ **Builder Extensions** - Fluent API for adding Scalar to your Aspire projects
- ✅ **Automatic Integration** - Seamlessly integrates with existing API projects

**Benefits:**

- 🚀 Modern, interactive API documentation out of the box
- 🔄 Automatic OpenAPI spec discovery and rendering
- 🎯 Better developer experience for API consumers

**Example:**

```csharp
builder.AddScalar("api-docs")
    .WithOpenApiSpec("/openapi/v1.yaml");
```

---

#### WiremockCli Support (Experimental) 🧪

**Package:** `SAIF.Platform.Aspire.Hosting`

Introduced experimental WiremockCli integration for Aspire applications, enabling powerful API mocking capabilities during local development and testing.

**Key Features:**

- ✅ **Experimental APIs** - Early access to WiremockCli functionality (marked with `SAIFWIREMOCKCLI0001` diagnostic)
- ✅ **Service Configuration** - Configure mock services with fluent API
- ✅ **Aspire Integration** - Native support for Aspire resource management

**Benefits:**

- 🚀 Accelerate development with reliable API mocks
- 🔄 Test integration scenarios without external dependencies
- 🎯 Consistent mock behavior across team environments

**Example:**

```csharp
builder.AddWiremockCli("mock-api")
    .WithMappingsDirectory("./mocks");
```

**Note:** This feature is experimental and APIs may change in future releases. Use the diagnostic ID `SAIFWIREMOCKCLI0001` to suppress warnings if needed.

**Documentation:**

- [WiremockCli Guide](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/src/dotnet/SAIF.Platform.Aspire.Hosting/WiremockCli/README.md)

---

### Terraform Modules

#### Azure Management Group Module 🏢

**Module:** `src/terraform/azure-management/modules/management_group`

Complete Terraform module for creating and managing Azure Management Groups, enabling hierarchical organization of Azure subscriptions.

**Key Features:**

- ✅ **Hierarchical Structures** - Support parent-child management group relationships
- ✅ **Subscription Association** - Attach subscriptions to management groups
- ✅ **Input Validation** - Comprehensive validation for names and subscription UUIDs
- ✅ **Smart Defaults** - Display name defaults to name if not provided

**New Variables:**

- `name` (string, required) - Management group name
- `display_name` (string, optional) - Friendly display name
- `parent_management_group_id` (string, optional) - Parent management group ID for hierarchy
- `subscription_ids` (list(string), optional) - List of subscription UUIDs to associate

**Example:**

```hcl
module "platform_mg" {
  source = "../../modules/management_group"

  name         = "platform"
  display_name = "Platform Services"
  parent_management_group_id = azurerm_management_group.root.id
  subscription_ids = [
    "12345678-1234-1234-1234-123456789012"
  ]
}
```

**Benefits:**

- ✅ Organize subscriptions into logical hierarchies
- ✅ Apply governance policies at scale
- ✅ Simplify subscription management

---

#### Azure Subscription Module 🔑

**Module:** `src/terraform/azure-management/modules/subscription`

New Terraform module for managing Azure subscriptions with comprehensive configuration options and examples.

**Key Features:**

- ✅ **Subscription Provisioning** - Create and manage Azure subscriptions
- ✅ **Flexible Configuration** - Support for various subscription types and settings
- ✅ **Example Configurations** - Multiple examples demonstrating common patterns

**Example:**

```hcl
module "subscription" {
  source = "../../modules/subscription"

  subscription_name = "dev-subscription"
  # Additional configuration...
}
```

**Benefits:**

- ✅ Automated subscription provisioning
- ✅ Consistent subscription configuration
- ✅ Infrastructure as code for subscription management

**Documentation:**

- [Subscription Module README](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/src/terraform/azure-management/modules/subscription/README.md)

---

#### Application Permissions Management 🔐

**Module:** `src/terraform/saif-application-permissions`

Added `keep.tf` file to preserve application permissions configuration and prevent accidental deletion of critical security settings.

**Key Features:**

- ✅ **Protected Configuration** - Ensures permissions remain tracked in source control
- ✅ **Prevents Drift** - Keeps critical security settings from being accidentally removed

**Benefits:**

- 🛡️ Enhanced security posture
- 🔒 Prevents permission configuration loss
- 📝 Maintains audit trail for permission changes

---

### Foundry Examples

#### PetStore Event Orchestration Sample 🐾

**Location:** `foundry/dotnet/event-orchestration`

Comprehensive example application demonstrating event-driven architecture with Azure Functions, Durable Functions, Service Bus, and Cosmos DB.

**Components:**

- ✅ **PetStore.Api** - REST API for order management
- ✅ **PetStore.Orchestration** - Durable Functions for saga orchestration
- ✅ **PetStore.Data** - Cosmos DB data access layer
- ✅ **PetStore.ServiceBus.Seed** - Service Bus message seeding tool
- ✅ **PetStore.AppHost** - Aspire orchestration host

**Key Features:**

- ✅ **Saga Pattern** - Order fulfillment orchestration with compensation logic
- ✅ **Activity Tracing** - Comprehensive correlation ID tracking across services
- ✅ **Service Bus Integration** - Event-driven communication between services
- ✅ **Cosmos DB** - Document storage for orders and inventory

**Architecture Highlights:**

- 🚀 Event-driven microservices architecture
- 🔄 Durable Functions for reliable orchestration
- 🎯 Correlation ID tracking for distributed tracing
- 📊 Sensitive data logging enabled for local development

**Example:**

```csharp
// OrderCreatedTrigger - Service Bus trigger
[Function(nameof(OrderCreatedTrigger))]
public async Task Run(
    [ServiceBusTrigger("orders", Connection = "ServiceBusConnection")]
    string message,
    FunctionContext context)
{
    var orchestrationClient = context.GetOrchestrationClient();
    await orchestrationClient.StartNewAsync(
        nameof(OrderFulfillmentOrchestrator),
        message);
}
```

**Documentation:**

- [PetStore Event Orchestration README](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/foundry/dotnet/event-orchestration/README.md)

---

#### Azure API Management Policy Examples 🛡️

**Location:** `foundry/terraform/azure-apim-policy`

Complete Terraform examples for Azure API Management policies, including authentication, authorization, and request/response transformation.

**Policy Templates:**

- ✅ **EntraID Authentication** - Validate and authorize Azure AD tokens
- ✅ **Okta Authentication** - Support for Okta identity provider
- ✅ **Permission Checking** - Fine-grained permission validation
- ✅ **Error Handling** - Standardized error response headers
- ✅ **CORS Support** - Configurable origin headers
- ✅ **Mock Backends** - Development/testing backend configuration

**Key Features:**

- ✅ **Modular Policy Design** - Reusable policy fragments
- ✅ **Template-Based** - Easy customization via variables
- ✅ **OpenAPI Integration** - Policy examples with OpenAPI specification
- ✅ **Test Endpoints** - HTTP test file included for validation

**Example:**

```hcl
module "auth_policy" {
  source = "./api_auth_policy_entraid"

  api_management_id = azurerm_api_management.apim.id
  # Additional configuration...
}
```

**Benefits:**

- 🔒 Enterprise-grade API security
- 🔄 Reusable policy patterns
- 🎯 Consistent authentication/authorization

---

## 🔧 Enhancements

### NuGet Packages

- ✅ **SAIF.Platform.Aspire.Hosting** - Updated WiremockCli with improved defaults and options extensions
- ✅ **Microsoft.Identity.Client** - Updated from 4.77.1 to 4.79.0 with improved managed identity support and IMDS v2
- ✅ **Microsoft.Identity.Client.Broker** - Updated from 4.77.1 to 4.79.0 with Android edge-to-edge support
- ✅ **Microsoft.Identity.Client.Extensions.Msal** - Updated from 4.77.1 to 4.79.0 with platform updates
- ✅ **Microsoft.Kiota.Abstractions** - Updated from 1.20.1 to 1.21.0 with new SetContentFromEnumCollection method
- ✅ **Microsoft.Kiota.Http.HttpClientLibrary** - Updated from 1.20.1 to 1.21.0 with backwards compatibility fixes
- ✅ **FluentValidation** - Updated from 12.0.0 to 12.1.0 with Tamil and Telugu language support
- ✅ **FluentValidation.DependencyInjectionExtensions** - Updated from 12.0.0 to 12.1.0
- ✅ **Spectre.Console** - Updated from 0.52.0 to 0.53.0

### Terraform Modules

- ✅ **azure-management/modules/resource_group** - Updated README documentation
- ✅ **azure-apim-policy** - Added comprehensive policy templates and examples

---

## 🐛 Bug Fixes

### Terraform Modules

- 🐛 **azure-apim-policy** - Fixed extraneous quotes in policy conditions

### Documentation

- 🐛 **settings-and-secrets.md** - Clarified that library name doesn't need to match project ID (but recommended)

---

## 📚 Documentation

### New Documentation

- 📖 [Forge History](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/docs/history.md) - Evolution and timeline of the Forge platform
- 📖 [Contributing Guide](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/docs/contributing/index.md) - Guides for platform developers
- 📖 [Presentations Index](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/docs/presentations/index.md) - Business and change management materials
- 📖 [Release Notes Index](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/docs/release-notes/index.md) - Version history and release tracking
- 📖 [Development Guides](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/docs/guides/development/index.md) - Developer guides and tutorials
- 📖 [Migration Guides](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/docs/guides/migration/index.md) - Version migration documentation
- 📖 [Security Guides](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/docs/guides/security/index.md) - Security best practices and guides
- 📖 [Environment Reference](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/docs/reference/environments/index.md) - Environment configuration reference
- 📖 [Security Reference](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/docs/reference/security/index.md) - Security architecture and patterns
- 📖 [Azure Architecture Diagrams](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/docs/diagrams/) - System design and architecture diagrams

### Updated Documentation

- 📝 [README](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/README.md) - Updated Forge documentation links
- 📝 [Settings and Secrets Guide](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/docs/guides/development/settings-and-secrets.md) - Clarified library naming conventions
- 📝 [Change Management Presentation](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/docs/presentations/202510-change-management.md) - Updated content

---

## 🔄 Breaking Changes

**None in this release** ✅

---

## 📋 Additional Notes

- **Total commits:** 54
- **Files changed:** 129 files (118 added, 10 modified, 1 deleted)
- **Contributors:**
  - Craig Palmquist (crapal@saif.com)
  - Jason Coria Corona Yue (jasyue@saif.com)
  - Emmitt Johnson (emmjoh@saif.com)
  - Brian Sheridan (brishe@saif.com)
  - Aaron Morgulis C (aarmor@saif.com)
  - Platform Build Service (automated dependency updates)

### Commit Statistics by Type

- 📝 **6** new features
- 🐛 **2** bug fixes
- 📚 **11** documentation updates
- 🔧 **18** dependency updates
- ♻️ **3** refactoring/maintenance
- 🔀 **14** merge commits

---

### Support

- 📧 Teams Support Channel: [Support](https://teams.microsoft.com/l/channel/19%3Acb611810fb0b42b080cfff5590bdd51c%40thread.tacv2/Support?groupId=514d2dac-2d62-48ce-bf99-0fa0ce39469c&tenantId=a86cb8ed-369b-4df5-ace5-43811f6e08cf)

---