Skip to content

Azure-Samples/orleans-url-shortener

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

8 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

page_type languages products urlFragment name description
sample
azdeveloper
aspx-csharp
csharp
bicep
azure
azure-cosmos-db
azure-container-apps
azure-table-storage
azure-storage
azure-container-registry
aspnet-core
template
URL Shortener using Microsoft Orleans and Azure for hosting and data
An ASP.NET Core 8.0 web application to illustrate basic Microsoft Orleans concepts; such as working with Grains, Silos, and persistent state. Uses Azure Developer CLI (azd) to build, deploy, and monitor.

URL Shortener using Microsoft Orleans and Azure for hosting and data

Microsoft Learn Quickstart Open in GitHub Codespaces Open in Dev Container

This is an ASP.NET Core 8.0 web application to illustrate basic Microsoft Orleans concepts; such as working with Grains, Silos, and persistent state. This web application can be configured to work with in-memory, Azure Cosmos DB for NoSQL, or Azure Table Storage data persistence options. The web application is designed to be hosted using a Docker container in Azure Contianer Apps.

When you are finished, you will have a simple URL shortner utilty web application deployed to Azure.

Prerequisites

This template will create infrastructure and deploy code to Azure. If you don't have an Azure Subscription, you can sign up for a free account here. Make sure you have the contributor role in the Azure subscription.

The following prerequisites are required to use this template. Please ensure that you have them all installed locally.

Quickstart

To learn how to get started with any template, follow the steps in this Microsoft Orleans quickstart with this template (orleans-url-shortener).

This quickstart will show you how to authenticate on Azure, initialize the template, implement data storage in Azure, provision infrastructure, and deploy code on Azure via the following commands:

# Log in to azd. Only required once per-install.
azd auth login

# First-time project setup. Initialize a project in the current directory, using this template.
# Omit the --template argument if you are running in a development container.
azd init --template orleans-url-shortener

# Provision and deploy to Azure
azd up

Deploying Azure Table Storage and Azure Cosmos DB for NoSQL

Azure data persistence is opt-in for this template. By default, the template will not deploy and Azure data service. Follow these steps to configure data persistence in Azure.

  1. To deploy an Azure data service, configure the DEPLOY_AZURE_COSMOS_DB_NOSQL or DEPLOY_AZURE_TABLE_STORAGE environment variables. By default, these environment variables are set to false.

    # Enables deployment of Azure Cosmos DB for NoSQL resource
    azd env set DEPLOY_AZURE_COSMOS_DB_NOSQL true
    
    # Enables deployment of Azure Table Storage resource
    azd env set DEPLOY_AZURE_TABLE_STORAGE true
    
    # Reprovision architecture and deploy Bicep template again
    azd provision
  2. Change your current working directory to ./src/web

    cd ./src/web
  3. Add the correct package for the data persistence and clustering option you prefer.

    • Azure Cosmos DB for NoSQL persistence
    Azure data service Type NuGet package
    Azure Cosmos DB Clustering Microsoft.Orleans.Clustering.Cosmos
    Azure Cosmos DB Persistence Microsoft.Orleans.Persistence.Cosmos
    # Add identity package
    dotnet add package Azure.Identity
    
    # Azure Cosmos DB for NoSQL data persistence and clustering grains
    dotnet add package Microsoft.Orleans.Clustering.Cosmos
    dotnet add package Microsoft.Orleans.Persistence.Cosmos
    • Azure Table Storage persistence
    Azure data service Type NuGet package
    Azure Table Storage Clustering Microsoft.Orleans.Clustering.AzureStorage
    Azure Table Storage Persistence Microsoft.Orleans.Persistence.AzureStorage
    # Add identity package
    dotnet add package Azure.Identity
    
    # Azure Table Storage data persistence and clustering grains
    dotnet add package Microsoft.Orleans.Clustering.AzureStorage
    dotnet add package Microsoft.Orleans.Persistence.AzureStorage
  4. Configure the template's code in the src/Web/Program.cs file to enable your preferred choice of data persistence.

    • Azure Cosmos DB for NoSQL persistence

      using Azure.Identity;
      using Orleans.Configuration;
      if (builder.Environment.IsDevelopment())
      {
          builder.Host.UseOrleans(static siloBuilder =>
          {
              siloBuilder
                  .UseLocalhostClustering()
                  .AddMemoryGrainStorage("urls");
          });
      }
      else
      {
          builder.Host.UseOrleans(siloBuilder =>
          {
              var endpoint = builder.Configuration["AZURE_COSMOS_DB_NOSQL_ENDPOINT"]!;
              var credential = new DefaultAzureCredential();
      
              siloBuilder
                  .UseCosmosClustering(options =>
                  {
                      options.ConfigureCosmosClient(endpoint, credential);
                  })
                  .AddCosmosGrainStorage(name: "urls", options =>
                  {
                      options.ConfigureCosmosClient(endpoint, credential);
                  })
                  .Configure<ClusterOptions>(options =>
                  {
                      options.ClusterId = "url-shortener";
                      options.ServiceId = "urls";
                  });
          });
      }
    • Azure Table Storage persistence

      using Azure.Identity;
      using Orleans.Configuration;
      if (builder.Environment.IsDevelopment())
      {
          builder.Host.UseOrleans(static siloBuilder =>
          {
              siloBuilder
                  .UseLocalhostClustering()
                  .AddMemoryGrainStorage("urls");
          });
      }
      else
      {
          builder.Host.UseOrleans(siloBuilder =>
          {
              var endpoint = new Uri(builder.Configuration["AZURE_TABLE_STORAGE_ENDPOINT"]!);
              var credential = new DefaultAzureCredential();
      
              siloBuilder
                  .UseAzureStorageClustering(options =>
                  {
                      options.ConfigureTableServiceClient(endpoint, credential);
                  })
                  .AddAzureTableGrainStorage(name: "urls", options =>
                  {
                      options.ConfigureTableServiceClient(endpoint, credential);
                  })
                  .Configure<ClusterOptions>(options =>
                  {
                      options.ClusterId = "url-shortener";
                      options.ServiceId = "urls";
                  });
          });
      }
  5. Redeploy the application's code.

    # Rebuild Docker container and re-deploy application to Azure Container Apps
    azd deploy

Application Architecture

This application utilizes the following Azure resources at a minimum:

For data persistence, you can choose to use one of these services:

Here's a high level architecture diagram that illustrates these components. Notice that these are all contained within a single resource group, that will be created for you when you create the resources.

flowchart LR
    subgraph container-app[Azure Container Apps]
        app-framework([ASP.NET Core 8 - Microsoft Orleans])
    end
    choice[Persistence options]
    subgraph storage[Azure Storage]
        direction LR
        subgraph table-service[Table Service]
            subgraph table-orleanssiloinstances[Table: OrleansSiloInstances]
            end
            subgraph table-orleansgrainstate[Table: OrleansGrainState]
            end
        end
    end
    subgraph cosmos-db[Azure Cosmos DB for NoSQL]
        direction LR
        subgraph database-orleans[Database: Orleans]
            subgraph container-orleanscluster[Container: OrleansCluster]
            end
            subgraph container-orleansstoraage[Container: OrleansStorage]
            end
        end
    end
    container-app --> choice
    choice -.-> storage
    choice -.-> cosmos-db
Loading

Cost of provisioning and deploying this template

This template provisions resources to an Azure subscription that you will select upon provisioning them. Refer to the Pricing calculator for Microsoft Azure to estimate the cost you might incur when this template is running on Azure and, if needed, update the included Azure resource definitions found in infra/main.bicep to suit your needs.

Application Code

This template is structured to follow the Azure Developer CLI. You can learn more about azd architecture in the official documentation.

Next Steps

At this point, you have a complete application deployed on Azure. But there is much more that the Azure Developer CLI can do. These next steps will introduce you to additional commands that will make creating applications on Azure much easier. Using the Azure Developer CLI, you can setup your pipelines, monitor your application, test and debug locally.

  • azd pipeline config - to configure a CI/CD pipeline (using GitHub Actions or Azure DevOps) to deploy your application whenever code is pushed to the main branch.

  • Run and Debug Locally - using Visual Studio Code and the Azure Developer CLI extension

  • azd down - to delete all the Azure resources created with this template