Add AzureServiceTags with common Azure service tags for NSG rules

.github/skills/startup-perf/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: startup-perf
+description: Measures Aspire application startup performance using dotnet-trace and the TraceAnalyzer tool. Use this when asked to measure impact of a code change on Aspire application startup performance.
+---
+
+# Aspire Startup Performance Measurement
+
+This skill provides patterns and practices for measuring .NET Aspire application startup performance using the `Measure-StartupPerformance.ps1` script and the companion `TraceAnalyzer` tool.
+
+## Overview
+
+The startup performance tooling collects `dotnet-trace` traces from an Aspire AppHost application and computes the startup duration from `AspireEventSource` events. Specifically, it measures the time between the `DcpModelCreationStart` (event ID 17) and `DcpModelCreationStop` (event ID 18) events emitted by the `Microsoft-Aspire-Hosting` EventSource provider.
+
+**Script Location**: `tools/perf/Measure-StartupPerformance.ps1`
+**TraceAnalyzer Location**: `tools/perf/TraceAnalyzer/`
+**Documentation**: `docs/getting-perf-traces.md`
+
+## Prerequisites
+
+- PowerShell 7+
+- `dotnet-trace` global tool (`dotnet tool install -g dotnet-trace`)
+- .NET SDK (restored via `./restore.cmd` or `./restore.sh`)
+
+## Quick Start
+
+### Single Measurement
+
+```powershell
+# From repository root — measures the default TestShop.AppHost
+.\tools\perf\Measure-StartupPerformance.ps1
+```
+
+### Multiple Iterations with Statistics
+
+```powershell
+.\tools\perf\Measure-StartupPerformance.ps1 -Iterations 5
+```
+
+### Custom Project
+
+```powershell
+.\tools\perf\Measure-StartupPerformance.ps1 -ProjectPath "path\to\MyApp.AppHost.csproj" -Iterations 3
+```
+
+### Preserve Traces for Manual Analysis
+
+```powershell
+.\tools\perf\Measure-StartupPerformance.ps1 -Iterations 3 -PreserveTraces -TraceOutputDirectory "C:\traces"
+```
+
+### Verbose Output
+
+```powershell
+.\tools\perf\Measure-StartupPerformance.ps1 -Verbose
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `ProjectPath` | TestShop.AppHost | Path to the AppHost `.csproj` to measure |
+| `Iterations` | 1 | Number of measurement runs (1–100) |
+| `PreserveTraces` | `$false` | Keep `.nettrace` files after analysis |
+| `TraceOutputDirectory` | temp folder | Directory for preserved trace files |
+| `SkipBuild` | `$false` | Skip `dotnet build` before running |
+| `TraceDurationSeconds` | 60 | Maximum trace collection time (1–86400) |
+| `PauseBetweenIterationsSeconds` | 45 | Pause between iterations (0–3600) |
+| `Verbose` | `$false` | Show detailed output |
+
+## How It Works
+
+The script follows this sequence:
+
+1. **Prerequisites check** — Verifies `dotnet-trace` is installed and the project exists.
+2. **Build** — Builds the AppHost project in Release configuration (unless `-SkipBuild`).
+3. **Build TraceAnalyzer** — Builds the companion `tools/perf/TraceAnalyzer` project.
+4. **For each iteration:**
+   a. Locates the compiled executable (Arcade-style or traditional output paths).
+   b. Reads `launchSettings.json` for environment variables.
+   c. Launches the AppHost as a separate process.
+   d. Attaches `dotnet-trace` to the running process with the `Microsoft-Aspire-Hosting` provider.
+   e. Waits for the trace to complete (duration timeout or process exit).
+   f. Runs the TraceAnalyzer to extract the startup duration from the `.nettrace` file.
+   g. Cleans up processes.
+5. **Reports results** — Prints per-iteration times and statistics (min, max, average, std dev).
+
+## TraceAnalyzer Tool
+
+The `tools/perf/TraceAnalyzer` is a small .NET console app that parses `.nettrace` files using the `Microsoft.Diagnostics.Tracing.TraceEvent` library.
+
+### What It Does
+
+- Opens the `.nettrace` file with `EventPipeEventSource`
+- Listens for events from the `Microsoft-Aspire-Hosting` provider
+- Extracts timestamps for `DcpModelCreationStart` (ID 17) and `DcpModelCreationStop` (ID 18)
+- Outputs the duration in milliseconds (or `"null"` if events are not found)
+
+### Standalone Usage
+
+```bash
+dotnet run --project tools/perf/TraceAnalyzer -c Release -- <path-to-nettrace-file>
+```
+
+## Understanding Output
+
+### Successful Run
+
+```
+==================================================
+ Aspire Startup Performance Measurement
+==================================================
+
+Project: TestShop.AppHost
+Iterations: 3
+...
+
+Iteration 1
+----------------------------------------
+Starting TestShop.AppHost...
+Attaching trace collection to PID 12345...
+Collecting performance trace...
+Trace collection completed.
+Analyzing trace: ...
+Startup time: 1234.56 ms
+
+...
+
+==================================================
+ Results Summary
+==================================================
+
+Iteration StartupTimeMs
+--------- -------------
+        1       1234.56
+        2       1189.23
+        3       1201.45
+
+Statistics:
+  Successful iterations: 3 / 3
+  Minimum: 1189.23 ms
+  Maximum: 1234.56 ms
+  Average: 1208.41 ms
+  Std Dev: 18.92 ms
+```
+
+### Common Issues
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `dotnet-trace is not installed` | Missing global tool | Run `dotnet tool install -g dotnet-trace` |
+| `Could not find compiled executable` | Project not built | Remove `-SkipBuild` or build manually |
+| `Could not find DcpModelCreation events` | Trace too short or events not emitted | Increase `-TraceDurationSeconds` |
+| `Application exited immediately` | App crash on startup | Check app logs, ensure dependencies are available |
+| `dotnet-trace exited with code != 0` | Trace collection error | Check verbose output; trace file may still be valid |
+
+## Comparing Before/After Performance
+
+To measure the impact of a code change:
+
+```powershell
+# 1. Measure baseline (on main branch)
+git checkout main
+.\tools\perf\Measure-StartupPerformance.ps1 -Iterations 5 -PreserveTraces -TraceOutputDirectory "C:\traces\baseline"
+
+# 2. Measure with changes
+git checkout my-feature-branch
+.\tools\perf\Measure-StartupPerformance.ps1 -Iterations 5 -PreserveTraces -TraceOutputDirectory "C:\traces\feature"
+
+# 3. Compare the reported averages and std devs
+```
+
+Use enough iterations (5+) and a consistent pause between iterations for reliable comparisons.
+
+## Collecting Traces for Manual Analysis
+
+If you need to inspect trace files manually (e.g., in PerfView or Visual Studio):
+
+```powershell
+.\tools\perf\Measure-StartupPerformance.ps1 -PreserveTraces -TraceOutputDirectory "C:\my-traces"
+```
+
+See `docs/getting-perf-traces.md` for guidance on analyzing traces with PerfView or `dotnet trace report`.
+
+## EventSource Provider Details
+
+The `Microsoft-Aspire-Hosting` EventSource emits events for key Aspire lifecycle milestones. The startup performance script focuses on:
+
+| Event ID | Event Name | Description |
+|----------|------------|-------------|
+| 17 | `DcpModelCreationStart` | Marks the beginning of DCP model creation |
+| 18 | `DcpModelCreationStop` | Marks the completion of DCP model creation |
+
+The measured startup time is the wall-clock difference between these two events, representing the time to create all application services and supporting dependencies.

AGENTS.md

@@ -355,6 +355,7 @@ The following specialized skills are available in `.github/skills/`:
 - **test-management**: Quarantines or disables flaky/problematic tests using the QuarantineTools utility
 - **connection-properties**: Expert for creating and improving Connection Properties in Aspire resources
 - **dependency-update**: Guides dependency version updates by checking nuget.org, triggering the dotnet-migrate-package Azure DevOps pipeline, and monitoring runs
+- **startup-perf**: Measures Aspire application startup performance using dotnet-trace and the TraceAnalyzer tool
 
 ## Pattern-Based Instructions
 

docs/getting-perf-traces.md

@@ -28,8 +28,16 @@ Once you are ready, hit "Start Collection" button and run your scenario.
 
 When done with the scenario, hit "Stop Collection". Wait for PerfView to finish merging and analyzing data (the "working" status bar stops flashing).
 
-### Verify that the trace contains Aspire data
+### Verify that PerfView trace contains Aspire data
 
 This is an optional step, but if you are wondering if your trace has been captured properly, you can check the following:
 
 1. Open the trace (usually named PerfViewData.etl, if you haven't changed the name) and double click Events view. Verify you have a bunch of events from the Microsoft-Aspire-Hosting provider.
+
+## Profiling scripts
+
+The `tools/perf` folder in the repository contains scripts that help quickly assess the impact of code changes on key performance scenarios. Currently available scripts are:
+
+| Script | Description |
+| --- | --------- |
+| `Measure-StartupPerformance.ps1` | Measures startup time for a specific Aspire project. More specifically, the script measures the time to get all application services and supporting dependencies CREATED; the application is not necessarily responsive after measured time. |

src/Aspire.Hosting.Azure.Network/AzureServiceTags.cs

@@ -0,0 +1,111 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Aspire.Hosting.Azure;
+
+/// <summary>
+/// Provides well-known Azure service tags that can be used as source or destination address prefixes
+/// in network security group rules.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Service tags represent a group of IP address prefixes from a given Azure service. Microsoft manages the
+/// address prefixes encompassed by each tag and automatically updates them as addresses change.
+/// </para>
+/// <para>
+/// These tags can be used with the <c>from</c> and <c>to</c> parameters of methods such as
+/// <see cref="AzureVirtualNetworkExtensions.AllowInbound"/>, <see cref="AzureVirtualNetworkExtensions.DenyInbound"/>,
+/// <see cref="AzureVirtualNetworkExtensions.AllowOutbound"/>, <see cref="AzureVirtualNetworkExtensions.DenyOutbound"/>,
+/// or with the <see cref="AzureSecurityRule.SourceAddressPrefix"/> and <see cref="AzureSecurityRule.DestinationAddressPrefix"/> properties.
+/// </para>
+/// </remarks>
+/// <example>
+/// Use service tags when configuring network security rules:
+/// <code>
+/// var subnet = vnet.AddSubnet("web", "10.0.1.0/24")
+///     .AllowInbound(port: "443", from: AzureServiceTags.AzureLoadBalancer, protocol: SecurityRuleProtocol.Tcp)
+///     .DenyInbound(from: AzureServiceTags.Internet);
+/// </code>
+/// </example>
+public static class AzureServiceTags
+{
+    /// <summary>
+    /// Represents the Internet address space, including all publicly routable IP addresses.
+    /// </summary>
+    public const string Internet = nameof(Internet);
+
+    /// <summary>
+    /// Represents the address space for the virtual network, including all connected address spaces,
+    /// all connected on-premises address spaces, and peered virtual networks.
+    /// </summary>
+    public const string VirtualNetwork = nameof(VirtualNetwork);
+
+    /// <summary>
+    /// Represents the Azure infrastructure load balancer. This tag is commonly used to allow
+    /// health probe traffic from Azure.
+    /// </summary>
+    public const string AzureLoadBalancer = nameof(AzureLoadBalancer);
+
+    /// <summary>
+    /// Represents Azure Traffic Manager probe IP addresses.
+    /// </summary>
+    public const string AzureTrafficManager = nameof(AzureTrafficManager);
+
+    /// <summary>
+    /// Represents the Azure Storage service. This tag does not include specific Storage accounts;
+    /// it covers all Azure Storage IP addresses.
+    /// </summary>
+    public const string Storage = nameof(Storage);
+
+    /// <summary>
+    /// Represents Azure SQL Database, Azure Database for MySQL, Azure Database for PostgreSQL,
+    /// Azure Database for MariaDB, and Azure Synapse Analytics.
+    /// </summary>
+    public const string Sql = nameof(Sql);
+
+    /// <summary>
+    /// Represents Azure Cosmos DB service addresses.
+    /// </summary>
+    public const string AzureCosmosDB = nameof(AzureCosmosDB);
+
+    /// <summary>
+    /// Represents Azure Key Vault service addresses.
+    /// </summary>
+    public const string AzureKeyVault = nameof(AzureKeyVault);
+
+    /// <summary>
+    /// Represents Azure Event Hubs service addresses.
+    /// </summary>
+    public const string EventHub = nameof(EventHub);
+
+    /// <summary>
+    /// Represents Azure Service Bus service addresses.
+    /// </summary>
+    public const string ServiceBus = nameof(ServiceBus);
+
+    /// <summary>
+    /// Represents Azure Container Registry service addresses.
+    /// </summary>
+    public const string AzureContainerRegistry = nameof(AzureContainerRegistry);
+
+    /// <summary>
+    /// Represents Azure App Service and Azure Functions service addresses.
+    /// </summary>
+    public const string AppService = nameof(AppService);
+
+    /// <summary>
+    /// Represents Microsoft Entra ID (formerly Azure Active Directory) service addresses.
+    /// </summary>
+    public const string AzureActiveDirectory = nameof(AzureActiveDirectory);
+
+    /// <summary>
+    /// Represents Azure Monitor service addresses, including Log Analytics, Application Insights,
+    /// and Azure Monitor metrics.
+    /// </summary>
+    public const string AzureMonitor = nameof(AzureMonitor);
+
+    /// <summary>
+    /// Represents the Gateway Manager service, used for VPN Gateway and Application Gateway management traffic.
+    /// </summary>
+    public const string GatewayManager = nameof(GatewayManager);
+}

tests/Aspire.Hosting.Azure.Tests/AzureVirtualNetworkExtensionsTests.cs

@@ -361,6 +361,66 @@ await Verify(vnetManifest.BicepText, extension: "bicep")
             .AppendContentAsFile(nsgManifest.BicepText, "bicep", "nsg");
     }
 
+    [Fact]
+    public void ServiceTags_CanBeUsedAsFromAndToParameters()
+    {
+        using var builder = TestDistributedApplicationBuilder.Create(DistributedApplicationOperation.Publish);
+
+        var vnet = builder.AddAzureVirtualNetwork("myvnet");
+        var subnet = vnet.AddSubnet("web", "10.0.1.0/24")
+            .AllowInbound(port: "443", from: AzureServiceTags.AzureLoadBalancer, protocol: SecurityRuleProtocol.Tcp)
+            .DenyInbound(from: AzureServiceTags.Internet)
+            .AllowOutbound(port: "443", to: AzureServiceTags.Storage)
+            .DenyOutbound(to: AzureServiceTags.VirtualNetwork);
+
+        var rules = subnet.Resource.NetworkSecurityGroup!.SecurityRules;
+        Assert.Equal(4, rules.Count);
+
+        Assert.Equal("AzureLoadBalancer", rules[0].SourceAddressPrefix);
+        Assert.Equal("Internet", rules[1].SourceAddressPrefix);
+        Assert.Equal("Storage", rules[2].DestinationAddressPrefix);
+        Assert.Equal("VirtualNetwork", rules[3].DestinationAddressPrefix);
+    }
+
+    [Fact]
+    public void ServiceTags_CanBeUsedInSecurityRuleProperties()
+    {
+        var rule = new AzureSecurityRule
+        {
+            Name = "allow-https-from-lb",
+            Priority = 100,
+            Direction = SecurityRuleDirection.Inbound,
+            Access = SecurityRuleAccess.Allow,
+            Protocol = SecurityRuleProtocol.Tcp,
+            SourceAddressPrefix = AzureServiceTags.AzureLoadBalancer,
+            DestinationAddressPrefix = AzureServiceTags.VirtualNetwork,
+            DestinationPortRange = "443"
+        };
+
+        Assert.Equal("AzureLoadBalancer", rule.SourceAddressPrefix);
+        Assert.Equal("VirtualNetwork", rule.DestinationAddressPrefix);
+    }
+
+    [Fact]
+    public void ServiceTags_HaveExpectedValues()
+    {
+        Assert.Equal("Internet", AzureServiceTags.Internet);
+        Assert.Equal("VirtualNetwork", AzureServiceTags.VirtualNetwork);
+        Assert.Equal("AzureLoadBalancer", AzureServiceTags.AzureLoadBalancer);
+        Assert.Equal("AzureTrafficManager", AzureServiceTags.AzureTrafficManager);
+        Assert.Equal("Storage", AzureServiceTags.Storage);
+        Assert.Equal("Sql", AzureServiceTags.Sql);
+        Assert.Equal("AzureCosmosDB", AzureServiceTags.AzureCosmosDB);
+        Assert.Equal("AzureKeyVault", AzureServiceTags.AzureKeyVault);
+        Assert.Equal("EventHub", AzureServiceTags.EventHub);
+        Assert.Equal("ServiceBus", AzureServiceTags.ServiceBus);
+        Assert.Equal("AzureContainerRegistry", AzureServiceTags.AzureContainerRegistry);
+        Assert.Equal("AppService", AzureServiceTags.AppService);
+        Assert.Equal("AzureActiveDirectory", AzureServiceTags.AzureActiveDirectory);
+        Assert.Equal("AzureMonitor", AzureServiceTags.AzureMonitor);
+        Assert.Equal("GatewayManager", AzureServiceTags.GatewayManager);
+    }
+
     [Fact]
     public void AllFourDirectionAccessCombos_SetCorrectly()
     {