From 60aa0cb28f3948b6cb07551c7161f2a1105b0ee2 Mon Sep 17 00:00:00 2001 From: Arcturus Zhang Date: Mon, 20 Oct 2025 15:21:27 +0800 Subject: [PATCH 1/2] add some documents about bicepvalue --- sdk/provisioning/Azure.Provisioning/README.md | 113 +++++++++++++++++- 1 file changed, 110 insertions(+), 3 deletions(-) diff --git a/sdk/provisioning/Azure.Provisioning/README.md b/sdk/provisioning/Azure.Provisioning/README.md index b878fb2fa3fb..63105cda69a0 100644 --- a/sdk/provisioning/Azure.Provisioning/README.md +++ b/sdk/provisioning/Azure.Provisioning/README.md @@ -1,6 +1,6 @@ # Azure Provisioning client library for .NET -Azure.Provisioning makes it easy to declaratively specify Azure infrastructure natively in .NET. +`Azure.Provisioning` makes it easy to declaratively specify Azure infrastructure natively in .NET. ## Getting started @@ -20,13 +20,120 @@ dotnet add package Azure.Provisioning ## Key concepts -This library allows you to specify your infrastructure in a declarative style using dotnet. You can then use azd to deploy your infrastructure to Azure directly without needing to write or maintain bicep or arm templates. +This library allows you to specify your infrastructure in a declarative style using dotnet. You can then use `azd` to deploy your infrastructure to Azure directly without needing to write or maintain `bicep` or arm templates. + +### `BicepValue` types + +`BicepValue` types are the foundation of `Azure.Provisioning`, providing a flexible type system that can represent literal .NET values, Bicep expressions, or unset properties. These types enable strongly-typed infrastructure definition while maintaining the flexibility needed for dynamic resource configuration. + +#### Core `BicepValue` Types + +**`BicepValue`** - Represents a strongly-typed value that can be: +- A literal .NET value of type `T` +- A Bicep expression that evaluates to type `T` +- An unset value (can be assigned later) + +```csharp +// Literal value +BicepValue literalName = "my-storage-account"; + +// Expression value +BicepValue expressionName = BicepFunction.CreateGuid(); + +// Unset value (can be assigned later) +BicepValue unsetName = new(); +``` + +**`BicepList`** - Represents a collection of `BicepValue` items that can be: +- A list of literal values +- A Bicep expression that evaluates to an array +- An unset list + +```csharp +// Literal list +BicepList tagNames = new() { "Environment", "Project", "Owner" }; + +// Expression list (referencing a parameter) +BicepList dynamicTags = parameterReference; + +// Adding items +tagNames.Add("CostCenter"); +``` + +**`BicepDictionary`** - Represents a key-value collection where values are `BicepValue`: +- A dictionary of literal key-value pairs +- A Bicep expression that evaluates to an object +- An unset dictionary + +```csharp +// Literal dictionary +BicepDictionary tags = new() +{ + ["Environment"] = "Production", + ["Project"] = "WebApp", + ["Owner"] = "DevTeam" +}; + +// Expression dictionary +BicepDictionary dynamicTags = parameterReference; + +// Accessing values +tags["CostCenter"] = "12345"; +``` + +#### Working with Azure Resources + +**`ProvisionableConstruct`** - Base class for infrastructure components that group related properties and resources. Most users will work with concrete implementations like `StorageAccount`, `VirtualNetwork`, etc. + +**`ProvisionableResource`** - Base class for Azure resources that provides resource-specific functionality. Users typically work with specific resource types like `StorageAccount`, `VirtualMachine`, `AppService`, etc. + +Here's how you use the provided Azure resource classes: + +```csharp +// Create a storage account with BicepValue properties +StorageAccount storage = new("myStorage", StorageAccount.ResourceVersions.V2023_01_01) +{ + // Set literal values + Name = "mystorageaccount", + Kind = StorageKind.StorageV2, + + // Use BicepValue for dynamic configuration + Location = locationParameter, // Reference a parameter + + // Configure nested properties + Sku = new StorageSku + { + Name = StorageSkuName.StandardLrs + }, + + // Use BicepList for collections + Tags = new BicepDictionary + { + ["Environment"] = "Production", + ["Project"] = environmentParameter // Mix literal and dynamic values + } +}; + +// Access output properties (these are BicepValue that reference the deployed resource) +BicepValue storageAccountId = storage.Id; +BicepValue primaryBlobEndpoint = storage.PrimaryEndpoints.BlobUri; + +// Reference properties in other resources +var appService = new AppService("myApp") +{ + // Reference the storage account's connection string + ConnectionStrings = new BicepDictionary + { + ["Storage"] = BicepFunction.Interpolate($"DefaultEndpointsProtocol=https;AccountName={storage.Name};AccountKey={storage.GetKeys().Value[0].Value}") + } +}; +``` ## Examples ### Create Basic Infrastructure -This example demonstrates how to create basic Azure infrastructure using the Azure Provisioning framework, including a storage account with blob services and output values. +This example demonstrates how to create basic Azure infrastructure using the `Azure.Provisioning` framework, including a storage account with blob services and output values. ```C# Snippet:ProvisioningBasic Infrastructure infra = new(); From b4f6aed978336d95f4018c8428b149cf339a9cb7 Mon Sep 17 00:00:00 2001 From: Arcturus Zhang Date: Mon, 20 Oct 2025 15:27:06 +0800 Subject: [PATCH 2/2] some refinement --- sdk/provisioning/Azure.Provisioning/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/sdk/provisioning/Azure.Provisioning/README.md b/sdk/provisioning/Azure.Provisioning/README.md index 63105cda69a0..d4b6257b2b9f 100644 --- a/sdk/provisioning/Azure.Provisioning/README.md +++ b/sdk/provisioning/Azure.Provisioning/README.md @@ -31,7 +31,7 @@ This library allows you to specify your infrastructure in a declarative style us **`BicepValue`** - Represents a strongly-typed value that can be: - A literal .NET value of type `T` - A Bicep expression that evaluates to type `T` -- An unset value (can be assigned later) +- An unset value (usually one should get this state from the property of a constructed resource/construct) ```csharp // Literal value @@ -41,13 +41,13 @@ BicepValue literalName = "my-storage-account"; BicepValue expressionName = BicepFunction.CreateGuid(); // Unset value (can be assigned later) -BicepValue unsetName = new(); +BicepValue unsetName = storageAccount.Name; ``` **`BicepList`** - Represents a collection of `BicepValue` items that can be: - A list of literal values - A Bicep expression that evaluates to an array -- An unset list +- An unset list (usually one should get this state from the property of a constructed resource/construct) ```csharp // Literal list @@ -63,7 +63,7 @@ tagNames.Add("CostCenter"); **`BicepDictionary`** - Represents a key-value collection where values are `BicepValue`: - A dictionary of literal key-value pairs - A Bicep expression that evaluates to an object -- An unset dictionary +- An unset dictionary (usually one should get this state from the property of a constructed resource/construct) ```csharp // Literal dictionary @@ -83,9 +83,9 @@ tags["CostCenter"] = "12345"; #### Working with Azure Resources -**`ProvisionableConstruct`** - Base class for infrastructure components that group related properties and resources. Most users will work with concrete implementations like `StorageAccount`, `VirtualNetwork`, etc. +**`ProvisionableResource`** - Base class for Azure resources that provides resource-specific functionality. Users typically work with specific resource types like `StorageAccount`, `VirtualMachine`, `AppService`, etc. An instance of type `ProvisionableResource` corresponds to a resource statement in `bicep` language. -**`ProvisionableResource`** - Base class for Azure resources that provides resource-specific functionality. Users typically work with specific resource types like `StorageAccount`, `VirtualMachine`, `AppService`, etc. +**`ProvisionableConstruct`** - Base class for infrastructure components that group related properties and resources. Most users will work with concrete implementations like `StorageAccountSku`, `VirtualNetworkIPConfiguration`, etc. An instance of type `ProvisionableConstruct` usually corresponds to an object definition statement in `bicep` language. Here's how you use the provided Azure resource classes: