Bob’s Used Books: A .NET Sample Application – Part 1: Getting Started

Introduction

The best sample applications are simple to understand, but have enough complexity to demonstrate real-world usage. Our new open-source .NET sample application, Bob’s Used Books, provides the .NET community with a simple but real-world .NET application that leverages multiple AWS frameworks and services.

Bob’s Used Books is a simple eCommerce application that sells fictional second hand books. The application consists of an administration portal and a customer portal. The administration portal is used by the application administrators to manage things like orders and inventory. The customer portal is used by customers to search for and purchase books. Customers also have the ability to sell their own books through the application. Bob’s Used Books takes advantage of multiple AWS services, including:

Bob’s Used Books also provides a starting point for future blogs, workshops, and guidance on modernizing .NET workloads. Each .NET modernization demonstration will walk through the what, why, and how of that particular modernization journey.

This is the first in a series of blog posts that dive deep into the implementation of Bob’s Used Books. In this post, I’ll describe how to get up and running with Bob’s Used Books as quickly as possible, and explore the different debug and deployment modes that are available. In the next post I’ll discuss the application architecture and highlight some of the decision making and conventions that went into building the application.

Getting Started with Bob’s Used Books

A lot of interesting and useful information will be shared in this blog series, but if you just want to get up and running as quickly as possible this is what you need to do:

On a Windows machine, download the source code or clone the GitHub repo from https://github.com/aws-samples/bobs-used-bookstore-sample.
Open the solution (BobsBookstore.sln) in an IDE that supports .NET 6.0 (i.e. Visual Studio 2022 or JetBrains Rider).
Make sure SQL Server Express LocalDB is installed (it is installed by default with Visual Studio).
Set the Bookstore.Web project as the StartUp project.
Select the Local launch profile then press F5.

That’s it! The application will start and you can debug the application on your local development machine. When using the Local launch profile, the application runs entirely on your local machine and makes no calls to AWS or uses AWS resources.

Figure 1 – Select Local debugging and set Bookstore.Web as startup project

Debugging and Running Bob’s Used Books

When we set out to build Bob’s Used Books one of our goals was to offer an excellent developer experience. It should be simple to understand, it should be simple to debug, and it should be simple to deploy. With that in mind there are three ways to debug and run Bob’s Used Bookstore: Local Debugging and Integrated Debugging which are launch profiles defined in Bookstore.Web/Properties/launchSettings.json, and Full Deployment which is implemented in the Bookstore.Cdk project. Each differs in the amount of AWS services and resources the application uses.

Local Debugging

The Local Debugging profile is the quickest and easiest way to get started with Bob’s Used Books (and is described above in Getting Started with Bob’s Used Books). Local Debugging does not require an AWS account, and uses no AWS services or resources. AWS services are swapped with mocks or local implementations. For example, Bob’s Used Books would normally use Amazon S3 to store book images, but during Local Debugging it instead swaps out the Amazon S3 service implementation (Bookstore.Data/FileServices/S3FileService) and uses a local file service implementation (Bookstore.Data/FileServices/LocalFileService) instead.

We anticipate that Local Debugging will be the initial way that developers interact with Bob’s Used Books. It enables developers to quickly and easily launch the application, see it in action, and inspect the code normally used to interact with AWS-specific services without needing to provision those cloud resources. At some point, though, most developers will want to step through code that interacts with AWS. This is where Integrated Debugging comes in.

Integrated Debugging

When you are ready to debug Bob’s Used Books against real AWS Services you use the Integrated Debugging launch profile. You can think of Integrated Debugging as a middle ground between Local Debugging and a full deployment to AWS. With Integrated Debugging you provision some of the AWS resources that Bob’s Used Books uses in a full deployment to the cloud, but the application still runs locally on your development machine. You can debug the application in exactly the same way as Local Debugging, however now you can see the application interacting with AWS services directly.

Before you can use Integrated Debugging you need to provision a small number of AWS resources. The Bookstore.Cdk project uses the AWS Cloud Development Kit (CDK) to provision those resources. The CDK project can also perform a full deployment of the application to AWS, which I’ll discuss shortly.

AWS CDK enables us to define AWS services and resources in C# and to then provision those AWS resources when we are ready. This is often referred to as Infrastructure-as-Code (IaC).

In order to provision AWS resources with the CDK you need to do the following:

Install the latest Long Term Support (LTS) version of Node.js
Create an AWS account if you don’t have one already
Configure CDK authentication by following the Authentication with AWS section in the AWS CDK Getting Started guide
Install the AWS CDK by opening a command-line shell and running the following command: npm install -g aws-cdk

The first time you use AWS CDK to provision services in your AWS account you need to bootstrap that account. Open a command-line shell and navigate to the application solution folder (this is the folder that contains BobsBookstore.sln). Run the following command:

cdk bootstrap

Once the AWS CDK has finished bootstrapping your account you are ready to provision the AWS resources required to support Integrated Debugging. Run the following command:

cdk deploy BobsBookstoreCore --require-approval "never"

The –require-approval “never” parameter tells the AWS CDK to automatically approve all modifications to your AWS account rather than prompting you for approval, even modifications that affect permissions and access. It is a convenience that is acceptable for the purposes of this sample application, but you should carefully consider if it is appropriate for other AWS CDK deployments.

The CDK command above assumes that your AWS credential profile is named default. If you do not have a credential profile with that name, or wish to use an alternate credential profile, add the –profile parameter followed by the name of the credential profile. For example, cdk deploy BobsBookstoreCore --profile my-profile. Note that the selected profile should be configured to set the target region. See Configuration and credential file settings for more details. An example of a credential profile containing region configuration is shown below.

[my-profile]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
region=us-west-2

This tells the AWS CDK to deploy the BobsBookstoreCore CloudFormation Stack which describes the AWS resources that need to be provisioned. It will take about 5 minutes to complete provisioning them.

Now all you need to do is select the Integrated launch profile and start debugging against real AWS resources!

Figure 2 – Select Integrated Debugging

Bob’s Used Books uses Amazon Cognito for identity management. The first time you login to Bob’s Used Books with Integrated Debugging you will need to update the administrator password. In the application, select Log in from the application toolbar:

Figure 3 – Bob’s Used Books customer portal homepage

Figure 4 – Amazon Cognito hosted sign in UI

You will then be prompted to create a new password and to provide some additional details.

Figure 5 – Amazon Cognito change password hosted UI

That’s it! You are signed into the application and taken to the customer portal home page. The admin user belongs to the Administrators group which means you can navigate between the admin portal and the customer portal by following the Admin Portal and Customer Portal links in the top-right corner of the page.

Figure 6 – Bob’s Used Books authenticated customer portal home page

The application supports self sign up. When users sign up to Bob’s Used Books they are granted access to the customer portal, but not to the administrator portal. Administrators cannot be added via self sign up, they must be added directly to the application’s Cognito user pool.

Full Deployment

Debugging an application running locally is an important capability, but at some point you need to deploy that application to a production environment. The process of deploying Bob’s Used Books to AWS is very similar to deploying the AWS services for Integrated Debugging, but instead of deploying the BobsBookstoreCore CloudFormation Stack you deploy the BobsBookstoreEC2 CloudFormation Stack. This creates the full set of resources in the cloud to support the deployed application.

The first thing you need to do is build and publish the application. Open a command-line prompt and navigate to the root of the repository folder (this is the folder that contains BobsBookstore.sln). Run the following command:

dotnet publish -p:PublishProfile=FolderProfile -c Release

Figure 7 – Publish the application

Once the application has been built and published it can be deployed to AWS. If you haven’t set up the AWS CDK on your development machine yet, run through the steps in the Integrated Debugging section above to install the prerequisites, configure CDK authentication, and bootstrap your AWS account. Once you have done that, open a command-line prompt and navigate to the application solution folder (this is the folder that contains BobsBookstore.sln). Run the following command:

cdk deploy BobsBookstoreEC2 --require-approval "never"

In addition to the services that are provisioned by the BobsBookstoreCore CloudFormation Stack, BobsBookstoreEC2 creates a new Virtual Private Cloud (VPC) and inside the VPC provisions an RDS for SQL Server database, and an Amazon EC2 instance that hosts the application. Once the resources are available, it deploys the application. These additional resources take about 25 minutes to provision.

Once the deployment is complete the application URL is displayed in an output called BobsBookstoreEC2.EC2Url. Copy and paste that URL into a browser.

Figure 8 – The deployed application’s URL

It may take a few seconds for the web server to start servicing requests after a fresh deployment. It is working as expected once you see a browser warning similar to the screenshot below.

In order to make deployment as simple as possible, the application uses a self-signed certificate to enable traffic over SSL. The first time you open Bob’s Used Books in a browser you will see a security warning about a potential security risk. This is because the browser doesn’t recognize the self-signed certificate. It is safe to ignore this warning for Bob’s Used Books, but exercise extreme caution if you ever see these warnings elsewhere!

Figure 9 – Browser warning

If you have used Bob’s Used Books in either Local Debugging or Integrated Debugging, and then do a Full Deployment, you may notice that your books and orders have disappeared. This is because in Local Debugging and Integrated Debugging Bob’s Used Books uses a SQL Server LocalDB instance for the database backend, but Full Deployment provisions and uses an RDS for SQL Server database. If you’re interested in why we have taken this approach be sure to check out the next post in this blog series.

Clean Up

If you have used Integrated Debugging or Full Deployment you can delete the AWS services and resources that were created by opening a command-line prompt, navigating to the application solution folder, and running the following command:

cdk destroy BobsBookstore*

This is an important step to ensure you don’t incur unnecessary costs.

Conclusion

Bob’s Used Books is a new open-source .NET application that is designed to reflect a simple but real-world eCommerce application running on AWS. In this blog post I have described how to get up and running with the application and the different ways the application can be run locally, and in AWS.

You can get started with Bob’s Used Books by downloading the source code or cloning the GitHub repo from https://github.com/aws-samples/bobs-used-bookstore-sample.

This is the first blog post in a series. In the next blog post I will dive deep on the application architecture, AWS services the application uses, and design decisions that went into building Bob’s Used Books.

.NET on AWS Blog