diff --git a/SampleApplications/2022/MediaCatalog/CloudFormation/mediacatalog.yml b/SampleApplications/2022/MediaCatalog/CloudFormation/mediacatalog.yml new file mode 100644 index 0000000..f6ba3dd --- /dev/null +++ b/SampleApplications/2022/MediaCatalog/CloudFormation/mediacatalog.yml @@ -0,0 +1,442 @@ +Resources: + projectbucket49C58645: + Type: AWS::S3::Bucket + UpdateReplacePolicy: Retain + DeletionPolicy: Retain + Metadata: + aws:cdk:path: Media-Catalog-Stack/project-bucket/Resource + projectbucketPolicy1EC30B15: + Type: AWS::S3::BucketPolicy + Properties: + Bucket: + Ref: projectbucket49C58645 + PolicyDocument: + Statement: + - Action: + - s3:GetBucket* + - s3:GetObject* + - s3:List* + Effect: Allow + Principal: + CanonicalUser: + Fn::GetAtt: + - OriginAccessIdentityDF1E3CAC + - S3CanonicalUserId + Resource: + - Fn::GetAtt: + - projectbucket49C58645 + - Arn + - Fn::Join: + - "" + - - Fn::GetAtt: + - projectbucket49C58645 + - Arn + - /* + - Action: s3:GetObject + Effect: Allow + Principal: + CanonicalUser: + Fn::GetAtt: + - OriginAccessIdentityDF1E3CAC + - S3CanonicalUserId + Resource: + Fn::Join: + - "" + - - Fn::GetAtt: + - projectbucket49C58645 + - Arn + - /* + Version: "2012-10-17" + Metadata: + aws:cdk:path: Media-Catalog-Stack/project-bucket/Policy/Resource + OriginAccessIdentityDF1E3CAC: + Type: AWS::CloudFront::CloudFrontOriginAccessIdentity + Properties: + CloudFrontOriginAccessIdentityConfig: + Comment: Allows CloudFront to reach the bucket + Metadata: + aws:cdk:path: Media-Catalog-Stack/OriginAccessIdentity/Resource + projectdistribution6597D937: + Type: AWS::CloudFront::Distribution + Properties: + DistributionConfig: + DefaultCacheBehavior: + CachePolicyId: 658327ea-f89d-4fab-a63d-7e88639e58f6 + Compress: true + TargetOriginId: MediaCatalogStackprojectdistributionOrigin126811F54 + ViewerProtocolPolicy: allow-all + Enabled: true + HttpVersion: http2 + IPV6Enabled: true + Origins: + - DomainName: + Fn::GetAtt: + - projectbucket49C58645 + - RegionalDomainName + Id: MediaCatalogStackprojectdistributionOrigin126811F54 + S3OriginConfig: + OriginAccessIdentity: + Fn::Join: + - "" + - - origin-access-identity/cloudfront/ + - Ref: OriginAccessIdentityDF1E3CAC + Metadata: + aws:cdk:path: Media-Catalog-Stack/project-distribution/Resource + fileTable83642645: + Type: AWS::DynamoDB::Table + Properties: + KeySchema: + - AttributeName: keyname + KeyType: HASH + AttributeDefinitions: + - AttributeName: keyname + AttributeType: S + ProvisionedThroughput: + ReadCapacityUnits: 3 + WriteCapacityUnits: 3 + TableName: MetadataService-files + UpdateReplacePolicy: Retain + DeletionPolicy: Retain + Metadata: + aws:cdk:path: Media-Catalog-Stack/fileTable/Resource + imagesTable4174DE57: + Type: AWS::DynamoDB::Table + Properties: + KeySchema: + - AttributeName: image + KeyType: HASH + AttributeDefinitions: + - AttributeName: image + AttributeType: S + ProvisionedThroughput: + ReadCapacityUnits: 3 + WriteCapacityUnits: 3 + TableName: MetadataService-Images + UpdateReplacePolicy: Retain + DeletionPolicy: Retain + Metadata: + aws:cdk:path: Media-Catalog-Stack/imagesTable/Resource + lookupTable70C77133: + Type: AWS::DynamoDB::Table + Properties: + KeySchema: + - AttributeName: label + KeyType: HASH + AttributeDefinitions: + - AttributeName: label + AttributeType: S + ProvisionedThroughput: + ReadCapacityUnits: 3 + WriteCapacityUnits: 3 + TableName: MetadataService-Lookups + UpdateReplacePolicy: Retain + DeletionPolicy: Retain + Metadata: + aws:cdk:path: Media-Catalog-Stack/lookupTable/Resource + beanstalkroleE93800ED: + Type: AWS::IAM::Role + Properties: + AssumeRolePolicyDocument: + Statement: + - Action: sts:AssumeRole + Effect: Allow + Principal: + Service: + Fn::Join: + - "" + - - ec2. + - Ref: AWS::URLSuffix + Version: "2012-10-17" + ManagedPolicyArns: + - Fn::Join: + - "" + - - "arn:" + - Ref: AWS::Partition + - :iam::aws:policy/CloudWatchLogsFullAccess + - Fn::Join: + - "" + - - "arn:" + - Ref: AWS::Partition + - :iam::aws:policy/AmazonRekognitionReadOnlyAccess + - Fn::Join: + - "" + - - "arn:" + - Ref: AWS::Partition + - :iam::aws:policy/AWSXrayFullAccess + Metadata: + aws:cdk:path: Media-Catalog-Stack/beanstalk-role/Resource + beanstalkroleDefaultPolicy8C98130E: + Type: AWS::IAM::Policy + Properties: + PolicyDocument: + Statement: + - Action: + - s3:Abort* + - s3:DeleteObject* + - s3:GetBucket* + - s3:GetObject* + - s3:List* + - s3:PutObject + - s3:PutObjectLegalHold + - s3:PutObjectRetention + - s3:PutObjectTagging + - s3:PutObjectVersionTagging + Effect: Allow + Resource: + - Fn::GetAtt: + - projectbucket49C58645 + - Arn + - Fn::Join: + - "" + - - Fn::GetAtt: + - projectbucket49C58645 + - Arn + - /* + - Action: + - dynamodb:BatchGetItem + - dynamodb:BatchWriteItem + - dynamodb:ConditionCheckItem + - dynamodb:DeleteItem + - dynamodb:DescribeTable + - dynamodb:GetItem + - dynamodb:GetRecords + - dynamodb:GetShardIterator + - dynamodb:PutItem + - dynamodb:Query + - dynamodb:Scan + - dynamodb:UpdateItem + Effect: Allow + Resource: + - Fn::GetAtt: + - fileTable83642645 + - Arn + - Fn::GetAtt: + - imagesTable4174DE57 + - Arn + - Fn::GetAtt: + - lookupTable70C77133 + - Arn + - Ref: AWS::NoValue + - Action: + - ssm:DescribeParameters + - ssm:GetParameter + - ssm:GetParameterHistory + - ssm:GetParameters + Effect: Allow + Resource: + - Fn::Join: + - "" + - - "arn:" + - Ref: AWS::Partition + - ":ssm:" + - Ref: AWS::Region + - ":" + - Ref: AWS::AccountId + - :parameter/ + - Ref: beanstalkrolerarameter1F07177C + - Fn::Join: + - "" + - - "arn:" + - Ref: AWS::Partition + - ":ssm:" + - Ref: AWS::Region + - ":" + - Ref: AWS::AccountId + - :parameter/ + - Ref: cloudfronturl63DBF573 + - Fn::Join: + - "" + - - "arn:" + - Ref: AWS::Partition + - ":ssm:" + - Ref: AWS::Region + - ":" + - Ref: AWS::AccountId + - :parameter/ + - Ref: filemetadatatable2E0AD559 + - Fn::Join: + - "" + - - "arn:" + - Ref: AWS::Partition + - ":ssm:" + - Ref: AWS::Region + - ":" + - Ref: AWS::AccountId + - :parameter/ + - Ref: imagemetadatatable2A36F062 + - Fn::Join: + - "" + - - "arn:" + - Ref: AWS::Partition + - ":ssm:" + - Ref: AWS::Region + - ":" + - Ref: AWS::AccountId + - :parameter/ + - Ref: lookupmetadatatable6579D6CE + - Fn::Join: + - "" + - - "arn:" + - Ref: AWS::Partition + - ":ssm:" + - Ref: AWS::Region + - ":" + - Ref: AWS::AccountId + - :parameter/ + - Ref: mediabucketnameAA0A697D + Version: "2012-10-17" + PolicyName: beanstalkroleDefaultPolicy8C98130E + Roles: + - Ref: beanstalkroleE93800ED + Metadata: + aws:cdk:path: Media-Catalog-Stack/beanstalk-role/DefaultPolicy/Resource + beanstalkprofile: + Type: AWS::IAM::InstanceProfile + Properties: + Roles: + - Ref: beanstalkroleE93800ED + InstanceProfileName: + Ref: beanstalkroleE93800ED + Metadata: + aws:cdk:path: Media-Catalog-Stack/beanstalk-profile + cloudfronturl63DBF573: + Type: AWS::SSM::Parameter + Properties: + Type: String + Value: + Fn::GetAtt: + - projectdistribution6597D937 + - DomainName + Description: The base URL for the Cloud Front Distribution + Name: Cloud-Front-URL + Metadata: + aws:cdk:path: Media-Catalog-Stack/cloud-front-url/Resource + mediabucketnameAA0A697D: + Type: AWS::SSM::Parameter + Properties: + Type: String + Value: + Ref: projectbucket49C58645 + Description: The S3 Bucket that stores the files. + Name: Media-Bucket-name + Metadata: + aws:cdk:path: Media-Catalog-Stack/media-bucket-name/Resource + filemetadatatable2E0AD559: + Type: AWS::SSM::Parameter + Properties: + Type: String + Value: + Ref: fileTable83642645 + Description: Table where the file metadata gets placed after upload. + Name: File-Metadata-Table + Metadata: + aws:cdk:path: Media-Catalog-Stack/file-metadata-table/Resource + imagemetadatatable2A36F062: + Type: AWS::SSM::Parameter + Properties: + Type: String + Value: + Ref: imagesTable4174DE57 + Description: Metadata about images, what Tags are included and saved in the image. + Name: Image-Metadata-Table + Metadata: + aws:cdk:path: Media-Catalog-Stack/image-metadata-table/Resource + lookupmetadatatable6579D6CE: + Type: AWS::SSM::Parameter + Properties: + Type: String + Value: + Ref: lookupTable70C77133 + Description: Metadata about images, what Tags are included and saved in the image. + Name: Lookup-Metadata-Table + Metadata: + aws:cdk:path: Media-Catalog-Stack/lookup-metadata-table/Resource + beanstalkrolerarameter1F07177C: + Type: AWS::SSM::Parameter + Properties: + Type: String + Value: + Ref: beanstalkroleE93800ED + Description: Role for your elastic beanstalk instance to use. + Name: Beanstalk-IAM-Role + Metadata: + aws:cdk:path: Media-Catalog-Stack/beanstalk-role-rarameter/Resource + CDKMetadata: + Type: AWS::CDK::Metadata + Properties: + Analytics: v2:deflate64:H4sIAAAAAAAA/21QwU6EMBD9Fu9lAEm8eVhZTfayEtx4NaUdNiPQbqZFsyH8u5Rq2IOn9+b1vcmb3kORQXYnv12idJf01MD05qXqxCJ9TK6A6WlUHXpRtuaXRahsT+q6yXGehertqFu2xsP0ynQms1MKnTtoNJ78miiD5yV4/nXsyXmmZvRkTbDfzrPQVyMHq5eiJ9n0GAwrmQXJAabaRm3FreTGDsZ5aRRWbFsKMeeGcDSTOVeS5YAeeY38DfMsanR2ZBU33/DSGk2x1976I/r0ATLI8xSOz6fSMu4ul+Qd2S2Wx68C8jRf3sOXfzqihMfl4gGhjvgDBsS2zo4BAAA= + Metadata: + aws:cdk:path: Media-Catalog-Stack/CDKMetadata/Default + Condition: CDKMetadataAvailable +Conditions: + CDKMetadataAvailable: + Fn::Or: + - Fn::Or: + - Fn::Equals: + - Ref: AWS::Region + - af-south-1 + - Fn::Equals: + - Ref: AWS::Region + - ap-east-1 + - Fn::Equals: + - Ref: AWS::Region + - ap-northeast-1 + - Fn::Equals: + - Ref: AWS::Region + - ap-northeast-2 + - Fn::Equals: + - Ref: AWS::Region + - ap-south-1 + - Fn::Equals: + - Ref: AWS::Region + - ap-southeast-1 + - Fn::Equals: + - Ref: AWS::Region + - ap-southeast-2 + - Fn::Equals: + - Ref: AWS::Region + - ca-central-1 + - Fn::Equals: + - Ref: AWS::Region + - cn-north-1 + - Fn::Equals: + - Ref: AWS::Region + - cn-northwest-1 + - Fn::Or: + - Fn::Equals: + - Ref: AWS::Region + - eu-central-1 + - Fn::Equals: + - Ref: AWS::Region + - eu-north-1 + - Fn::Equals: + - Ref: AWS::Region + - eu-south-1 + - Fn::Equals: + - Ref: AWS::Region + - eu-west-1 + - Fn::Equals: + - Ref: AWS::Region + - eu-west-2 + - Fn::Equals: + - Ref: AWS::Region + - eu-west-3 + - Fn::Equals: + - Ref: AWS::Region + - me-south-1 + - Fn::Equals: + - Ref: AWS::Region + - sa-east-1 + - Fn::Equals: + - Ref: AWS::Region + - us-east-1 + - Fn::Equals: + - Ref: AWS::Region + - us-east-2 + - Fn::Or: + - Fn::Equals: + - Ref: AWS::Region + - us-west-1 + - Fn::Equals: + - Ref: AWS::Region + - us-west-2 diff --git a/ToolGuides/toolkit-for-refactoring/01-Prerequisites/01-Setup.md b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/01-Setup.md new file mode 100644 index 0000000..5cf8981 --- /dev/null +++ b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/01-Setup.md @@ -0,0 +1,17 @@ +# Setting up your environment + +In order to follow this guide, you will need to have a development environment. The environment must have at a minimum: + +* A Microsoft Windows 10 or 11 laptop, desktop, EC2 Instance or Virtual Machine. +* [Microsoft Visual Studio 2022 Community, or better.](https://visualstudio.microsoft.com/) +* [Git source control.](https://git-scm.com/) +* Administrative access to Windows. +* [An AWS Account.](https://aws.amazon.com/free) +* [IAM Credentials into your account.](https://us-east-1.console.aws.amazon.com/iamv2/home#/home) +* [AWS Command Line Interface installed.](https://aws.amazon.com/cli/) + +This guide assumes that in addition to having Windows set up, you have already installed the tools listed above, and that you have configured access to your AWS Account for the command line. If you have not already done so, please complete the installation and configuration before proceeding. + + +[Next](./02-Sample-Application.md)
+[Back to Start](../README.md) \ No newline at end of file diff --git a/ToolGuides/toolkit-for-refactoring/01-Prerequisites/02-Sample-Application.md b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/02-Sample-Application.md new file mode 100644 index 0000000..0539265 --- /dev/null +++ b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/02-Sample-Application.md @@ -0,0 +1,34 @@ +# Sample Application + +Throughout this guide, we will be refactoring a sample application. This application is available in the AWS .NET Samples GitHub repository. + +Download the code [here](https://github.com/aws-samples/aws-net-guides). + +At a command line, using your git client type: + +``` +git clone git@github.com:aws-samples/aws-net-guides.git +``` + +The sample application that we will use is in the sub folder: + +``` +SampleApplications\2022\MediaCatalog\MediaLibrary4.8 +``` + +The sample application has a required set of infrastructure that must be deployed into your account. The infrastructure is deployed using Cloud Formation. From the AWS Console, you can create a new CloudFormation stack and use the template located in the sample application. +``` +aws-net-guides\SampleApplications\2022\MediaCatalog\CloudFormation\mediacatalog.yml +``` + +You can also deploy the stack from the AWS Command line using the following command in the aws-net-guides\SampleApplications\2022\MediaCatalog\CloudFormation\ folder. +``` +aws cloudformation deploy --template-file MediaCatalog.yml --stack-name MediaCatalogStack --capabilities CAPABILITY_IAM +``` + +You should make a copy of the Sample Application code, as the actions in this guide will be destructive to the project and source code. For example copy the folder "SampleApplications\2022\MediaCatalog\MediaLibrary4.8" to "C:\Source\MediaLibrary4.8" as this will allow us to change the application source files, while still having the original source code available. + +The rest of this guide will assume that your sample project is stored in "C:\Source\MediaLibrary4.8\". + +[Next](./03-Sample-Tour.md)
+[Back to Start](../README.md) \ No newline at end of file diff --git a/ToolGuides/toolkit-for-refactoring/01-Prerequisites/03-Sample-Tour.md b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/03-Sample-Tour.md new file mode 100644 index 0000000..9995f6d --- /dev/null +++ b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/03-Sample-Tour.md @@ -0,0 +1,47 @@ +# A Tour of the Sample Application + +In Visual Studio, open the solution file: +``` +C:\Source\MediaLibrary4.8\MediaLibrary\MediaLibrary.sln +``` + +Once the solution file is open in Visual Studio, run the solution to have a look at the starting point for the sample application. + +![Media Catalog](img/home-page.png) + +From the main page, click the "Upload" link under the Upload title. + +Use the Browse and Upload buttons to upload an image to the application. + +![Upload](img/upload.png) + +In the sample code folder, there are sample images provided by the Smithsonian Institution. These images can be found by going to the origional location that you cloned the repo and looking in the following folder structure. +``` +aws-net-guides\SampleApplications\2022\MediaCatalog\MediaLibrary6.0\SampleImages\ +``` + +Browse to this folder and select the image "NZP-20140817-6602RG-000003.jpg" click "Upload File" once the file has been selected. + +The upload process automatically uses Amazon Rekognition to scan the image for any content that might be offensive. The application code automatically rejects any image where any moderation flags have been found. + +Once uploaded, the application will bring you to a list of the files that have been uploaded, and are ready to process. + +![Process](img/process.png) + +Click the "Process" link beside the image. This will use Amazon Rekognition to scan the image and find labels for things that are in the image. + +The processing page will give you a list of all the labels that Rekognition has detected and give you an opportunity to save the labels that you want against the image. + +![Rekognition Results](img/results.png) + +Select the options for Cheetah, Wildlife, Animal and Mammal. Then click Save. + +You will then be brought back to the image list view. The image will no longer have a "Process" link, but will not have a link that allows you to view the previously saved results. + +![Final](img/final.png) + +This completes the tour of the Media Catalog application. Feel free to spend more time looking around the application and becoming familiar with the other functions that are available before moving on to the next part of the guide. + + +[Next](../02-Getting-Started/01-Instalation.md)
+[Back to Start](../README.md) \ No newline at end of file diff --git a/ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/final.png b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/final.png new file mode 100644 index 0000000..c96f816 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/final.png differ diff --git a/ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/home-page.png b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/home-page.png new file mode 100644 index 0000000..095f70e Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/home-page.png differ diff --git a/ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/process.png b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/process.png new file mode 100644 index 0000000..6b9ecbb Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/process.png differ diff --git a/ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/results.png b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/results.png new file mode 100644 index 0000000..df6c5b6 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/results.png differ diff --git a/ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/upload.png b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/upload.png new file mode 100644 index 0000000..e975456 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/upload.png differ diff --git a/ToolGuides/toolkit-for-refactoring/02-Getting-Started/01-Instalation.md b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/01-Instalation.md new file mode 100644 index 0000000..fc688a1 --- /dev/null +++ b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/01-Instalation.md @@ -0,0 +1,29 @@ +# Installing the AWS Toolkit for .NET Modernization + +The AWS Toolkit for .NET Refactoring installs in Visual Studio as an extension. If you don't have Visual Studio open, start it now and select the option to continue without code. + +![Open VS](img/visual-studio-open.png) + +From Visual Studio, click on the Extensions menu item, and then click on Manage Extensions. + +![Manage Extensions](img/manage-extenstions.png) + +Make sure the option to search for “Online” extensions is selected. Then type “AWS” in the search field. Your extensions list will be filtered down. From this menu you can select the “AWS Toolkit for .NET Refactoring VS 2022” from the menu. Once selected, click the Download button. + +![Manage Extensions](img/download-toolkit.png) + +Once the download has been completed, you will receive a message that the changes will be scheduled once Visual Studio is closed. At this point, click the Close button, and shut down Visual Studio. + +![Close Visual Studio](img/close-visual-studio.png) + +Click the Close button, then close Visual Studio. Once Visual Studio closes, the Visual Studio Extension Installer application will run. + +![Close Visual Studio](img/modify-visual-studio.png) + +Click the Modify button to allow Visual Studio to install the extension. + +This completes the installation of the .NET Refactoring Toolkit for .NET. + + +[Next](./02-assessing-application.md)
+[Back to Start](../README.md) \ No newline at end of file diff --git a/ToolGuides/toolkit-for-refactoring/02-Getting-Started/02-assessing-application.md b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/02-assessing-application.md new file mode 100644 index 0000000..56569e9 --- /dev/null +++ b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/02-assessing-application.md @@ -0,0 +1,77 @@ +# Assessing your application + +The first step in using the AWS Toolkit for .NET Refactoring to refactor your application from .NET Framework 4.8 to .NET 6 is to perform an assessment of the current application. This assessment will scan through your application code, dependencies, and NuGet packages to help determine the level of complexity with converting your application. + +The assessment is nondestructive, the results of the assessment is a report. + +From Visual Studio, open the solution file + +``` +C:\source\MediaLibrary4.8\MediaLibrary\MediaLibrary.sln +``` + +If the toolkit does not automatically open the Getting Started page below, you can manually launch the Getting Started page by clicking on the extensions menu, select the AWS Toolkit for .NET Refactoring, and then clicking on Getting Started. + +![Configure Toolkit Menu](img/toolkit-configure-menu.png) + +## Configuring the Toolkit + +The AWS Toolkit will need to be configured on the first execution. The configuration page is seen here: + +![Configure Toolkit Menu](img/toolkit-configure.png) + +In order to progress beyond the first page, you must click on the link under the End User License Agreement (EULA.) Click on this link and read the agreement on the linked page. + +The first configuration option is to select how the toolkit will connect to AWS. You have two options for these details. First, you can specify a named profile that has been configured by the AWS Command Line. In this case you have an access key and a secret key configured on your machine. Typically, these credentials are stored by using the command: +``` +aws configure +``` +And then providing credentials. + +The second option is to allow the tool to locate credentials automatically. This option will allow the tool to use credentials that were obtained via IAM Identity Center (Formerly SSO) or inherit credentials from an IAM Role attached to an EC2 Instance. + +Functionality for the application will be identical with either method, as long as the selected method has valid credentials for your AWS account. If you are unsure of which option to use, consult with your AWS Account Administrator as they may have policies that determine which method is to be used for obtaining AWS Credentials. + +The second configuration option that needs to be set is the region for test deployments. Currently, you can select either "US-EAST-2" or "EU-WEST-2." Note that this selection applies **only** to the test deployments conducted by the toolkit. You have the option to deploy your applications to any AWS region once you are happy with the refactoring. + +Once these options have been completed, click Next. + +## Starting the Assessment + +After configuring the toolkit, you are presented with the Refactoring Dashboard. + +![Dashboard - Not Started](img/dashboard-not-started.png) + +At this point, the Assessment is listed as "Not Started." As a result other toolkit functionality may not be available. In order to perform an assessment, you first need to open one of the code files in the solution. Double click on the "HomeController.cs" file to open it, then click back on the Dashboard Window. + +![Dashboard - Not Started](img/open-code-file.png) + +From this window select the option to "Start Assessment" and the toolkit will begin inspecting your application. + +![Dashboard - Not Started](img/assessment-in-progress.png) + +The status on the dashboard will change to "In Progress" while the scanning takes place. + +![Dashboard - Not Started](img/assessment-complete.png) + +Once your assessment is complete, you will receive an assessment report below. + +### Incompatible NuGet packages + +This lists the number of packages that are included in the solution that are not compatible with the target version of .NET in this case .NET 6. Note that for these packages, you will need to find alternatives for the required functionality. + +### Incompatible APIs + +This lists the number of API calls that are not portable to the new version of .NET. This may be cases where functionality has been deprecated or the API calls have breaking changes. Manual coding effort will be required, after porting, to make the code compatible with the new target version of .NET. + +These results provide details to the amount of manual work, that the toolkit was able to identify, that will be required after the porting. It is important to understand that these are the incompatibilities that the tool was able to identify, it is not necessarily all of the changes that will be required. You may find code that needs to be reworked when you test your application after porting. + +Further details of the incomparable code can be found by looking at the error list, and selecting to view Warnings. Each item in the list shows some manual effort that you will have to complete. + +![Dashboard - Not Started](img/error-list.png) + + +[Next](../03-porting-application/01-porting-application.md)
+[Back to Start](../README.md) + + diff --git a/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/assessment-complete.png b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/assessment-complete.png new file mode 100644 index 0000000..9d755e4 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/assessment-complete.png differ diff --git a/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/assessment-in-progress.png b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/assessment-in-progress.png new file mode 100644 index 0000000..9938e93 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/assessment-in-progress.png differ diff --git a/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/close-visual-studio.png b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/close-visual-studio.png new file mode 100644 index 0000000..01fbe6d Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/close-visual-studio.png differ diff --git a/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/dashboard-not-started.png b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/dashboard-not-started.png new file mode 100644 index 0000000..c45053b Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/dashboard-not-started.png differ diff --git a/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/download-toolkit.png b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/download-toolkit.png new file mode 100644 index 0000000..5a17cc7 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/download-toolkit.png differ diff --git a/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/error-list.png b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/error-list.png new file mode 100644 index 0000000..349e802 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/error-list.png differ diff --git a/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/manage-extenstions.png b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/manage-extenstions.png new file mode 100644 index 0000000..b509e6a Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/manage-extenstions.png differ diff --git a/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/modify-visual-studio.png b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/modify-visual-studio.png new file mode 100644 index 0000000..f054b8d Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/modify-visual-studio.png differ diff --git a/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/open-code-file.png b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/open-code-file.png new file mode 100644 index 0000000..aea8e3f Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/open-code-file.png differ diff --git a/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/toolkit-configure-menu.png b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/toolkit-configure-menu.png new file mode 100644 index 0000000..14c6322 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/toolkit-configure-menu.png differ diff --git a/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/toolkit-configure.png b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/toolkit-configure.png new file mode 100644 index 0000000..a74c531 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/toolkit-configure.png differ diff --git a/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/visual-studio-open.png b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/visual-studio-open.png new file mode 100644 index 0000000..e38fb5b Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/02-Getting-Started/img/visual-studio-open.png differ diff --git a/ToolGuides/toolkit-for-refactoring/03-porting-application/01-porting-application.md b/ToolGuides/toolkit-for-refactoring/03-porting-application/01-porting-application.md new file mode 100644 index 0000000..7596847 --- /dev/null +++ b/ToolGuides/toolkit-for-refactoring/03-porting-application/01-porting-application.md @@ -0,0 +1,33 @@ +# Porting your application +Once your assessment has been completed, you are able to port your project to the desired version of .NET. + +## Warning: +Porting application code is destructive. You can't undo the changes once the process of porting your solution has begun. Backup all source code before progressing. + +## Start porting your application + +You start the porting process for your application from the assessment dashboard. Select the project to be ported in the Solution Explorer, then click the Port drop down, and click "Port Selected Project." + +![Start Assessment](img/start-porting.png) + +At this point you receive one final warning that the process is permanent. + +![Warning](img/confirm-porting.png) + +Check the confirmation and then click the Port button. The time required for porting your application will vary depending on the size of the solution, number of projects, etc. This sample project completes quickly. Once porting has been completed, you will receive a message showing that porting has been successful. + +![Porting Complete](img/porting-complete.png) + +Click Ok to dismiss this dialog. You will then receive a message that your project files have been updated. This dialog will give you the option to reload. You should click the button to "Reload All" before going any further. + +![Reload Projects](img/reload-projects.png) + +Once your project has been reloaded, the dashboard will look like this. + +![Porting Results](img/refactoring-results.png) + +This completes the porting of your application. However, if you attempt to run the application now, the application will not compile. You will need to move onto the manual refactoring stage in order to complete the move to .NET 6. + + +[Next](./02-manual-refactoring.md)
+[Back to Start](../README.md) \ No newline at end of file diff --git a/ToolGuides/toolkit-for-refactoring/03-porting-application/02-manual-refactoring.md b/ToolGuides/toolkit-for-refactoring/03-porting-application/02-manual-refactoring.md new file mode 100644 index 0000000..442b636 --- /dev/null +++ b/ToolGuides/toolkit-for-refactoring/03-porting-application/02-manual-refactoring.md @@ -0,0 +1,233 @@ +# Manual Post-Porting refactoring + +Once your application has been refactored by the toolkit, you will have to go through a process of manually refactoring any of the incompatible code that the toolkit was not able to automatically correct for you. + +This section of the guide will walk through some of the manual effort required for completing the porting of this application. + +If you need help in progressing with the refactoring effort, there is a copy of the MediaLibrary project built to target .NET 6 in the AWS Samples repository at the following location: + +``` +aws-net-guides\SampleApplications\2022\MediaCatalog\MediaLibrary6.0 +``` + +## Fixing the missing NuGet packages + +When you open up code files that reference the AWS SDKs you will notice errors with the using clauses in the code, and other errors indicating that classes that your code uses can not be found. + +![Error List](img/s3-storage-class-errors.png) + +These errors are caused by missing NuGet packages. These errors are corrected by adding the list of required AWS SDKs back into the project via NuGet. Right click on your project, select "Manage NuGet Packages..." and then add the following packages to your project. + +* AWSSDK.Core +* AWSSDK.S3 +* AWSSDK.DynamoDBv2 +* AWSSDK.SimpleSystemsManagement +* AWSSDK.Extensions.NETCore.Setup +* AWSSDK.Rekognition +* AWSSDK.XRay +* AWSXRayRecorder.Handlers.AwsSdk + +## Fixing the Upload function + +The **Controllers/FileManagementController.cs** file contains an upload method that references the HttpPostedFileBase class. However, this class is no longer available in .NET 6. This is one of the APIs that needs to be manually corrected. + +Replace the code: +```C# +public async Task Upload(HttpPostedFileBase file) +``` +with +```C# +public async Task Upload(IFormFile file) +``` + +This change will cause additional changes to be required through the code necessary to save the file to Amazon S3. Open the Services/S3StorageService.cs file. + +Open the file **Services/IStorageService.cs** + +Replace the code: +```C# +string SaveFile(HttpPostedFileBase file); +``` +with +```C# +string SaveFile(IFormFile file); +``` + +Open the **Services/S3StorageService.cs** file. This class will not compile because of the HttpPostedFileBase class not being available in .NET 6. + +replace the code: +```C# +public string SaveFile(HttpPostedFileBase file) +``` +with +```C# +public string SaveFile(IFormFile file) +``` + +replace the code: +```C# +try +{ + var stream = new MemoryStream(); + file.InputStream.CopyTo(stream); + + request.InputStream = file.InputStream; + utility.Upload(request); +} +``` +with +```C# +try +{ + var stream = new MemoryStream(); + file.CopyTo(stream); + + request.InputStream = file.OpenReadStream(); + utility.Upload(request); +} +``` +Open the file **Services/FileSystemStorageService.cs** this is a class primarily used for local testing of the website when not using Amazon S3 for storage. You can either delete the file from your solution, or you can fix the implementation for .NET 6. + +If you choose to fix the optional class, replace the code: +```C# +public string SaveFile(HttpPostedFileBase file) +{ + var filePath = Path.Combine(baseFileLocation, DateTime.Now.Ticks.ToString() + Path.GetExtension(file.FileName)); + using (var stream = System.IO.File.Create(filePath)) + { + file.InputStream.CopyTo(stream); + return Path.Combine(baseFileLocation, filePath); + } +} +``` +with +```C# +public string SaveFile(IFormFile file) +{ + var filePath = Path.Combine(baseFileLocation, DateTime.Now.Ticks.ToString() + Path.GetExtension(file.FileName)); + using (var stream = System.IO.File.Create(filePath)) + { + file.CopyTo(stream); + return Path.Combine(baseFileLocation, filePath); + } +} +``` + +## Removing the Test Project + +At this point your main project will compile, however the Test project in the solution will fail to build. Normally you would carry on to fix the test project, however, for the purposes of this guide we will simply remove the test project. + +Right click on the test project and select Remove. +![Remove Tests](img/remove-tests.png) + +Attempting to build your project now will have some results that may appear confusing. A rebuild will show that there are no code errors: +![Build Failed 1](img/build-failed-1.png) + +However, the project output will indicate that the build of the project has failed.![Build Failed 2](img/build-failed-2.png) + +This discrepancy comes down to the code that is embedded in the project's CSHTML pages. The specific problems lie in the layout files used by the MVC framework. + +## Fix the application views + +Open the file **Views/Shared/_layout.cshtml** + +replace the code: +```html +@ViewBag.Title - My ASP.NET Application +``` +with: +```html +@ViewBag.Title - My ASP.NET @System.Environment.Version +``` + +replace the code: +```C# +@Styles.Render("~/Content/css") +@Scripts.Render("~/bundles/modernizr") +``` +with +```html + + + +``` + +replace the code: +```C# +@Scripts.Render("~/bundles/jquery") +@Scripts.Render("~/bundles/bootstrap") +``` +with +```html + + +``` + +## Fix the App Settings + +At this point your application will successfully compile. However, if you run the application locally it will fail with the following error: +![Crypto Error](img/crypto-error.png) + +This error is caused by the boiler plate code that is used to create the .NET 6 AppSettings.json file. The default app settings attempts to support HTTPS on your test end points when the application is run in debug mode, however the default code does not have a certificate required to support HTTPS. + +Open the file **appSettings.json** in the root of the project. + +replace the code: +```json + "AllowedHosts": "*", + "Kestrel": { + "Endpoints": { + "Http": { + "Url": "http://0.0.0.0:80" + }, + "Https": { + "Url": "https://0.0.0.0:443", + "Certificate": { + "Path": "", + "Password": "" + } + } + } + } + ``` + with + ```json + "AllowedHosts": "*" + ``` +This change completely eliminated the "Kestrel" section, and removes the trailing comma after the AllowedHosts entry. + +Save all of your open files, and run the application using the debug option. + +## Testing your application + +Once you have run the application, your project should start up correctly, and you should see the following: + +![Final Results](img/final-results.png) + +Note that the title of the tab calls out that the application is running .NET version 6.0! + +You can test your application functionality by interacting with the application. This may uncover additional errors that occur at runtime, despite your application successfully compiling. + +For example, if you attempt to process an image: +![Process error 1](img/process-error-1.png) + +your will receive the following runtime error: +![Process error 2](img/process-error-2.png) + +You can fix this by opening the file **Controllers/RekognitionController.cs** +replace the code: +```C# +public async Task Process(ImageProcessingModel model, FormCollection collection) +``` +with +```C# +public async Task Process(ImageProcessingModel model, IFormCollection collection) +``` + +## Complete + +Congradulations! You have completed the porting of your application from .NET 4.8 to .NET 6. + + +[Next](../04-Cleanup/01-cleanup.md)
+[Back to Start](../README.md) \ No newline at end of file diff --git a/ToolGuides/toolkit-for-refactoring/03-porting-application/img/build-failed-1.png b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/build-failed-1.png new file mode 100644 index 0000000..a34abc7 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/build-failed-1.png differ diff --git a/ToolGuides/toolkit-for-refactoring/03-porting-application/img/build-failed-2.png b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/build-failed-2.png new file mode 100644 index 0000000..5fbe6d0 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/build-failed-2.png differ diff --git a/ToolGuides/toolkit-for-refactoring/03-porting-application/img/confirm-porting.png b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/confirm-porting.png new file mode 100644 index 0000000..76ab866 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/confirm-porting.png differ diff --git a/ToolGuides/toolkit-for-refactoring/03-porting-application/img/crypto-error.png b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/crypto-error.png new file mode 100644 index 0000000..380f9a2 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/crypto-error.png differ diff --git a/ToolGuides/toolkit-for-refactoring/03-porting-application/img/final-results.png b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/final-results.png new file mode 100644 index 0000000..92f223a Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/final-results.png differ diff --git a/ToolGuides/toolkit-for-refactoring/03-porting-application/img/porting-complete.png b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/porting-complete.png new file mode 100644 index 0000000..dc376b2 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/porting-complete.png differ diff --git a/ToolGuides/toolkit-for-refactoring/03-porting-application/img/process-error-1.png b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/process-error-1.png new file mode 100644 index 0000000..e065c0d Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/process-error-1.png differ diff --git a/ToolGuides/toolkit-for-refactoring/03-porting-application/img/process-error-2.png b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/process-error-2.png new file mode 100644 index 0000000..a8ac280 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/process-error-2.png differ diff --git a/ToolGuides/toolkit-for-refactoring/03-porting-application/img/refactoring-results.png b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/refactoring-results.png new file mode 100644 index 0000000..4e851fd Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/refactoring-results.png differ diff --git a/ToolGuides/toolkit-for-refactoring/03-porting-application/img/reload-projects.png b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/reload-projects.png new file mode 100644 index 0000000..0aaad10 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/reload-projects.png differ diff --git a/ToolGuides/toolkit-for-refactoring/03-porting-application/img/remove-tests.png b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/remove-tests.png new file mode 100644 index 0000000..ce304bc Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/remove-tests.png differ diff --git a/ToolGuides/toolkit-for-refactoring/03-porting-application/img/s3-storage-class-errors.png b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/s3-storage-class-errors.png new file mode 100644 index 0000000..1e0d255 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/s3-storage-class-errors.png differ diff --git a/ToolGuides/toolkit-for-refactoring/03-porting-application/img/start-porting.png b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/start-porting.png new file mode 100644 index 0000000..5559713 Binary files /dev/null and b/ToolGuides/toolkit-for-refactoring/03-porting-application/img/start-porting.png differ diff --git a/ToolGuides/toolkit-for-refactoring/04-Cleanup/01-cleanup.md b/ToolGuides/toolkit-for-refactoring/04-Cleanup/01-cleanup.md new file mode 100644 index 0000000..961db2e --- /dev/null +++ b/ToolGuides/toolkit-for-refactoring/04-Cleanup/01-cleanup.md @@ -0,0 +1,18 @@ +# Cleaning up your resources + +It is important to clean up the resources that have been deployed into your AWS Account to prevent unintentional charges from being accumulated in your account. This will require a combination of manual and automated processes. + +## Clean up S3 +The deployment of the CloudFormation template has created an S3 bucket in your account. This bucket will contain copies of the images that you have uploaded to the application. CloudFormation cannot automatically delete these files, as they were not part of the stack deployment. You should manually delete the content of that bucket. + +## Clean up DynamoDB +The deployment process created three Dynamo DB tables. These tables contain the metadata for the images that have been uploaded to your application. Cloud Formation will not automatically delete these tables as they have user data in them. Delete the following DynamoDB tables manually. +* MetadataService-files +* MetadataService-Images +* MetadataService-Lookups + +## Delete Cloud Formation Stack +Once the manual cleanup has been completed, you can go into CloudFormation and delete the stack that you deployed in the first section of this guide. Cloud formation will clean up the rest of the resources in your account. + + +[Back to Start](../README.md) \ No newline at end of file diff --git a/ToolGuides/toolkit-for-refactoring/README.md b/ToolGuides/toolkit-for-refactoring/README.md new file mode 100644 index 0000000..dd5d702 --- /dev/null +++ b/ToolGuides/toolkit-for-refactoring/README.md @@ -0,0 +1,24 @@ +# AWS Toolkit for .NET Refactoring + +## End to End Guide + +This guide serves as an introduction to the AWS Toolkit for .NET Refactoring. The guide will walk you through getting the toolkit installed, and refactoring your first application. + +By the completion of this guide, you will be familiar with the basic functions of the toolkit and be able to work your way through a sample application. Additional resources will be available to continue learning. + +### Introduction + +The AWS Toolkit for .NET Refactoring is an extension that plugs into Visual Studio and assists users with converting their applications from .NET Framework ie 4.8 to modern .NET ie .NET 6 or 7. The toolkit assesses applications to determine the portability of the application to modern .NET, as well as assisting users with the conversion of projects and code, to the target .NET release. + +Users should be aware that the conversion is performed in place, and cannot be undone once the process has been launched on a project. + +Following this guide will result in the possibility of charges to your AWS Account. Charges include usage of Amazon DynamoDB and Amazon Simple Storage Service (S3). + +### Resources + +* [Toolkit for Visual Studio 2022](https://marketplace.visualstudio.com/items?itemName=AWSTR.refactoringtoolkit2022) +* [Toolkit for Visual Studio 2019](https://marketplace.visualstudio.com/items?itemName=AWSTR.refactoringtoolkit2019) + +### Further Reading + +[Product Page](https://aws.amazon.com/visual-studio-net/)
\ No newline at end of file