Merge pull request #70 from aws-samples/tool-guides

Tool guides

Author: Thomas Moore

SampleApplications/2022/MediaCatalog/CloudFormation/mediacatalog.yml

@@ -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) <br/>
+[Back to Start](../README.md)

ToolGuides/toolkit-for-refactoring/01-Prerequisites/01-Setup.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 [email protected]: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) <br/>
+[Back to Start](../README.md)

ToolGuides/toolkit-for-refactoring/01-Prerequisites/02-Sample-Application.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) <br/>
+[Back to Start](../README.md)

ToolGuides/toolkit-for-refactoring/01-Prerequisites/03-Sample-Tour.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) <br/>
+[Back to Start](../README.md)

ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/final.png

@@ -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) <br/>
+[Back to Start](../README.md)
+
+

ToolGuides/toolkit-for-refactoring/01-Prerequisites/img/home-page.png

@@ -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) <br/>
+[Back to Start](../README.md)