### Initialize Bicep RPC Client from an existing installation

Source: https://github.com/azure/bicep/blob/main/docs/bicep-rpc-client.md

This C# example demonstrates how to initialize the Bicep RPC Client using an existing local Bicep CLI installation by providing the direct path to the executable.

```csharp
var clientFactory = new BicepClientFactory(new HttpClient());

using var client = await clientFactory.InitializeFromPath(
    "/path/to/bicep", 
    cancellationToken);
```

--------------------------------

### Bicep Extension Host Setup (Program.cs)

Source: https://github.com/azure/bicep/blob/main/docs/experimental/local-deploy-dotnet-quickstart.md

Configures and starts the Bicep Local Extension host using ASP.NET Core, registering the extension and its resource handlers.

```csharp
using Microsoft.AspNetCore.Builder;
using Bicep.Local.Extension.Host.Extensions;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder();

builder.AddBicepExtensionHost(args);
builder.Services
    .AddBicepExtension(
        name: "MyExtension",
        version: "0.0.1",
        isSingleton: true,
        typeAssembly: typeof(Program).Assembly)
    .WithResourceHandler<MyResourceHandler>();

var app = builder.Build();

app.MapBicepExtension();

await app.RunAsync();
```

--------------------------------

### Initialize Bicep Client with Existing Installation

Source: https://github.com/azure/bicep/blob/main/src/Bicep.RpcClient/PACKAGE.md

Initializes the Bicep client using an existing Bicep CLI installation at a specified path.

```csharp
using var bicep = await factory.Initialize(new() {
    ExistingCliPath = "/usr/local/bin/bicep"
});
```

--------------------------------

### grpcurl Examples

Source: https://github.com/azure/bicep/blob/main/docs/experimental/local-deploy-dotnet-debugging-guide.md

Command-line examples using grpcurl to interact with the Bicep Local Extensibility RPC API.

```APIDOC
## Ping

### Description
Sends a ping request to the Bicep extension service.

### Command
```bash
grpcurl -plaintext localhost:5001 extension.BicepExtension/Ping
```

### Response Example
```
{}
```

## GetTypeFiles

### Description
Retrieves type definition files from the Bicep extension service.

### Command
```bash
grpcurl -plaintext localhost:5001 extension.BicepExtension/GetTypeFiles
```
```

--------------------------------

### Install Playwright

Source: https://github.com/azure/bicep/blob/main/src/Bicep.Playground.E2ETests/README.md

Installs Playwright dependencies. Run this once or when Playwright is updated.

```bash
dotnet build
pwsh ./bin/Debug/net10.0/playwright.ps1 install
```

--------------------------------

### Install Nightly Bicep CLI from Fork (Windows)

Source: https://github.com/azure/bicep/blob/main/docs/installing-nightly.md

Installs the nightly Bicep CLI from a specified GitHub fork repository.

```powershell
iex "& { $(irm https://aka.ms/bicep/nightly-cli.ps1) } -Repo anthony-c-martin/bicep"
```

--------------------------------

### Install grpcui (Windows/macOS)

Source: https://github.com/azure/bicep/blob/main/docs/experimental/local-deploy-dotnet-debugging-guide.md

Installs the grpcui tool, a web-based UI for interacting with gRPC services. Use this for a visual debugging experience.

```bash
choco install grpcui   # Windows
brew install grpcui    # macOS
```

--------------------------------

### Install Nightly Bicep CLI from Fork (Mac/Linux)

Source: https://github.com/azure/bicep/blob/main/docs/installing-nightly.md

Installs the nightly Bicep CLI from a specified GitHub fork repository.

```shell
bash <(curl -Ls https://aka.ms/bicep/nightly-cli.sh) --repo anthony-c-martin/bicep
```

--------------------------------

### grpcurl Ping Output Example

Source: https://github.com/azure/bicep/blob/main/docs/experimental/local-deploy-dotnet-debugging-guide.md

Example output for a successful Ping request to the BicepExtension service using grpcurl. Indicates the service is running and responding.

```bash
grpcurl -plaintext localhost:5001 extension.BicepExtension/Ping
# Output: {}
```

--------------------------------

### Quick Start: Run and Test Bicep Extension

Source: https://github.com/azure/bicep/blob/main/docs/experimental/local-deploy-dotnet-debugging-guide.md

Set up the environment, run the extension, and test its endpoints using grpcurl.

```bash
# 1. Set environment & start extension
export ASPNETCORE_ENVIRONMENT=Development
dotnet run --project ./MyExtension.csproj -- --http 5001

# 2. Verify it's running
grpcurl -plaintext localhost:5001 extension.BicepExtension/Ping

# 3. Test a request
grpcurl -plaintext -d '{"type":"MyResource","properties":"{}","config":"{}"}' \
  localhost:5001 extension.BicepExtension/CreateOrUpdate
```

--------------------------------

### Build the .NET Solution

Source: https://github.com/azure/bicep/blob/main/CONTRIBUTING.md

Build the entire .NET solution for Bicep. This command should be run from the repository root.

```bash
dotnet build
```

--------------------------------

### Empty Bicep Module Example

Source: https://github.com/azure/bicep/blob/main/src/Bicep.RegistryModuleTool.TestFixtures/Samples/NewlyGenerated/README.md

This is an empty Bicep module. It can be used as a starting point for creating new modules.

```bicep

```

--------------------------------

### Register Bicep Language with Highlight.js

Source: https://github.com/azure/bicep/blob/main/docs/highlighting.md

Example of how to register the Bicep language with highlight.js in a JavaScript project. Ensure highlight.js and the bicep plugin are installed.

```js
import hljs from 'highlight.js';
import bicep from './bicep.es.min';

hljs.registerLanguage('bicep', bicep);
```

--------------------------------

### Bicep Extension Operations

Source: https://github.com/azure/bicep/blob/main/docs/experimental/local-deploy-dotnet-debugging-guide.md

This section details the available operations for the Bicep extension, including CreateOrUpdate, Preview, Get, and Delete, along with example grpcurl commands.

```APIDOC
## CreateOrUpdate

### Description
Creates or updates a resource.

### Method
grpcurl

### Endpoint
localhost:5001 extension.BicepExtension/CreateOrUpdate

### Request Body
- **type** (string) - Required - The type of the resource.
- **properties** (string) - Required - JSON string representing the resource properties.
- **config** (string) - Required - JSON string representing the extension configuration.

### Request Example
```bash
grpcurl -plaintext -d '{
  "type": "echo",
  "properties": "{\"payload\": \"Hello, World!\"}",
  "config": "{}"
}' localhost:5001 extension.BicepExtension/CreateOrUpdate
```

### Response
#### Success Response (200)
- **resource** (object) - The created or updated resource.
  - **type** (string) - The type of the resource.
  - **identifiers** (string) - JSON string representing resource identifiers.
  - **properties** (string) - JSON string representing resource properties.

#### Response Example
```json
{
  "resource": {
    "type": "echo",
    "identifiers": "{}",
    "properties": "{\"payload\":\"Hello, World!\"}"
  }
}
```
```

```APIDOC
## Preview

### Description
Previews a resource operation.

### Method
grpcurl

### Endpoint
localhost:5001 extension.BicepExtension/Preview

### Request Body
- **type** (string) - Required - The type of the resource.
- **properties** (string) - Required - JSON string representing the resource properties.
- **config** (string) - Required - JSON string representing the extension configuration.

### Request Example
```bash
grpcurl -plaintext -d '{
  "type": "MyResource",
  "properties": "{\"name\": \"preview-test\"}",
  "config": "{}"
}' localhost:5001 extension.BicepExtension/Preview
```
```

```APIDOC
## Get

### Description
Retrieves a resource.

### Method
grpcurl

### Endpoint
localhost:5001 extension.BicepExtension/Get

### Request Body
- **type** (string) - Required - The type of the resource.
- **identifiers** (string) - Required - JSON string representing the resource identifiers.
- **config** (string) - Required - JSON string representing the extension configuration.

### Request Example
```bash
grpcurl -plaintext -d '{
  "type": "MyResource",
  "identifiers": "{\"name\": \"my-resource\"}",
  "config": "{}"
}' localhost:5001 extension.BicepExtension/Get
```
```

```APIDOC
## Delete

### Description
Deletes a resource.

### Method
grpcurl

### Endpoint
localhost:5001 extension.BicepExtension/Delete

### Request Body
- **type** (string) - Required - The type of the resource.
- **identifiers** (string) - Required - JSON string representing the resource identifiers.
- **config** (string) - Required - JSON string representing the extension configuration.

### Request Example
```bash
grpcurl -plaintext -d '{
  "type": "MyResource",
  "identifiers": "{\"name\": \"resource-to-delete\"}",
  "config": "{}"
}' localhost:5001 extension.BicepExtension/Delete
```
```

--------------------------------

### Preview Highlight.js Baseline HTML Files

Source: https://github.com/azure/bicep/blob/main/docs/highlighting.md

Launch an HTTP server to preview the baseline HTML files for the highlight.js plugin. Requires npx and http-server.

```sh
npx http-server ./src/highlightjs/test/baselines
```

--------------------------------

### Create Contributor Role Assignment

Source: https://github.com/azure/bicep/blob/main/src/highlightjs/test/baselines/issue5127.html

Assigns the Contributor role to a Service Principal using a generated GUID. The GUID is deterministic, ensuring the same GUID is generated for the same resource group.

```bicep
name: guid(contributorRoleDefinitionId, resourceGroup().id) // Create a GUID based on the role definition ID and scope (resource group ID). This will return the same GUID every time the template is deployed to the same resource group.
properties: {
  principalType: 'ServicePrincipal'
  roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', contributorRoleDefinitionId)
  principalId: managedIdentity.properties.principalId
  description: 'Grant the "Contributor" role to the user-assigned managed identity so it can access the storage account.'
}
```

--------------------------------

### Initialize Bicep Client with Configuration

Source: https://github.com/azure/bicep/blob/main/docs/bicep-rpc-client.md

Downloads and initializes the Bicep CLI with specified configuration options.

```APIDOC
## Initialize Bicep Client with Configuration

### Description
Downloads and initializes the Bicep CLI with specified configuration options. You can specify the version, installation path, target platform, and architecture.

### Method
`DownloadAndInitialize`

### Request Body
- **config** (`BicepClientConfiguration`) - Configuration options for the Bicep client.
  - **BicepVersion** (string, optional) - Version of Bicep to download (format: "x.y.z"). Defaults to the latest version if not specified.
  - **InstallPath** (string, optional) - Custom installation path for Bicep binaries. Defaults to "~/.bicep/bin".
  - **OsPlatform** (`OSPlatform`, optional) - Target OS platform (for cross-platform scenarios). Defaults to the current OS.
  - **Architecture** (`Architecture`, optional) - Target architecture (for cross-architecture scenarios). Defaults to the current architecture.
- **cancellationToken** (`CancellationToken`) - A token to observe for cancellation requests.
```

--------------------------------

### Add Azure.Bicep.RpcClient Package

Source: https://github.com/azure/bicep/blob/main/src/Bicep.RpcClient/PACKAGE.md

Install the Azure.Bicep.RpcClient NuGet package using the .NET CLI.

```bash
dotnet add package Azure.Bicep.RpcClient
```

--------------------------------

### Install Nightly Bicep CLI from Custom Branch (Windows)

Source: https://github.com/azure/bicep/blob/main/docs/installing-nightly.md

Installs the nightly Bicep CLI from a specified custom branch.

```powershell
iex "& { $(irm https://aka.ms/bicep/nightly-cli.ps1) } -Branch jeskew/variable-imports"
```

--------------------------------

### Configure Bicep Client Initialization

Source: https://github.com/azure/bicep/blob/main/docs/bicep-rpc-client.md

Demonstrates all available configuration options for the BicepClientConfiguration class, including version, installation path, target platform, and architecture.

```csharp
var config = new BicepClientConfiguration
{
    // Version of Bicep to download (format: "x.y.z")
    // If not specified, downloads the latest version
    BicepVersion = "0.38.3",
    
    // Custom installation path for Bicep binaries
    // Default: ~/.bicep/bin
    InstallPath = "/custom/path/to/bicep",
    
    // Target OS platform (for cross-platform scenarios)
    // Default: Current OS
    OsPlatform = OSPlatform.Linux,
    
    // Target architecture (for cross-architecture scenarios)
    // Default: Current architecture
    Architecture = Architecture.X64
};

using var client = await clientFactory.DownloadAndInitialize(config, cancellationToken);
```

--------------------------------

### Install Nightly Bicep CLI from Custom Branch (Mac/Linux)

Source: https://github.com/azure/bicep/blob/main/docs/installing-nightly.md

Installs the nightly Bicep CLI from a specified custom branch.

```shell
bash <(curl -Ls https://aka.ms/bicep/nightly-cli.sh) --branch jeskew/variable-imports
```

--------------------------------

### Command Line: Set Environment Variables and Run (Bash)

Source: https://github.com/azure/bicep/blob/main/docs/experimental/local-deploy-dotnet-debugging-guide.md

Set development environment variables and run the Bicep extension using dotnet run in Bash.

```bash
# macOS/Linux
export ASPNETCORE_ENVIRONMENT=Development
export BICEP_TRACING_ENABLED=true
dotnet run --project ./MyExtension.csproj -- --http 5001
```

--------------------------------

### Configure Test Project with .NET SDK

Source: https://github.com/azure/bicep/blob/main/docs/experimental/local-deploy-dotnet-unittesting-guide.md

Set up the .csproj file for a Bicep extension unit test project. Includes necessary SDK, project references, and NuGet package references for testing.

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <IsPackable>false</IsPackable>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\YourExtension\YourExtension.csproj" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" />
    <PackageReference Include="MSTest.TestAdapter" />
    <PackageReference Include="MSTest.TestFramework" />
    <PackageReference Include="Moq" />
    <PackageReference Include="FluentAssertions" />
  </ItemGroup>
</Project>
```

--------------------------------

### Preview Textmate Grammar Baselines

Source: https://github.com/azure/bicep/blob/main/docs/highlighting.md

Launch an HTTP server to preview the Textmate grammar baselines in a browser. This command requires npx and http-server.

```sh
npx http-server ./src/textmate/test/baselines
```

--------------------------------

### Initialize Bicep Client with Default Configuration

Source: https://github.com/azure/bicep/blob/main/src/Bicep.RpcClient/PACKAGE.md

Initializes the Bicep client, automatically downloading and connecting to the latest Bicep CLI. Binaries are cached under ~/.bicep/bin.

```csharp
using Bicep.RpcClient;

var factory = new BicepClientFactory();

// Download (or reuse) the latest Bicep CLI and connect
using var bicep = await factory.Initialize(BicepClientConfiguration.Default);
```

--------------------------------

### Install Nightly VS Code Extension from Custom Branch (Windows)

Source: https://github.com/azure/bicep/blob/main/docs/installing-nightly.md

Installs the nightly VSCode extension from a specified custom branch.

```powershell
iex "& { $(irm https://aka.ms/bicep/nightly-vsix.ps1) } -Branch jeskew/variable-imports"
```

--------------------------------

### Install Nightly Bicep CLI (Mac/Linux)

Source: https://github.com/azure/bicep/blob/main/docs/installing-nightly.md

Installs the latest nightly Bicep CLI binary to ~/.azure/bin/bicep using a bash script. Requires GitHub CLI.

```shell
bash <(curl -Ls https://aka.ms/bicep/nightly-cli.sh)
```