コンテンツにスキップ
ドキュメントAspire を試す
ドキュメント試す

Azure Virtual Network

このコンテンツはまだ日本語訳がありません。

Azure Virtual Network logo

This article is the reference for the Aspire Azure Virtual Network integration. It enumerates the AppHost APIs — with examples for both AppHost.cs and apphost.mts — that you use to configure virtual networks, subnets, NAT gateways, network security groups (NSGs), private endpoints, and network security perimeters in your AppHost project.

Azure Virtual Network enables Azure resources to securely communicate with each other, the internet, and on-premises networks.

The Azure Virtual Network hosting integration models network resources as the following types:

  • AzureVirtualNetworkResource: Represents an Azure Virtual Network.
  • AzureSubnetResource: Represents a subnet within a virtual network.
  • AzureNetworkSecurityGroupResource: Represents a network security group for traffic control.
  • AzureNatGatewayResource: Represents a NAT gateway for deterministic outbound IP addresses.
  • AzurePublicIPAddressResource: Represents a public IP address.
  • AzureNetworkSecurityPerimeterResource: Represents an Azure Network Security Perimeter for PaaS service isolation.

To start building an Aspire app that uses Azure Virtual Network, install the 📦 Aspire.Hosting.Azure.Network NuGet package:

Terminal
aspire add azure-network

Learn more about aspire add in the command reference.

This updates your aspire.config.json with the Azure Network hosting integration package:

aspire.config.json
{
"packages": {
"Aspire.Hosting.Azure.Network": "13.5.3"
}
}

To add a virtual network, call AddAzureVirtualNetwork (or addAzureVirtualNetwork) on the builder instance:

apphost.mts
import { createBuilder } from './.aspire/modules/aspire.mjs';
const builder = await createBuilder();
const vnet = await builder.addAzureVirtualNetwork("vnet");
// After adding all resources, run the app...
await builder.build().run();

By default, the virtual network uses the address prefix 10.0.0.0/16. You can specify a custom address prefix:

apphost.mts
const vnet = await builder.addAzureVirtualNetwork('vnet', '10.1.0.0/16');

Call AddSubnet (or addSubnet) on the virtual network builder to add a subnet with a name and address prefix:

apphost.mts
const vnet = await builder.addAzureVirtualNetwork("vnet");
const subnet = vnet.addSubnet("my-subnet", "10.0.1.0/24");

You can add multiple subnets with different address ranges to a single virtual network. Subnet address prefixes must fall within the virtual network’s address space (for example, 10.0.1.0/24 is valid within a 10.0.0.0/16 network).

A NAT gateway provides deterministic outbound public IP addresses for subnet resources. Call AddNatGateway (or addNatGateway) to create a NAT gateway, then associate it with a subnet using WithNatGateway (or withNatGateway):

apphost.mts
const natGateway = await builder.addNatGateway("nat");
const vnet = await builder.addAzureVirtualNetwork("vnet");
const subnet = vnet.addSubnet("aca-subnet", "10.0.0.0/23")
.withNatGateway(natGateway);

By default, a public IP address is automatically created for the NAT gateway. To provide an explicit public IP address for full control, call AddPublicIPAddress (or addPublicIPAddress) and associate it with WithPublicIPAddress (or withPublicIPAddress):

apphost.mts
const pip = await builder.addPublicIPAddress('nat-pip');
const natGateway = await builder.addNatGateway('nat').withPublicIPAddress(pip);

For advanced settings like idle timeout or availability zones, use ConfigureInfrastructure.

Network security groups (NSGs) control inbound and outbound traffic flow on subnets. The integration provides two APIs for configuring NSGs: a shorthand API for common scenarios and an explicit API for full control.

The shorthand API uses fluent methods on subnet builders that automatically create an NSG, auto-increment priority, and auto-generate rule names:

apphost.mts
const vnet = await builder.addAzureVirtualNetwork("vnet");
const subnet = vnet.addSubnet("web", "10.0.1.0/24")
.allowInbound("443", "AzureLoadBalancer", undefined, "Tcp")
.denyInbound(undefined, "Internet");

The available shorthand methods are:

  • AllowInbound (or allowInbound) — Allow inbound traffic.
  • DenyInbound (or denyInbound) — Deny inbound traffic.
  • AllowOutbound (or allowOutbound) — Allow outbound traffic.
  • DenyOutbound (or denyOutbound) — Deny outbound traffic.

Priority auto-increments by 100 (100, 200, 300…) and rule names are auto-generated from the access, direction, port, and source (for example, allow-inbound-443-AzureLoadBalancer).

For full control over security rules, create a standalone NSG with AddNetworkSecurityGroup (or addNetworkSecurityGroup) on the builder and attach it to a subnet with WithNetworkSecurityGroup (or withNetworkSecurityGroup):

apphost.mts
import { createBuilder } from './.aspire/modules/aspire.mjs';
const builder = await createBuilder();
const vnet = await builder.addAzureVirtualNetwork("vnet");
const nsg = builder.addNetworkSecurityGroup("web-nsg")
.withSecurityRule({
name: "allow-https",
priority: 100,
direction: "Inbound",
access: "Allow",
protocol: "Tcp",
destinationPortRange: "443"
});
const subnet = vnet.addSubnet("web-subnet", "10.0.1.0/24")
.withNetworkSecurityGroup(nsg);

The AzureSecurityRule type provides sensible defaults—SourcePortRange, SourceAddressPrefix, and DestinationAddressPrefix all default to "*". The Name, Priority, Direction, Access, Protocol, and DestinationPortRange properties are required.

A single NSG can be shared across multiple subnets.

Compute environment integrations that support regional virtual network integration expose a WithDelegatedSubnet (or withDelegatedSubnet in TypeScript) extension method that assigns a subnet to the environment, enabling subnet delegation so the environment can inject its infrastructure. For example, Azure Container Apps and Azure App Service both support WithDelegatedSubnet:

apphost.mts
const vnet = await builder.addAzureVirtualNetwork("vnet");
const acaSubnet = await vnet.addSubnet("aca-subnet", "10.0.0.0/24");
const appServiceSubnet = await vnet.addSubnet("app-service-subnet", "10.0.1.0/24");
// Azure Container Apps environment
await builder.addAzureContainerAppEnvironment("aca-env")
.withDelegatedSubnet(acaSubnet);
// Azure App Service environment
await builder.addAzureAppServiceEnvironment("app-service-env")
.withDelegatedSubnet(appServiceSubnet);

Each compute environment delegates the subnet to its own Azure service (for example, App Service delegates to Microsoft.Web/serverFarms). Regional virtual network integration affects outbound traffic only—it doesn’t make ingress private and doesn’t enable Route All.

For scenarios that aren’t covered by a compute environment’s WithDelegatedSubnet helper, call WithServiceDelegation (or withServiceDelegation in TypeScript) directly on the subnet builder to delegate it to a supported Azure service. The delegation name defaults to serviceName so you don’t have to repeat the value:

apphost.mts
import { AzureSubnetServiceDelegations } from './.aspire/modules/aspire.mjs';
const vnet = await builder.addAzureVirtualNetwork("vnet");
const subnet = await vnet.addSubnet("aci-subnet", "10.0.0.0/23");
await subnet.withServiceDelegation(AzureSubnetServiceDelegations.ContainerInstances);
// Or specify a custom delegation name.
await subnet.withServiceDelegation(
AzureSubnetServiceDelegations.ContainerInstances,
{ name: "aci-delegation" });

AzureSubnetServiceDelegations provides discoverable, well-known service identifiers so you don’t have to remember or duplicate the underlying Azure resource provider strings:

ConstantValue
ContainerInstancesMicrosoft.ContainerInstance/containerGroups
ContainerAppEnvironmentsMicrosoft.App/environments
AppServiceEnvironmentsMicrosoft.Web/serverFarms
ApplicationGatewayForContainersMicrosoft.ServiceNetworking/trafficControllers

You can also pass another supported Azure resource provider path as serviceName if the service doesn’t have a well-known constant. Aspire models and emits one service delegation for a subnet, so use one compute-environment delegation helper or service delegation per subnet. Repeated direct WithServiceDelegation calls replace the previous service-delegation annotation, so the latest direct call wins. WithDelegatedSubnet allows an existing delegation for the same required service, but throws an InvalidOperationException when the subnet’s effective existing service delegation differs.

Private endpoints enable secure connectivity to Azure services over a private network. Call AddPrivateEndpoint (or addPrivateEndpoint) on a subnet builder and pass the Azure resource to connect to:

apphost.mts
const vnet = await builder.addAzureVirtualNetwork("vnet");
const peSubnet = vnet.addSubnet("private-endpoints", "10.0.2.0/24");
const storage = await builder.addAzureStorage("storage");
const blobs = storage.addBlobs("blobs");
peSubnet.addPrivateEndpoint(blobs);

When you add a private endpoint, the following resources are automatically created:

  1. A Private DNS Zone for the service (for example, privatelink.blob.core.windows.net).
  2. A Virtual Network Link connecting the DNS zone to your virtual network.
  3. A DNS Zone Group on the private endpoint for automatic DNS registration.
  4. The target resource is automatically configured to deny public network access.

The private DNS zone ensures that services within the virtual network automatically resolve the target resource’s hostname to its private IP address. Resources that reference the target (for example, via WithReference) use the same connection information—DNS resolution handles routing traffic over the private network.

To keep public access enabled on a resource that has a private endpoint, use ConfigureInfrastructure to override the automatic lockdown:

AppHost.cs
storage.ConfigureInfrastructure(infra =>
{
var storageAccount = infra.GetProvisionableResources()
.OfType<StorageAccount>()
.Single();
storageAccount.PublicNetworkAccess = StoragePublicNetworkAccess.Enabled;
});

Azure Service Bus requires the Premium tier to support private endpoints. When you add a private endpoint for a Service Bus resource, Aspire automatically sets the SKU to Premium.

Azure SQL Server uses a deployment script to grant your application’s managed identity access to the SQL database. When you add a private endpoint for a SQL Server resource, the deployment script needs to run inside the virtual network via Azure Container Instances (ACI). Aspire automatically creates a delegated subnet and a storage account for the deployment script container. For details on customizing this behavior, see Admin deployment script.

Azure Container Registry requires the Premium SKU to support private endpoints. When you add a private endpoint for an Azure Container Registry resource, Aspire automatically upgrades the SKU to Premium.

Azure Network Security Perimeters (NSPs) provide a logical security boundary for Azure PaaS services such as Storage, Key Vault, Cosmos DB, and SQL. Where virtual networks and private endpoints secure connectivity at the infrastructure layer, NSPs operate at the PaaS layer—grouping resources so they can communicate with each other while restricting public access via access rules.

NSPs complement private endpoints with a higher-level grouping model. Instead of configuring a private endpoint for every resource pair, you place all related PaaS resources inside a single perimeter. Resources within the perimeter communicate freely, and you define inbound and outbound access rules that apply to the entire boundary. This is useful when:

  • You have many PaaS resources that need to talk to each other but shouldn’t be publicly accessible.
  • You want a single set of access rules (IP ranges, subscription allow-lists, FQDN allow-lists) that apply uniformly to the group.
  • You want to audit traffic before enforcing restrictions by using Learning mode.

Call AddNetworkSecurityPerimeter (or addNetworkSecurityPerimeter) on the builder instance to create an NSP with a default profile:

apphost.mts
import { createBuilder } from './.aspire/modules/aspire.mjs';
const builder = await createBuilder();
const nsp = await builder.addNetworkSecurityPerimeter("my-nsp");
// After adding all resources, run the app...
await builder.build().run();

Access rules control traffic flowing into and out of the perimeter. Call WithAccessRule (or withAccessRule) and pass an AzureNspAccessRule to define a rule:

apphost.mts
const nsp = await builder.addNetworkSecurityPerimeter("my-nsp")
.withAccessRule({
name: "allow-my-ip",
direction: "Inbound",
addressPrefixes: ["203.0.113.0/24"]
})
.withAccessRule({
name: "allow-outbound-fqdn",
direction: "Outbound",
fullyQualifiedDomainNames: ["*.blob.core.windows.net"]
});

The following properties are available on AzureNspAccessRule:

PropertyDirectionDescription
AddressPrefixesInboundCIDR ranges allowed to reach the perimeter.
SubscriptionsInboundSubscription resource IDs (format: /subscriptions/{id}) allowed access.
FullyQualifiedDomainNamesOutboundFQDNs that resources inside the perimeter can communicate with.

Each property also has a corresponding *References variant (for example, AddressPrefixReferences) that accepts ReferenceExpression values resolved at deploy time.

Call WithNetworkSecurityPerimeter (or withNetworkSecurityPerimeter) on a PaaS resource builder to associate it with an NSP:

apphost.mts
const nsp = await builder.addNetworkSecurityPerimeter("my-nsp");
const storage = await builder.addAzureStorage("storage")
.withNetworkSecurityPerimeter(nsp);
const keyVault = await builder.addAzureKeyVault("kv")
.withNetworkSecurityPerimeter(nsp);

Once associated, resources within the perimeter can communicate with each other, while public access is governed by the perimeter’s access rules.

The following Azure resources support NSP association:

By default, associations use Enforced mode—resources within the perimeter can communicate with each other, and any public traffic that doesn’t match an access rule is blocked. You can switch to Learning mode to log violations without blocking traffic, which is helpful when onboarding resources to identify which access rules are needed before switching to enforced mode:

apphost.mts
// Enforced mode (default) — blocks traffic that violates the rules
storage.withNetworkSecurityPerimeter(nsp);
// Learning mode — logs violations without blocking
keyVault.withNetworkSecurityPerimeter(nsp, "Learning");

The following example demonstrates a complete network topology with a virtual network, subnets, NSG rules, a NAT gateway, private endpoints, and an Azure Container Apps environment:

apphost.mts
import { createBuilder } from './.aspire/modules/aspire.mjs';
const builder = await createBuilder();
// Create a virtual network with two subnets
const vnet = await builder.addAzureVirtualNetwork("vnet");
// Container Apps subnet with NSG rules and NAT gateway
const containerAppsSubnet = vnet.addSubnet("container-apps", "10.0.0.0/23")
.allowInbound({ port: "443", from: "AzureLoadBalancer", protocol: "Tcp" })
.denyInbound({ from: "VirtualNetwork" })
.denyInbound({ from: "Internet" });
const natGateway = await builder.addNatGateway("nat");
containerAppsSubnet.withNatGateway(natGateway);
// Private endpoints subnet
const peSubnet = vnet.addSubnet("private-endpoints", "10.0.2.0/27")
.allowInbound({ port: "443", from: "VirtualNetwork", protocol: "Tcp" })
.denyInbound({ from: "Internet" });
// Configure the Container App Environment to use the VNet.
await builder.addAzureContainerAppEnvironment("env")
.withDelegatedSubnet(containerAppsSubnet);
// Add storage with private endpoints
const storage = await builder.addAzureStorage("storage");
const blobs = storage.addBlobs("blobs");
const queues = storage.addQueues("queues");
peSubnet.addPrivateEndpoint(blobs);
peSubnet.addPrivateEndpoint(queues);
await builder.addProject("api", "../Api/Api.csproj")
.withExternalHttpEndpoints()
.withReference(blobs)
.withReference(queues);
await builder.build().run();