AWS Microservice Extractor for .NET
User Guide
AWS Microservice Extractor for .NET: User Guide
Copyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon.
Table of Contents
What Is AWS Microservice Extractor for .NET? ... 1
Features ... 1
Supported use cases ... 2
Concepts ... 2
Access ... 3
Pricing ... 3
How AWS Microservice Extractor for .NET works ... 4
Overview ... 4
Application analysis and extraction ... 4
Visualization ... 5
Runtime profiling ... 6
Limits ... 6
Information collected ... 6
Get started ... 7
Prerequisites ... 7
Prerequisites for analysis and extraction ... 7
Required IAM policies ... 8
Install ... 9
Installation ... 9
Runtime profiling prerequisites ... 9
Use Microservice Extractor ... 11
Set up ... 11
Onboard ... 12
View details ... 12
Launch visualization ... 13
Work with visualization ... 13
Extract as independent services ... 16
Manually deploy ... 17
Failure modes ... 17
Remove application ... 18
Edit details ... 18
Edit settings ... 18
Security ... 19
Data protection ... 19
Data collected by AWS Microservice Extractor for .NET ... 20
Identity and Access Management ... 20
Configuration and vulnerability analysis ... 21
Security best practices ... 21
Troubleshooting ... 22
AWS profile errors ... 22
Build failures ... 22
Extraction errors ... 23
Application artifact location ... 23
Onboarding and visualization errors ... 23
Creating groups ... 24
Uninstalling application ... 24
Metrics and logs collected by AWS Microservice Extractor for .NET ... 24
Questions and feedback ... 24
Document History ... 26
Features
What Is AWS Microservice Extractor for .NET?
AWS Microservice Extractor for .NET is an assistive modernization tool that helps to reduce the time and effort required to break down large, monolithic applications running on the AWS Cloud or on premises into smaller, independent services. These services can be operated and managed independently.
Microservice Extractor analyzes the code of your target application, and creates a visualization of the source code of the application. The visualization includes classes, namespaces, and method calls between them. The visualization of your application helps you to logically group functionalities based on criteria such as class dependencies, namespaces, and call counts. When you isolate the functionalities of the application into groups, Microservice Extractor provides assistive guidance to refactor your code base to prepare it for extraction into smaller services. When the code base is ready for extraction, Microservice Extractor extracts the functionalities into separate code solutions. You can then manually edit and deploy these code solutions as independent services.
Microservice Extractor overview topics
• Primary features (p. 1)
• Supported use cases (p. 2)
• Concepts (p. 2)
• Access AWS Microservice Extractor for .NET (p. 3)
• Pricing for AWS Microservice Extractor for .NET (p. 3)
Primary features
The primary features of AWS Microservice Extractor for .NET are:
Application analysis and graphical representation of application classes
Microservice Extractor analyzes your monolithic applications and, based on the analysis, produces a graphical representation that displays the application classes, optionally configured metrics for applicable classes, and dependencies between them. The interactive graph groups classes by functionality to help you make decisions about which parts of the application to extract as independent services.
Automated packaging of grouped functionalities into smaller services
You can designate the parts of an application to extract as separate services by grouping parts of the application code to be removed based on the functionality they implement. Microservice Extractor attempts to convert the grouped classes into code solutions. Internal application method calls can be converted to API operations so that the new, smaller services can function independently from the monolithic application.
Porting Assistant for .NET integration
You can determine whether your application dependencies are compatible with .NET Core, and group .NET Core compatible dependencies together using Porting Assistant for .NET integration with Microservice Extractor. Microservice Extractor detects whether Porting Assistant for .NET is installed on your machine and gives you the option to include .NET Core compatibility data. When this option
Supported use cases
is enabled, you can view .NET Core compatible dependencies in the visualization side panel of your monolithic application.
Supported use cases
AWS Microservice Extractor for .NET supports the following use cases.
.NET Framework
AWS Microservice Extractor for .NET supports .NET Framework ASP.NET web service applications hosted on IIS. Specifically, Microservice Extractor supports the following CLR 4.0 versions:
• Application visualization: .NET Framework version 4.0 and later
• Application extraction:
• .NET Framework version 4.8.0
• .NET Framework version 4.7.2
• .NET Framework version 4.7.1
• .NET Framework version 4.7.0
Microservice Extractor analyzes C# source code. Microservice Extractor does not support ASP.NET Web Pages or Razor Pages.
Extraction
Microservice Extractor supports extraction for the following use cases:
• Classes are extracted in their entirety. Partial class extraction is not supported.
• Classes do not change during compilation. Classes that change class structure during compilation are not supported.
Controllers
Microservice Extractor supports the following actions in relation to controllers:
• For applications with controllers, Microservice Extractor converts local method calls at the controller level to network calls to the extracted service.
• For other applications, Microservice Extractor adds code comments by default. If you choose the advanced option for Method invocations from the application to the extracted service during extraction, Microservice Extractor replaces local method calls with network calls, where possible.
• For MVC applications, Microservice Extractor copies the views (.cshtml file) to the extracted service to be able to render the relevant HTML when returning the response.
Concepts
The following concepts and definitions can help you to understand the AWS Microservice Extractor for .NET tool.
Nodes
Nodes represent the classes in the source code of the monolithic application.
Groups
Access
Closely related functions are organized as groups of nodes in the graphical representation of a
monolithic application. Application nodes are displayed with their dependencies to help you understand the functional architecture of your application. This visualization of the application nodes and
dependencies can help you to group them together by functionality.
Islands
Islands are nodes arranged as independent groups of connected nodes. Nodes within an island do not have any detected dependencies to or from nodes within other islands.
Visualization
The Microservice Extractor visualization uses source code analysis and runtime metrics to produce a graphical representation of a monolithic application. The graph shows dependencies between application nodes, call counts, and static references between code artifacts. You can use the graph and call counts to understand the dependencies between nodes, and to identify heavily called ones. You can run the assessment tool from the standalone Microservice Extractor application.
Extraction
Extraction, using Microservice Extractor, is the process of separating out logically grouped parts of a monolithic application into smaller, independent services. These parts are referred to as islands in the visualization of an application. You can perform an extraction using Microservice Extractor after an application has been assessed.
Access AWS Microservice Extractor for .NET
AWS Microservice Extractor for .NET is a standalone tool that you download and install on your developer workstation. Specify the source files for your applications to start an analysis. You can view the analysis using the UI console.
To install Microservice Extractor, see Install AWS Microservice Extractor for .NET (p. 9).
Pricing for AWS Microservice Extractor for .NET
AWS Microservice Extractor for .NET is available for use at no cost.
Overview
How AWS Microservice Extractor for .NET works
This section describes how AWS Microservice Extractor for .NET analyzes an application and extracts an application into smaller services.
How Microservice Extractor works topics
• Overview (p. 4)
• Application analysis and extraction (p. 4)
• Visualization (p. 5)
• Runtime profiling (p. 6)
• Service limits (p. 6)
• Information collected (p. 6)
Overview
The following are the high-level steps for using AWS Microservice Extractor for .NET to modernize your monolithic application by extracting it into smaller services.
1.Onboard and analyze the application — Onboard the application to Microservice Extractor by providing access to the application source code and binaries. The backend service logic of the application is analyzed by Microservice Extractor to understand the application and node structure, and the dependencies between nodes. The results of this analysis can help you to understand how to better group functionalities into separate services. If you have runtime profiling data that represents production data, you can optionally use it with the analysis to collect actionable runtime metrics.
If Porting Assistant for .NET is installed on your machine, you can optionally include .NET Core compatibility data in the visualization side panel.
2.Assist with identifying grouped classes to extract as independent services — Microservice Extractor creates a graphical representation of the application that shows the nodes, dependencies, and groupings based on dependency coupling. If you have uploaded runtime profiling data during application onboarding, for example, transactional call volume, then it will be displayed. This graphical representation assists you with extracting groupings of nodes as isolated services.
3.Refactor source code and extract grouped nodes — After the parts of the application that you want to extract are grouped and selected, refactor source code by isolating business domains and removing dependencies between them. Then, extract the groups as separate code solutions. After extracting the groups as separate solutions, you can manually edit and build the code solutions, and deploy them as independent services in containers.
Application analysis and extraction
AWS Microservice Extractor for .NET analyzes the source code of a monolithic application and creates a visualization of the application, which includes nodes, dependencies, call flows, and relevant metrics.
You can use the visualization of the application to make informed decisions about the structure of
Visualization
the application, and to identify parts of the application to group together and extract as independent services.
After Microservice Extractor extracts a specified functionality group within the application, you can manually package and deploy the functionalities as independent services in containers. You can then integrate the smaller services with your custom workflows.
Extracting monolithic applications into smaller, independent services is an iterative process. Based on your requirements, you can repeat the process by onboarding the newly extracted monolithic application into Microservice Extractor. This further assists with identifying and extracting components as independent services.
Visualization
AWS Microservice Extractor for .NET creates a visualization of the monolithic application nodes, the metrics for each node, and the dependencies between them. It provides data on the application structure required to help you decide what parts of the application you want to extract as smaller, independent services. You can use the visualization to perform the following:
• Isolate dependencies — Use the visualization to help you isolate dependencies and automatically capture interdependencies to create groups of closely related nodes. Nodes within each group rely on other nodes within the group.
• Narrow focus — View all of the dependencies for a selected node, and the shared dependencies between nodes.
• Assess call count — View the method call count number between nodes. Call count data is provided by the runtime metrics that you upload to the tool.
• Visualize at a high level — Get a high-level understanding of your monolithic application, and investigate dependencies and call count metrics to make decisions about parts of the application to extract into smaller, independent services.
Runtime profiling
Runtime profiling
The AWS Microservice Extractor for .NET tool includes an application runtime profiler to provide call count data with dependency details in the visualization of the application. The output of the profiler is processed by the assessment tool to create the graph. The visualization shows class level call counts to help you understand the traffic patterns of your application. This visual representation helps you to focus resources during the extraction process and to isolate areas of high value. The runtime profiler is a .dll file that must be included when you run your application in a test or integration environment with data that is representative of the production environment. CLR profiling is supported. For steps to run the profiler, see the Runtime profiling prerequisites (p. 9).
Service limits
AWS Microservice Extractor for .NET has the following limits.
• Large applications may reduce the performance of the Microservice Extractor application.
• Some failure modes are detected later in the Microservice Extractor workflow.
• If the loading status persists for several minutes on the visualization, please contact us at aws- [email protected].
• If the application build fails, the Microservice Extractor tool may continue its analysis. If the visualization does not appear, verify that the application can build successfully using MSBuild.
Information collected
Usage data sharing is enabled by default. You can disable usage data sharing by clearing the check box for usage data sharing on the AWS Microservice Extractor for .NET Settings page .
When usage data sharing is enabled, Microservice Extractor collects the following information when you onboard your source code:
• Success and failure operations performed during onboarding, static code analysis, application build, and graph creation.
• Resources consumed during operations, such as CPU and memory usage.
• Number of nodes and dependencies.
• Number of detected islands.
Microservice Extractor doesn’t collect proprietary information, such as source code. In case of failure, the tool might collect stack traces to improve product experience.
Microservice Extractor uses the information collected to continuously improve its API replacement suggestions. Microservice Extractor periodically analyzes the collected information and updates its replacement engine so that the Microservice Extractor experience is continuously improved.
Prerequisites
Get started with AWS Microservice Extractor for .NET
This section describes the prerequisites, installation procedure, and steps to get started using AWS Microservice Extractor for .NET.
Getting started topics
• Prerequisites to use AWS Microservice Extractor for .NET (p. 7)
• Install AWS Microservice Extractor for .NET (p. 9)
• Use AWS Microservice Extractor for .NET (p. 11)
Prerequisites to use AWS Microservice Extractor for .NET
This section describes the prerequisites for installing and using Microservice Extractor.
• Prerequisites for analysis and extraction of monolithic application (p. 7)
• Required AWS Identity and Access Management policies (p. 8)
Prerequisites for analysis and extraction of monolithic application
To use Microservice Extractor to analyze and extract a monolithic application to deploy into smaller services, you must have the following:
• A valid AWS CLI profile to publish metrics. For information about how to configure an AWS CLI profile, see Configuring the AWS CLI.
• A monolithic application that must be a .NET Framework ASP.NET web service application hosted on IIS with the .NET Framework developer pack installed.
• The ability to build the application solution with MSBuild.
• One of the following operating systems for analyzing the application and creating the visualization:
• Windows 10 or later
• Windows Server 2016 or later
• For the application analysis, you must have:
• .NET Framework version 4 or later compatibility with source code solution.
• 10 GB minimum of free disk space, in addition to the size of your application.
• 8 GB minimum of available memory.
• Compute power equivalent to or greater than that of an Intel Core i3 3-GHz processor.
• For the extraction, you must have:
Required IAM policies
• .NET Framework version 4.7 or 4.8 compatibility with source code solution.
• 20 GB minimum of free disk space, in addition to twice the size of your application.
Required AWS Identity and Access Management policies
To perform certain operations using AWS Microservice Extractor for .NET, you must attach AWS Identity and Access Management (IAM) policies to your IAM user. This section includes the policies that you must attach to your IAM user, and also instructions for attaching IAM policies to an IAM user.
You must use a valid AWS CLI profile to use the assessment tool and run the commands to complete an extraction. For information about how to configure your AWS CLI profile, see Configuring the AWS CLI.
How to attach an IAM policy to an IAM user
Perform the following steps to attach an IAM policy to an IAM user to grant permissions.
1. Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2. In the left navigation pane, choose Policies.
3. Choose Create policy.
4. Choose the JSON tab and copy and paste the policy into the text box.
5. Choose Review Policy and enter a Name and Description for the policy.
6. Choose Create Policy.
7. Filter the list of policies with the name of the policy that you just created.
8. Select the radio button next to your new policy, and from the Policy actions dropdown, select Attach.
9. Select the User name of the IAM user to which to attach the policy.
10.Choose Attach policy.
11.When you select an AWS profile from the dropdown in the Set up Microservice Extractor page of the tool, select the same IAM profile to which you attached the following permissions policies.
Permissions to use the AWS Microservice Extractor for .NET assessment tool
To use the AWS Microservice Extractor for .NET assessment tool, you must create an IAM policy that includes the following permissions attached to your IAM user. To view the type of application data collected by Microservice Extractor, see Information collected (p. 6).
{
"Version": "2012-10-17", "Statement": [
{
"Effect": "Allow", "Resource": [ "*"
],
"Action": [
"serviceextract:GetConfig"
] },
Install
{
"Sid": "SectionForMetricsService", "Effect": "Allow",
"Action": "execute-api:invoke", "Resource": [
"arn:aws:execute-api:us-east-1:*:*/prod/POST/put-metric-data", "arn:aws:execute-api:us-east-1:*:*/prod/POST/put-log-data"
] } ]}
Install AWS Microservice Extractor for .NET
This topic describes how to install AWS Microservice Extractor for .NET. It includes steps to configure prerequisites to use the runtime profiling agent on your application. You must configure the runtime profiling prerequisites after you download the Microservice Extractor installer.
Installation topics
• Installation (p. 9)
• Runtime profiling prerequisites (p. 9)
Installation
AWS Microservice Extractor for .NET is available for download as an executable file (ServiceExtract.exe):
Download Microservice Extractor
For optional integrity detection, you can download the SHA256 checksum of the installer.
To use the checksum file, calculate the SHA256 on your downloaded .exe file to compare against the output of the following PowerShell command:
Get-FileHash -Algorithm SHA256 Service-Extract.exe
You can verify the authenticity of the signatures of the Microservice Extractor .exe file by running the following command, which verifies that a valid certificate is contained in the file.
Get-AuthenticodeSignature <file-name>
After you have downloaded the .exe file, and performed optional integrity checks, you can run the installation executable for the Microservice Extractor assessment tool on your local computer.
When the installation completes, you can find the ServiceExtractProfiler.dll in C:\Users
\<username>\AppData\Local\Programs\AWS Microservice Extractor for .NET
\resources\AWS Tools\serviceextract-profiler\ServiceExtractProfiler.dll
Runtime profiling prerequisites
To use the runtime profiling agent on your application, you must configure the following prerequisites after you have downloaded the ServiceExtract.exe file.
Runtime profiling prerequisites
1. To ensure that IIS manager can access the .dll or output folder, copy the .dll from the default path into the inetpub folder (for example, C:\inetpub\wwwroot\...), which is the default folder for IIS. In addition, verify that your IIS user has read/write access to the output directory.
2. Create a folder for the Microservice Extractor runtime profiler to output to.
3. Register the Microservice Extractor runtime profiler on the server on which the application is running using one of the following commands. This step is not necessary for .NET Framework version 4 or later.
Windows 64-bit version:
%systemroot%\System32\regsvr32.exe C:\Users\<username>\AppData\Local\Programs
\AWS Microservice Extractor for .NET\resources\AWS Tools\serviceextract-profiler
\ServiceExtractProfiler.dll
Windows 32-bit version:
%systemroot%\SysWoW64\regsvr32.exe C:\Users\<username>\AppData\Local\Programs
\AWS Microservice Extractor for .NET\resources\AWS Tools\serviceextract-profiler
\ServiceExtractProfiler.dll
4. Set relevant environment variables before starting the target binary. You must manually update the following system variables.
COR_ENABLE_PROFILING enables profiling COR_ENABLE_PROFILING=1
COR_PROFILER specifies the profiler to use using CLSID or ProgID COR_PROFILER={DCF75470-C2FC-4198-88EE-D07740A3FB9B}
COR_PROFILER_PATH specifies the path of the serviceextract profiler
COR_PROFILER_PATH=C:\Users\<username>\AppData\Local\Programs\AWS Microservice Extractor for .NET\resources\AWS Tools\serviceextract-profiler\ServiceExtractProfiler.dll SERVICEEXTRACT_PROFILER_OUTPUT_DIR specifies the output directory used by the profiler SERVICEEXTRACT_PROFILER_OUTPUT_DIR=C:\ProfilerOutput
SERVICEEXTRACT_PROFILER_TARGET_DLL specifies the output directory used by the profiler SERVICEEXTRACT_PROFILER_TARGET_DLL=<your-target-app.dll>
Here is an example of how to configure IIS with the necessary environment variables in the applicationHost.config file:
<applicationPools>
<add name="DefaultAppPool" />
<add name="<YourSiteName>" autoStart="false" />
<add name=".NET v4.5 Classic" managedRuntimeVersion="v4.0"
managedPipelineMode="Classic" />
<add name=".NET v4.5" managedRuntimeVersion="v4.0" />
<add name="<YourSiteName2>" autoStart="false" />
<applicationPoolDefaults managedRuntimeVersion="v4.0">
<processModel identityType="ApplicationPoolIdentity" />
<environmentVariables>
<add name="COR_ENABLE_PROFILING" value="1" />
<add name="COR_PROFILER" value="{DCF75470-C2FC-4198-88EE-D07740A3FB9B}" />
<add name="COR_PROFILER_PATH" value=" C:\Users\<username>\AppData\Local
\Programs\AWS Microservice Extractor for .NET\resources\AWS Tools\serviceextract- profiler\ServiceExtractProfiler.dll
<add name="SERVICEEXTRACT_PROFILER_OUTPUT_DIR" value="C:\ProfilerOutput" />
<add name="SERVICEEXTRACT_PROFILER_TARGET_DLL" value="<your-target- app.dll>" />
</environmentVariables>
Use Microservice Extractor
</applicationPoolDefaults>
</applicationPools>
When the manual configuration completes, the runtime profiler automatically captures metrics when you run your application. Perform typical workloads and test cases while running your application to capture relevant metrics for an application assessment. After shutting down the application pool in IIS, a .csv file will be created by the profiler for you to upload to the Microservice Extractor tool for the assessment. You can find the .csv file at the output directory configured in the previous step for SERVICEEXTRACT_PROFILER_OUTPUT_DIR.
Use AWS Microservice Extractor for .NET
This section contains information to help you get started with AWS Microservice Extractor for .NET after verifying that the required prerequisites (p. 7) are met. When you start Microservice Extractor for
the first time, you are prompted to enter your AWS CLI profile information so that Microservice Extractor can collect metrics to improve your experience. These collected metrics also help to flag issues with the software so that AWS can quickly address them. If you have not set up your AWS profile, see Configuring the AWS CLI.
Using Microservice Extractor topics
• Set up AWS Microservice Extractor for .NET (p. 11)
• Onboard an application (p. 12)
• View application details (p. 12)
• Launch application visualization (p. 13)
• Work with the application visualization (p. 13)
• Extract parts of an application as independent services (p. 16)
• Manually deploy as independent service (p. 17)
• Failure modes (p. 17)
• Remove an application from AWS Microservice Extractor for .NET (p. 18)
• Edit application details (p. 18)
• Edit user settings (p. 18)
Set up AWS Microservice Extractor for .NET
Perform the following steps to set up AWS Microservice Extractor for .NET.
1. Verify that you have completed the prerequisite steps (p. 7) to use Microservice Extractor.
2. From the Microservice Extractor landing page, choose Get started.
3. From the Setup Microservice Extractor page, select an AWS named profile from the dropdown list, or Add a named profile. Microservice Extractor uses your AWS named profile to share your Microservice Extractor usage data with AWS to make the Microservice Extractor tool better. For more information about named profiles, see Named profiles in the AWS CLI User Guide.
4. Add or update the Working directory used to store the output from the application analysis and extraction of your application. You cannot change this directory after the application is set up.
5. Update the MSBuild path to build the application. If the path is not updated, the listed Default path will be used.
6. Microservice Extractor usage data sharing is enabled by default. To view the types of data collected, see Information collected (p. 6). Clear the check box selection to disable usage data sharing.
Onboard
7. Choose Next to onboard your application.
Onboard an application
To onboard your application, perform the following steps.
1. Navigate to the Applications page of the Microservice Extractor tool by either choosing it from the left navigation pane of the application, or by choosing Next from the Setup AWS Microservice Extractor for .NET page. In the Applications component, choose Onboard application. The
Onboard application option is disabled if you have not selected an AWS named profile from the Set up Microservice Extractor page.
2. On the Onboard application page, enter the following information for the application you want to onboard.
• Application details. Enter a Name and optional Description for your application.
• Source code. Provide the ASP.NET solution file (for example, the .sln file). Choose the application project file to upload to Microservice Extractor. The file must be buildable and use ASP.NET. The source code and its dependencies must be local to the on-premises machine or Amazon EC2 instance on which Microservice Extractor is run.
NoteMicroservice Extractor uses MSBuild to build your application. If your application uses custom build scripts, you will encounter an error during the application analysis.
• Runtime profiling data — optional. Upload the outputted .csv file from the runtime
profiling performed for your application. For steps to run the profiler, see the Runtime profiling prerequisites (p. 9). You can find the outputted .csv file in the output directory configured for the SERVICEEXTRACT_PROFILER_OUTPUT_DIR environment variable.
NoteYou can't change the source code or runtime profiling data that was input after onboarding. If you want to make changes to these input files, you must onboard the application as a new application.
• Analyze .NET Core portability — optional. If Porting Assistant for .NET is installed on your local machine, you can choose to include .NET Core compatibility data in the visualization of your application.
3. Choose Onboard Application. Microservice Extractor analyzes your source code and uses the analysis and runtime metrics to produce a graphical representation of your application.
4. When the analysis completes, the application will show a build status of Success on the
Applications page. From here, you can select the application and choose Launch visualization, or choose View dependency graph in the build success banner. The graph shows node dependencies, runtime metrics, such as runtime call counts, and static references between code artifacts, such as classes. If you choose the application name, you are taken to the Application details page, where you can view and edit the details you entered when you onboarded the application.
If the application shows a build failed status, review the error message, and choose Update source code to remediate.
NoteWe recommend that you wait until the build status shows Success before you navigate to the View details page.
View application details
When an application is successfully onboarded, you can view details about the application by choosing it from the Applications page. You will be taken to the Application details tab. From here, you can
Launch visualization
view and Edit the application details. If you previously launched the visualization for the application, you can choose the Visualization (nodes and dependencies) tab to view the graphical visualization of your application. For more information about how to work with the visualization, see Work with the application visualization (p. 13).
The application details page displays a summary of the onboarding details that you entered for the application. It also includes the location of the application logs, log status, and descriptions of any log errors. You can edit the name and description, source code files, and runtime profiling data by choosing Edit. If you make changes to the application details, the application analysis is performed again, and the application visualization is refreshed. If you cancel the edit, no changes will be applied.
Launch application visualization
After you onboard an application, you can launch the visualization of the application from the
Applications page to better conceptualize and group your application nodes. Select the application for which you want to view the visualization and choose Launch visualization. You will be taken directly to the Visualization (nodes and dependencies) tab of the application page.
From the Visualization (nodes and dependencies) page, you can view, in graph form, the logically grouped functionalities identified by Microservice Extractor to be extracted as isolated services.
For selected nodes, you can view .NET core portability. You can apply the default groups, modify them, or create new groups to associate with a functionality that guides refactoring. You can also Explore alternate visualizations for grouping, such as the Namespace view, which arranges the nodes by namespace, and the Island view, which shows parts of the application separated out as groups of nodes for extraction. For more details on graph functionality, see Work with the application visualization (p. 13).
Work with the application visualization
The Visualization tab displays the application nodes and dependencies in graphical format. The initial view on the Visualization tab is the main view. The circles represent nodes, and the arrows show dependencies and direction between nodes, incoming or outgoing. If you choose Explore alternate visualizations for grouping, Microservice Extractor groups your application nodes according to
namespaces or islands. By default, no groups are created. The main view reflects any updates you make to your groupings using the alternate visualization.
Visualization topics
• Features of the AWS Microservice Extractor for .NET visualization tool (p. 13)
• Main visualization (p. 15)
• Alternate visualization (p. 15)
Features of the AWS Microservice Extractor for .NET visualization tool
You can perform the following tasks from the Visualization (nodes and dependencies) page to help you group your application nodes to extract as a smaller service.
• Create custom groups to visualize a segmentation of the service You can create groups in the following ways:
• Drag and drop (main view only) — Select one or more nodes by clicking on them, then drag the node or nodes together.
• Choose or right-click (main and alternate views) — Choose or right-click a node to open the Actions menu. From the Actions menu, you can choose to Add node to group. The Add node(s) to
Work with visualization
group pane appears on the right, where you can choose to add nodes to an existing group or create a new group, and select the Group name and, optionally, the Group color .
Groups are indicated by dotted rectangles. You can collapse and expand groups by choosing the minimize and maximize icons in the left corner of each rectangle. Collapsing a rectangle helps to reduce visual noise as you focus on other areas of the service.
• View node details
Select one or more nodes. Selected nodes are indicated by a dotted circle. Incoming and outgoing dependencies for the selected nodes are highlighted as red (outgoing) or blue (incoming). If you select more than one node, each selected node will appear as dotted, and the dependencies will be highlighted for all of the selected nodes. When you choose or right-click on a node, you can select View node details from the Actions menu. The Node details panel appears on the right. Node details include the following tabs and information for one or more selected nodes:
• General — Shows the selected nodes, their dependencies, and runtime profiling information. The arrows, or Edges show the direction of the dependency, incoming or outgoing. The call count for each node dependency is also displayed.
• .NET Core portability — Shows the selected nodes and their .NET Core portability status. If a node is not compatible for .NET Core portability, hover over the status message to view the details and potential remediation.
• Reset view
Choose Reset view to reset the visualization to the original state, or as it was arranged when you first launched it. All new groups are removed, and all changes will be discarded.
• Add nodes to a namespace group (Alternate visualization for grouping your application) From the Alternate visualization for grouping your application view, under the Namespace view tab, choose a node or namespace, and choose or right-click on it to add it to a namespace group. From the Actions menu, choose Add node to group and add the details about the group to which the node should be added in the Add node(s) to group pane on the right. When you return to the main view, your updates in the namespace view will be reflected. Note that you cannot drag and drop nodes in the Namespace view.
• View namespace details (Alternate visualization for grouping your application)
From the Alternate visualization for grouping your application view, under the Namespace view tab, choose a node or namespace, and choose or right-click it to view namespace details. From the Actions menu, choose View namespace details. The Namespace details pane appears on the right, which displays the following information:
• General — Displays the selected nodes, their dependencies, and information about possible shared state access.
• Node summary — Displays the edges between nodes.
When you return to the main view, any updates you made in the namespace view will be reflected.
• View islands, and add nodes to an island
The Island view displays the nodes arranged as independent islands of connected nodes. No dependencies are detected to or from nodes within an island and nodes within other islands. The Island view helps you to identify potential node groupings to extract as independent services.
When you return to the main view, any updates you made in the Island view will be reflected. You cannot drag and drop nodes in the Island view.
• View Legend
The Legend displays the meanings of the symbols in the visualization.
Work with visualization
• A dotted circle indicates a selected node.
• A gray rectangle indicates a group.
• A gray rectangle that contains an expand icon indicates a collapsed group.
• A blue arrow indicates a dependency incoming to a node.
• A red arrow indicates a dependency outgoing from a node.
• View Group classification
Choose Group classification from the bottom of the visualization to view the name, ID, and color assigned to each group in the visualization.
• View runtime profiling information
You can view the number of call counts from the main view by hovering over the arrows in the visualization. From the Alternate visualization for grouping your application view, you can hover over the rectangle edges to view the number of nodes, and incoming and outgoing dependencies.
• Search and filter
From the main visualization page, you can search and filter by Class ID or Group name by selecting either option from the dropdown list of the search bar, and then entering the Class ID or Group name in the search bar. You can clear your filters by selecting Clear filters.
• Edit group name and color
After you have created a group, you can edit the name and color of the group by choosing or right- clicking it to open the Actions menu, then choosing Edit group name and color. You can update the group name and color in the Edit group name and color pane that appears on the right.
Main visualization
After you onboard an application, Microservice Extractor displays its nodes and dependencies as a graph.
No groups are created by default. You can create groups, modify them, or create new groups to associate with a functionality that guides refactoring. Use the main visualization to view your groups and prepare for extraction after creating groups in the main visualization, or after exploring recommended groupings based on namespace and islands using the alternate visualization.
Manually remove node dependencies to prepare parts of your application for extraction as smaller services. The parts are displayed as groups in the graph. Microservice Extractor can also extract API endpoints as separate services by isolating the code that underlies the API endpoints and replacing local calls with network calls. This creates a new implementation of the calling class in a new solution, while preserving the interface and original solution. You can then develop, build, and deploy the new repositories independently as services.
For more information about actions you can take from the main visualization, see Features of the AWS Microservice Extractor for .NET visualization tool (p. 13).
For help with grouping your application by namespace or islands, use the alternate visualization (p. 15).
Alternate visualization
You can explore suggested groupings for your nodes by choosing Explore alternate visualizations for grouping from the main visualization. The Alternate visualization for grouping your application page displays tabs for Namespace view and Island view.
Namespace view
The Namespace view displays nodes grouped by namespace. Namespace groups are represented by dotted rectangles. You can add and remove nodes from a group by choosing or right-clicking a node,
Extract as independent services
which displays a menu of options. This menu includes options to Add node to group and Remove node from group. When you select one of these options, you can customize the nodes to add or remove using the right-hand pane.
If you are working with a large application and want to collapse a namespace group, choose the minimize symbol in the upper left corner of the rectangle. Choose the expand symbol to reopen it.
To add all nodes from a single namespace to a group, right-click on a namespace and choose Add all nodes to group.
To view details about a namespace, choose or right-click a group or node, and choose View namespace details. The details will appear in the Namespace details pane on the right. If a class accesses a state that is shared by classes that belong to multiple groups in the application, modification of the shared state may result in errors when you extract the nodes as a smaller service. If the Shared state access detected message appears next to a class, check whether the class accesses a state that is shared by classes that belong to other groups. If so, update your application source code to remove access to the shared state.
You can view runtime profiling information (call count and dependency direction) by hovering over the edges of a group.
Return to the main view at any time by choosing Back to main view. When you return to the main view, any updates you made in the namespace view will be reflected.
Island view
The Island view displays the nodes arranged as independent islands of connected nodes. No
dependencies are detected to or from nodes within an island and nodes within other islands. The Island view helps you to identify potential node groupings to extract as independent services.
You can return to the main view at any time by choosing Back to main view. When you return to the main view, any updates you made in the Island view will be reflected.
For more information about actions you can take from the alternate visualization, see Features of the AWS Microservice Extractor for .NET visualization tool (p. 13).
Extract parts of an application as independent services
Review the arrangement of the group or groups you selected and their individual nodes and
dependencies on the main view of the Visualization (nodes and dependencies) page. When you are satisfied with your groups, choose Extract group as service and perform the following steps:
1. On the Review details and initiate extraction page, review and verify the Service details and the Extraction details. Address all of the issues listed for the nodes and dependencies. To view the description of an issue, select the Shared state access detected or Requires attention alert under Comments. Select the corresponding Class ID to view and address the issue in the source code.
If a class accesses a state that is shared by classes that belong to multiple groups in the application, modification of the shared state may result in errors when you extract the nodes as a smaller service.
If the Shared state access detected message appears next to a class, check whether the class accesses a state that is shared by classes that belong to other groups. If so, update your application source code to remove access to the shared state. Analyze the application again before proceeding with the extraction.
The following shared state accesses are detected:
• TempData property in ControllerBase class.
Manually deploy
• Session property in Controller class.
2. Select an option under Method invocations from application to extracted service. Consider the following limitations for each method:
• Use remote method invocations — network calls can add additional overhead to user requests.
Manual verification and refactoring may be required to ensure accuracy.
• Use local method invocations — code duplication from manual refactoring can introduce conflicting states in the application.
3. When you are satisfied with the extraction details, choose Extract. The progress of the extraction is displayed at the top of the page . To cancel the extraction, in the extraction progress banner, select Cancel extraction. If you cancel the extraction, the extraction configuration is deleted, and you must restart the extraction.
A successful extraction will display the output location of the extraction in the green status banner.
To view the extraction details, choose View details on the status banner.
If the extraction fails, the red status banner displays an error message. Navigate to the Visualization page to verify and address issues with the unsupported classes and try again.
View and edit extraction details
You can view the details of the extraction from the Application details page by selecting the radio button next to the Service name under Extractions, and choosing View details from the Actions dropdown. On the service details page, you can view the Extraction details and Nodes and dependencies. To edit the extraction details, choose Re-extract service from the Actions dropdown. You must re-extract a service in order to edit its configuration.
Manually deploy as independent service
To deploy parts of your application as smaller services, we recommend that you set up the following environment:
• Docker version 17.05 installed locally with administrator access
• An AWS profile with an attached policy that grants permissions to write to Amazon Elastic Container Registry and Amazon S3
• Windows Server 2019 or later
• A minimum of 50 GB of free disk space
To deploy the extracted service as an independent service, perform the following high-level steps:
1. Refactor the source code, if necessary, to ensure that the extracted service builds successfully.
2. Navigate to the output location of the extracted service.
3. From the Dockerfile, manually create a Docker container image.
4. Push the Docker container image to Amazon Elastic Container Registry (Amazon ECR).
5. Use AWS CloudFormation to deploy the container image hosted in Amazon ECR to Amazon Elastic Container Service (ECS). For more information, see Using Amazon ECR with Amazon ECS and Creating Amazon ECS resources with AWS CloudFormation.
Failure modes
What used to be called a function call is now a network call. A network call can fail for various reasons;
for example, network connectivity, service outages, authentication errors, or unknown server errors.
Remove application
While Microservice Extractor provides some handling for these new types of errors, you may want to update them to accommodate your error-handling scheme.
We recommend copying artifacts or package dependencies that lie outside the scope of the directory of your solution (with the exception of standard “reference assemblies” installed in known locations) into your solution directory, and adjusting project files to point to the updated location before starting automatic refactoring.
Remove an application from AWS Microservice Extractor for .NET
To remove an application from Microservice Extractor, perform the following steps:
1. From the left navigation pane, choose Applications.
2. Select the radio button next to the application that you want to remove, and from the Actions menu, select Remove application from list. When you remove an application, all of the contents in the working directory will be removed, and you will no longer be able to manage the application in Microservice Extractor.
Edit application details
To edit the details of an application, perform the following steps.
1. From the left navigation pane, choose Applications.
2. Select the radio button next to the application for which you want to edit the details. From the Action menu, select Edit application details.
3. On the Edit details page, you can update the application Name and Description, the Source code file locations, and the Runtime profiling data file location.
NoteWhen you update the source code file or profiling data output file, Microservice Extractor performs a new application analysis and refreshes the visualization of the application.
Edit user settings
To change your user settings, perform the following steps.
1. From the left navigation pane of the Microservice Extractor tool, choose Settings.
2. On the Settings page, select Edit.
3. On the Edit settings page, you can update your AWS named profile and your Microservice Extractor usage data sharing option. You cannot change your working directory after your application is set up.
Data protection
AWS Microservice Extractor for .NET security
Cloud security at AWS is the highest priority. As an AWS customer, you benefit from data centers and network architectures that are built to meet the requirements of the most security-sensitive organizations. Security is a shared responsibility between AWS and you. The shared responsibility model describes this as security of the cloud and security in the cloud:
• Security of the cloud – AWS is responsible for protecting the infrastructure that runs AWS services in the AWS Cloud. AWS also provides you with services that you can use securely. Third-party auditors regularly test and verify the effectiveness of our security as part of the AWS Compliance Programs.
For more information about the compliance programs that apply to Microservice Extractor, see AWS Services in Scope by Compliance Program.
• Security in the cloud – Your responsibility is determined by the AWS service that you use. You are also responsible for other factors including the sensitivity of your data, your company’s requirements, and applicable laws and regulations.
This documentation helps you understand how to apply the shared responsibility model when using AWS Microservice Extractor for .NET. The following topics show you how to configure Microservice Extractor to meet your security and compliance objectives. You also learn how to use other AWS services that help you to monitor and secure your Microservice Extractor resources.
Security topics
• Data protection in AWS Microservice Extractor for .NET (p. 19)
• Identity and Access Management in AWS Microservice Extractor for .NET (p. 20)
• Configuration and vulnerability analysis in AWS Microservice Extractor for .NET (p. 21)
• Security best practices (p. 21)
Data protection in AWS Microservice Extractor for .NET
The AWS shared responsibility model applies to data protection in AWS Microservice Extractor for .NET.
As described in this model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud. You are responsible for maintaining control over your content that is hosted on this infrastructure. This content includes the security configuration and management tasks for the AWS services that you use. For more information about data privacy, see the Data Privacy FAQ. For information about data protection in Europe, see the AWS Shared Responsibility Model and GDPR blog post on the AWS Security Blog.
For data protection purposes, we recommend that you protect AWS account credentials and set up individual user accounts with AWS Identity and Access Management (IAM). That way each user is given only the permissions necessary to fulfill their job duties. We also recommend that you secure your data in the following ways:
• Use multi-factor authentication (MFA) with each account.
• Use SSL/TLS to communicate with AWS resources. We recommend TLS 1.2 or later.
• Set up API and user activity logging with AWS CloudTrail.
Data collected by AWS Microservice Extractor for .NET
• Use AWS encryption solutions, along with all default security controls within AWS services.
• Use advanced managed security services such as Amazon Macie, which assists in discovering and securing personal data that is stored in Amazon S3.
• If you require FIPS 140-2 validated cryptographic modules when accessing AWS through a command line interface or an API, use a FIPS endpoint. For more information about the available FIPS endpoints, see Federal Information Processing Standard (FIPS) 140-2.
We strongly recommend that you never put confidential or sensitive information, such as your customers' email addresses, into tags or free-form fields such as a Name field. This includes when you work with Microservice Extractor or other AWS services using the console, API, AWS CLI, or AWS SDKs. Any data that you enter into tags or free-form fields used for names may be used for billing or diagnostic logs. If you provide a URL to an external server, we strongly recommend that you do not include credentials information in the URL to validate your request to that server.
Encryption at rest
Data within AWS Microservice Extractor for .NET is not encrypted at rest.
Encryption in transit
For configuration and metrics, Microservice Extractor makes requests to the server over the Transport Layer Security protocol (TLS).
Data collected by AWS Microservice Extractor for .NET
Usage data sharing is enabled by default. You can disable usage data sharing by clearing the check box for usage data sharing on the AWS Microservice Extractor for .NET Settings page .
When usage data sharing is enabled, Microservice Extractor collects the following information when you onboard your source code:
• Success/failure operations performed during onboarding, static code analysis, application build, and graph creation.
• Resources consumed during operations, such as CPU and memory usage.
• Number of nodes and dependencies.
• Number of detected islands.
Microservice Extractor doesn’t collect proprietary information, such as source code. In the case of failure, the tool might collect stack traces to improve product experience.
Identity and Access Management in AWS Microservice Extractor for .NET
AWS Identity and Access Management (IAM) is an AWS service that helps an administrator securely control access to AWS resources. AWS Microservice Extractor for .NET is a standalone application that does not require IAM access control to use resources.
To use Microservice Extractor, you must attach the policy for permissions to use the Microservice Extractor assessment tool to your IAM user. These policies are provided in the Prerequisites (p. 7) section of this guide.
Configuration and vulnerability analysis
Configuration and vulnerability analysis in AWS Microservice Extractor for .NET
When AWS Microservice Extractor for .NET requires updates, you are notified and must install the latest version of the application upon restart. You maintain the system patching responsibility, per the shared responsibility model.
Security best practices
AWS Microservice Extractor for .NET provides security features to consider as you develop and implement your own security policies. The following best practice is a general guideline and doesn’t represent a complete security solution. Because this best practice might not be appropriate or sufficient for your environment, treat it as a helpful consideration rather than a prescription.
Implement least privilege access
When you attach the IAM (p. 20) policies as inline policies to your IAM user, grant only the permissions that are required to perform the specified task. Implementing least privilege access is fundamental in reducing security risk and the impact that could result from errors or malicious intent.
AWS profile errors
Troubleshooting AWS Microservice Extractor for .NET
The following remediation strategies can help you troubleshoot problems with AWS Microservice Extractor for .NET.
Troubleshooting topics:
• AWS profile errors (p. 22)
• Build failures (p. 22)
• Extraction errors (p. 23)
• Application artifact location (p. 23)
• Onboarding and visualization errors (p. 23)
• Creating groups (p. 24)
• Uninstalling application (p. 24)
• Metrics and logs collected by AWS Microservice Extractor for .NET (p. 24)
• Questions and feedback (p. 24)
AWS profile errors
Description
An error regarding the specified AWS profile is returned. For example:
The specified AWS profile is invalid or does not have permission to send metrics to AWS.
Please refer to the Microservice Extractor User Guide for instructions on how to setup a valid AWS profile for use with Microservice Extractor.
Solution
• Verify that you have attached the required AWS Identity and Access Management (IAM) policies to your IAM user. To view the required policies, see the Microservice Extractor prerequisites (p. 7).
• Add a named AWS profile with proper credentials, if required. For more information, see Named profiles in the AWS CLI User Guide.
Build failures
Description
The build fails when you attempt to build your repositories.
Solution
Verify the following:
• The application is supported by Microservice Extractor. See Prerequisites for analysis and extraction of monolithic application (p. 7) to view the application prerequisites.
• You have installed MSBuild, and Microservice Extractor is pointing to it on the Settings page.
Extraction errors
• MSBuild is working properly. Check the MSBuild log on the Application details page. If there is no preview, or choosing the log returns an error, then MSBuild is likely failing. Verify that you can build the application manually to see if MSBuild is working properly.
• Microservice Extractor is using the same MSBuild version as your installed version of Visual Studio. If the versions don't match, you can update the MSBuild version used by Microservice Extractor from the Settings page.
• Relevant switches are added to the .csproj file so that the default msbuild operation can use them.
By default, Microservice Extractor appends the RestorePackagesConfig and restore switches to restore NuGet packages during build.
Extraction errors
Description
When you attempt to extract segments of your code as independent services, an error is returned.
Solution
For the following error:
Command failed: failed to run build command on ...\MyApp.sln: failed to execute command:
exec: "msbuild": executable file not found in %PATH%
• Verify that you have installed MSBuild and Microservice Extractor is pointing to it on the Settings page.
• Add MSBuild to the system path environment variable.
Check logs
• The <working Dir> referenced in this section refers to the working directory configured on the Settings page. You can determine the cause of most extraction failures by viewing
<workingDir>\logs\serviceextract-extraction.log. Generally, the last line in this file contains a message with the cause of the error.
• If the error message in the log refers to a build failure, check <workingDir>\logs\msbuild.log for details. Note that the extraction builds both the new service and the modified original application. The output of each of these builds is sent to msbuild.log.
• If the error message refers to a failure to download packages, check <workingDir>\logs
\nuget.log for details.
Application artifact location
To determine the application artifact file location, do the following:
1. Find the application ID in the Summary section of the Application details page.
2. The directory of the corresponding application is: C:\Users\<username>\AppData\Roaming
\ServiceExtract\version-1\cache\version-<versionNumber>\<applicationId>
Onboarding and visualization errors
If you are encountering problems onboarding an application and viewing the visualization, try the following solutions:
Creating groups
1. The metric policy may not be properly configured. Check the Electron main application log to check for the last succeeded state and high-level errors. If the metrics policy is not properly configured, the log file should display many error messages about metrics.
2. Check the directory of the corresponding application ID for the following intermediate artifact files:
edges.csv and vertices.csv inside of the data-extraction-output folder.
Creating groups
If you experience problems when creating groups, perform the following steps:
1. Check in the directory for the corresponding application ID for the following intermediate artifact file:
tags.csv inside of the tags-data folder.
2. Verify that the groupings are correctly reflected in the file.
3. Choose Reset view to remove all of the groups, and try again.
Uninstalling application
If you encounter issues when attempting to uninstall the application as a non-admin user when using the Apps and Features interface in Windows, perform the following steps:
1. Open Control Panel>Uninstall a program. Or, choose the Windows icon>Run> and enter appwiz.cpl.
2. Choose AWS Microservice Extractor for .NET from the list of installed applications, and select Uninstall to remove the application and its installation files.
Metrics and logs collected by AWS Microservice Extractor for .NET
AWS Microservice Extractor for .NET collects metrics and logs in the following location of the server or desktop where the tool runs: C:\Users\<username>\AppData\Roaming\ServiceExtract\logs.
Check logs
• You can determine the cause of most extraction failures by viewing C:\Users
\<username>\AppData\Roaming\ServiceExtract\logs\serviceextract-extraction.log.
In most cases, the last line of this file includes a message about the cause of an error.
• If the error message in the log refers to a build failure, check C:\Users\<username>\AppData
\Roaming\ServiceExtract\logs\msbuild.log for details. Note that the extraction builds both the new service and the modified original application. The output of each of these builds is sent to msbuild.log.
• If the error message refers to a failure to download packages, check C:\Users
\<username>\AppData\Roaming\ServiceExtract\logs\nuget.log for details.
Questions and feedback
If you have questions that are not addressed in the AWS Microservice Extractor for .NET technical documentation, contact <[email protected]>.
Questions and feedback
You can also provide feedback by choosing Feedback in the upper right-hand corner of this page.
AWS Microservice Extractor for .NET User Guide document history
The following table describes the documentation for this release of AWS Microservice Extractor for .NET.
• API version: latest
• Latest documentation update: November 30, 2021
update-history-change update-history-description update-history-date AWS Microservice
Extractor for .NET general availability (p. 1)
You can reduce the time and effort required to break down large, monolithic applications running on the AWS Cloud or on premises into smaller, independent services.
November 30, 2021
