Skip to content

Latest commit

 

History

History
84 lines (75 loc) · 10.5 KB

README.md

File metadata and controls

84 lines (75 loc) · 10.5 KB
Raw

C# DyanmoDB Object Persistence Model Generator

Using Roslyn, the open source .NET compiler, this project automates the creation of boilerplate C# code for using the .NET Object Persistence Model with DynamoDB.

The .NET Object Persistence Model for DynamoDB is a high level API that maps your DynamoDB tables to classes in C#, operating very similarly to an ORM tool(Object-relational mapper).

The automation tool in this repo uses CloudWatch to listen for when new DynamoDB tables are created within your AWS account.

When a new table is created, the automation tool generates a partial class in C# with automatically generated annotations for a DynamoDB table name, partition key, and sort key if present. The class is deposited in an S3 Bucket where you can download the .cs file to a .NET project of your choosing. C# Generated Code

Installation

Using CloudFormation, you can automatically create the infrastructure resources and deploy the code for this automation tool without the need to write code or manage resources yourself.

The assets are publicly available at the following URLs:

You won't need to access any of these files directly, but they are available to download if you would like to inspect the contents. You will only work with CloudFormation to install this automation tool.

Steps:

Navigate to CloudFormation in the AWS Console and follow these instructions:

  1. Click Create Stack. Create Stack
  2. Provide https://s3-us-west-2.amazonaws.com/amsxbg-ddb-code-generator/template.json as the URL to the CloudFormation template in S3. CF Template in S3
    • You can optionally view the the template in the Designer. CF Designer
  3. Enter a descriptive CloudFormation stack name. CF Stack Name
  4. Leave the defaults and click Next. CF Defaults
  5. Since this template uses the transform CloudFormation feature, you need to create a change set before you can execute the template. CF Change Set
  6. Once the change set completes, you can then Execute the CloudFormation template. CF Execute
  7. You'll know the CloudFormation stack has been created in your AWS account when the stack status is CREATE_COMPLETE. CF Created

Usage

The automation tool will generate an annotated C# class anytime you create a new DynamoDB table, regardless of how that table is created. You can create a new DynamoDB table through the AWS APIs, the AWS CLI, or through the AWS Console. We'll review how to create a table through the AWS Console.

Steps

Navigate to DynamoDB in the AWS Console.

  1. Click Create Table. DDB Create Table
  2. Enter information about your table. We'll create an example table for a blog, with the table name AMSXBGBlogTable, a partition key named PostId of type String, and a sort key named PublishedOn of type Number.
    • For this table, I added a prefix of a company name to the table name. Adding prefixes like company, department, etc. help to identify the table later.
    • We'll see later on that the automation tool picks a C# type of decimal for numbers in a DynamoDB table. We'll review some choices you have if you don't want to use decimal as the C# type in the generated code.
    • For more information on DynamoDB partition keys and sort keys, see this DynamoDB Best Practices guide. DDB Table Info
  3. The automation tool will run without any other prompting needed. You can check for an S3 Bucket that follows the naming convention of ddb-model-code-bucket-%your_aws_account_id%. S3 DDB Code Bucket
  4. You should find a file in this S3 Bucket with the same name as your DynamoDB table. The pattern for the file name is %ddb_table_name%DDBModel.cs. S3 DDB Code Bucket File
  5. Since S3 recognizes this as a text file, when you click download the file will save to your computer as a .txt file. You can simply rename the file when it downloads to a .cs file, or you can use the Download As feature of S3. S3 Download As
  6. Right click the link and choose Save Link As. S3 Download As Save S3 Download As Save Link As
  7. Add .cs to the file name before saving to your computer. S3 File Dialog

You should have a partial C# class with complete annotations for the DynamoDB table you created. Since the class is partial, you can create another file in your .NET project with the same name and add more properties that couldn't be inferred from your DynamoDB table.

When you want to use this class in a .NET project, be sure to include the AWSSDK.DynamoDBv2 package from Nuget in your project dependencies. If it is included in your project, you should see a reference your .csproj file:

<PackageReference Include="AWSSDK.DynamoDBv2" Version="3.3.12" />

Generated Code

Considerations for the Tool

If you want different generated types, such as an int type in the C# class when a DynamoDB key uses type Number, you can simply change the type in the generated file, or you can deploy your own custom version of the tool by altering the code in this repo and uploading the packages to your own S3 Buckets. You'll only need to change the CodeUri fields in the template.json CloudFormation template included in this repo.

Uninstall

Removing this automation tool is as easy as deleting the CloudFormation stack created in your AWS account. For more information on deleting a CloudFormation stack, see this documentation.

You may encounter an error when trying to delete the CloudFormation stack. If your generated S3 Bucket contains files when you attempt a stack deletion, CloudFormation will produce an error. You'll need to empty the S3 Bucket before you're allowed to delete the CloudFormation stack. See this documentation for how to empty an S3 Bucket.

Architecture Review and Inspiration

Writing an automation tool like this is relatively easy and doesn't take a lot of time. Since the resources used are all serverless, you only pay for time that the automation tool executes and you don't need to provision or manage any servers for this tool to function. I wanted to include a diagram of the pieces that make this tool work, so that you may be inspired to build your own automation tools that use the power of Roslyn and serverless architecture. Architecture Diagram

Additional C# Tools for AWS

If you're a C# developer on AWS be sure to check out these tools that will also increase your productivity.