ReSharper Help

Structural Search and Replace

ReSharper | Find | Search with Pattern…
ReSharper_StructuralSearchSearch

Standard search methods, like searching for usages of a certain symbol or text occurrences that hat match some regular expression do not give the desired results. For example, you may need to find code smells specific to your project or find pieces of code that need to be refactored.

ReSharper allows you to find and, if necessary, replace blocks of code match a specific pattern. These blocks may be quite different - they could contain different types, expressions, statements, etc, but they would be logically similar. For example, you can create a general pattern that will match all foreach loops independently of what is iterated and what is inside the loop, or you can make this pattern more detailed to find only loops that iterate over a specific type. The pattern can be as complex as you need and have any desired level of detail.

All patterns that you create are stored in your pattern catalog and act as custom code inspections with custom severity levels. This means that all code blocks that match a specific pattern can be highlighted in the editor as hints, suggestions, warnings, or errors. Quick-fixes are also provided for the patterns - they could transform matched code blocks as defined in the 'replace' part of the pattern.

In this topic:

Placeholders in search patterns

A pattern normally consists of:

  • A textual part, which must contain only identifiers allowed in the target language. With the textual part, you define what should be matched exactly. Note that white spaces, tabulation characters, and line breaks are ignored.
  • Placeholders, which allow matching variable parts of the target code blocks. A placeholder has the following format: $placeholder_name$ - where placeholder_name is an arbitrary identifier.

Each placeholder must be defined once and can be used several times in the pattern. When defining a placeholder, you need to define its kind and optional constraints. There are five kinds of placeholders:

  • Argument Placeholder - one or more arguments in a method invocation. If necessary, you can specify minimal or maximal number of arguments that should be matched.
  • Expression Placeholder - a sequence of operators and operands. You can optionally specify a type that is returned by this expression.
  • Identifier Placeholder - any symbol identifier. You can additionally specify a regular expression that will be used to match symbol names.
  • Statement Placeholder - a single-line statement that ends with a semicolon or a block of statements. If necessary, you can specify minimal or maximal number of statements that should be matched.
  • Type Placeholder - a value type or a reference type. By default, a placeholder of this kind will match any type, but you can specify a specific type explicitly.

Note that it is very important to choose the right kinds of placeholders for specific parts of your pattern. If your pattern does not match the block of code it is meant to matched, the problem is often with incorrectly chosen placeholder kinds.

Placeholders in structural search and replace patterns

Creating a search pattern

To search or replace code blocks, or to create a custom code inspection, you need to create a search pattern. You can use an existing code block as a base for the pattern, or you can create a new one from scratch.

To create a search pattern

  1. In the editor, select a block of code that should be matched by the pattern. This step is optional but it will help you create the pattern faster.
  2. On the main menu, choose menuPath or right-click the selection, if any, and choose Search with Pattern in the context menu. The Search with Pattern dialog will open.
  3. If some code block was selected at the first step, ReSharper detects all symbol names in the block and replaces them with placeholders. If necessary, you can edit the code, add and remove placeholders to get the desired pattern:
    • ReSharper checks that all placeholders used in the pattern have proper definition in the right part of the dialog. If there are placeholders without definitions, they are highlighted with red.
    • To add a new placeholder, just type a $<placeholder_name>$ and its definition will be added automatically.
      Always check the kind of automatically added placeholder definitions. Sometimes, it is not possible to unambiguously define the kind, so you may want to correct it manually.
    • To change the kind of a placeholder or specify constraints, select the placeholder definition on the right, click Edit, and edit the placeholder definition.
    • As soon as you remove a placeholder usage in the pattern body, its definition is removed automatically.
    • It also possible to manually add and remove placeholder definitions. To do so, click the corresponding buttons above the list of placeholder definitions.
  4. Depending on whether or not you want to match similar code blocks, select or clear the Match similar constructs check box. ReSharper considers following constructs as similar:
    1. Single-line statement and single-line statement that is enclosed in braces.
    2. Binary expressions as they are specified in the pattern and in reverse order.
    3. Expressions as they are specified in the pattern and expressions with different order of operands.
    4. Expressions where operands are enclosed in parentheses and expressions where operands are not enclosed.
    5. Postfix and prefix increment operators.
    6. Methods with different access modifiers.
  5. ReSharper performs a basic code analysis in the pattern body. If no errors are found, you can search for the matching code blocks, define how the matched blocks should be replaced, or just click Save to save the pattern to the pattern catalog.

Specifying a replace pattern

For each of your search patterns, you can add a replace pattern, which will allow you to quickly replace code blocks matched by the search pattern.

To specify a replace pattern

  1. Create a new search pattern or open for editing a pattern from the pattern catalog.
  2. In the Search with Pattern dialog, click Replace in the right-top corner.
  3. In the Replace pattern area that appears in the lower part of the dialog, specify the replace part of the pattern.
    Use the placeholders defined in the pattern. When a matched code block is replaced, each piece of code matched by a placeholder is copied according to the position of this placeholder in the replace part.
  4. Use check boxes below the replace area to specify whether to apply formatting rules and/or replace fully-qualified names with short names in the replaced code blocks.
  5. ReSharper performs a basic code analysis in the replace part of the pattern. If no errors are found, you can replace the matching code blocks or save the pattern to the pattern catalog.

Managing the pattern catalog

When you save a created pattern, ReSharper places it in its pattern catalog. To see the catalog and study the existing patterns, go to the Code Inspection | Custom Patterns options page, or just click Pattern Catalog Reference__Search_with_Pattern__Open_Catalogue in the Search with Pattern dialog.

You can do the following in the pattern catalog:

  • To preview a pattern, select it in the list. You will see its body and definitions of placeholders in the bottom of the page.
  • To remove a pattern, select it in the list and click Remove on the page toolbar.
  • To add a new pattern, click Add pattern on the toolbar. ReSharper will open the Search with Pattern dialog where you can specify the pattern details.
  • All patterns are used in the ReSharper's code inspection engine so the matched code blocks are detected automatically.
    By default, all new patterns have 'Do not show' severity level - this means that the matched code blocks are not highlighted in the editor. If you would like to highlight the detected blocks, select any other severity level using the selector to the right of the pattern.
  • To edit an existing pattern, double-click it or sel3ect it and click Edit on the window toolbar.
    When the pattern is open for editing, you can specify descriptions for its search and replace parts. The search description will be used to show the pattern in the catalog and as a description of the matched blocks highlighted in the editor. The replace description is shown as a name of the quick-fix, that is suggest for the highlighted block. For more information, see Creating Custom Code Inspections and Quick-Fixes.
Pattern catalog in ReSharper options

Finding and replacing code with the pattern

There are three approaches to searching and replacing code with patterns:

If you run the search one of the first two ways, all matching code blocks in your solution are listed in the Find Results window. If the results do not include what you are looking for, you can quickly modify the pattern and invoke the search process once again. To do so, click Change Search Pattern Reference__Windows__Pattern_Catalogue__Edit_Pattern on the window toolbar.

If you run the replace one of the first two ways, all replace candidates in your solution are shown in the Replace with Pattern dialog. In this dialog, you can study and group the candidates, If you want to see the candidates in the context, click Show Preview toolbar_show_preview on the toolbar. You can also double-click on any of the candidate to open the containing file in the editor.
If the displayed candidates are what you want to replace, click Replace on the bottom of the dialog.

Sharing patterns

Your search and replace patterns can be saved in a shared settings layer and become available to all your team.

If you create a pattern in the Custom Patterns options page, click Save To and then select a shared settings layer when the pattern is ready.

To share an existing pattern that is not shared yet, open it for editing and click Save Copy in the Edit Highlighting Pattern dialog. Then click Save To and then select a shared settings layer.

This feature is supported in the following languages/technologies:

C# VB.NET C++ HTML ASPX Razor JavaScript TypeScript CSS XML XAML RESX Build Scripts
feature_availablefeature_availablefeature_availablefeature_availablefeature_availablefeature_available

The instructions and examples given here address the use of the feature in C#. For details specific to other languages, see corresponding topics in the ReSharper by Language section.

See Also

Last modified: 30 June 2015