Add new topic for API Analyzer #3908
Conversation
|
|
|
|
||
| # .NET API Analyzer | ||
|
|
||
| The .NET API Analyzer is a Roslyn analyzer that discovers potential compatibility risks for APIs with different platforms and detecting calls to deprecated APIs. It can be useful for any developers of the .NET family at any stages of development. |
There was a problem hiding this comment.
detecting --> detects
any stages --> any stage
|
|
||
| The .NET API Analyzer is a Roslyn analyzer that discovers potential compatibility risks for APIs with different platforms and detecting calls to deprecated APIs. It can be useful for any developers of the .NET family at any stages of development. | ||
|
|
||
| API Analyzer comes as [NuGet package](https://www.nuget.org/packages/Microsoft.DotNet.Analyzers.Compatibility/) and after referencing it in a project, it automatically starts monitoring the code and squiggles problematic API usage. You can get suggestions on possible fixes by clicking on the light bulb, which also includes the ability to suppress the warnings. |
There was a problem hiding this comment.
comma between "after" and "an"
after referencing it --> after you reference it
I'm not enamored of squiggles as a verb. I would change it to "It automatically monitors the code and indicates problematic API usage."
For the last sentence, "You can also get suggestions on possible fixes by clicking on the light bulb, and you can suppress the warnings."
| API Analyzer comes as [NuGet package](https://www.nuget.org/packages/Microsoft.DotNet.Analyzers.Compatibility/) and after referencing it in a project, it automatically starts monitoring the code and squiggles problematic API usage. You can get suggestions on possible fixes by clicking on the light bulb, which also includes the ability to suppress the warnings. | ||
|
|
||
| ## Discovering deprecated APIs | ||
| When a deprecated API (for example `WebClient`) is used in a code, API Analyzer squiggles it out in green and shows a light bulb on the left |
There was a problem hiding this comment.
`WebClient` can be replaced with a link (<xref:System.Net.WebClient>)
again, squiggles as a verb; its usual meaning as a verb is to squirm or to wriggle. Perhaps "highlights it with a green squiggly line..."?
|
|
||
| The Error List window contains warnings with a unique ID per deprecated API (in our example `DE004`). By clicking on it, you go to a webpage with detailed information about why the API was deprecated and how alternative APIs should be used. | ||
|
|
||
|  |
There was a problem hiding this comment.
By clicking on it --> By clicking on the ID,
how alternative APIs should be used, or what alternative APIs should be used?
| // More code | ||
| } | ||
| ``` | ||
| You can also conditionally compile per target framework/operating system, but you currently need to do that manually. |
There was a problem hiding this comment.
Can you add a bit more detail about what you mean by doing that manually?
There was a problem hiding this comment.
I agree with @rpetrusha that more details here would be good.
|
|
||
| ## Supported diagnostics | ||
| Right now the analyzer handles the following cases: | ||
| * Usage of a .NET Standard API that throws `PlatformNoSupportedException` (PC001) |
There was a problem hiding this comment.
this could be a link: <xref:System.PlatformNotSupportedException>
|
|
||
| ## Supported diagnostics | ||
| Right now the analyzer handles the following cases: | ||
| * Usage of a .NET Standard API that throws `PlatformNoSupportedException` (PC001) |
There was a problem hiding this comment.
Each of these list items should end with a period.
| All these diagnostics are available not only in the IDE, but also on the command line as part of building your project, which includes the CI server. | ||
|
|
||
| ## Configuration | ||
| It is up to a user to decide how the diagnostics should be treated: as warnings, errors, suggestions, or to be turned off. For example as an architect you can decide that compatibility issues are errors, some deprecation are warnings and some are only suggestions. You can configure this separately by diagnostic ID and by project. To do so in your project tree -> Dependencies -> Analyzers -> Microsoft.DotNet.Analyzers.Compatibility, right click on the diagnostic ID and Set Rule Set Severity and pick a desired option. |
There was a problem hiding this comment.
comma after example and architect
some deprecation are warnings and some are only suggestions --> calls to some deprecated APIs generate warnings, while others only generate suggestions (comma after warnings)
|
@OliaG please let us know if you need any help with the changes. Thanks! |
|
|
||
| The .NET API Analyzer is a Roslyn analyzer that discovers potential compatibility risks for APIs with different platforms and detects calls to deprecated APIs. It can be useful for any developers of the .NET family at any stage of development. | ||
|
|
||
| API Analyzer comes as [NuGet package](https://www.nuget.org/packages/Microsoft.DotNet.Analyzers.Compatibility/) and after you reference it in a project, it automatically monitors the code and indicates problematic API usage. You can also get suggestions on possible fixes by clicking on the light bulb.The drop-down menu includes an option to suppress the warnings. |
There was a problem hiding this comment.
comes as -> comes as a
missing space after light bulb.
| API Analyzer comes as [NuGet package](https://www.nuget.org/packages/Microsoft.DotNet.Analyzers.Compatibility/) and after you reference it in a project, it automatically monitors the code and indicates problematic API usage. You can also get suggestions on possible fixes by clicking on the light bulb.The drop-down menu includes an option to suppress the warnings. | ||
|
|
||
| ## Discovering deprecated APIs | ||
| When a deprecated API (for example `WebClient`)is used in a code, API Analyzer highlights it with a green squiggly line and shows a light bulb on the left |
There was a problem hiding this comment.
API (for example WebClient)is, -> API, such as WebClient, is
shows a light bulb on the left -> shows a light bulb on the left as in the following example: (or something to that extent)
| ## Discovering deprecated APIs | ||
| When a deprecated API (for example `WebClient`)is used in a code, API Analyzer highlights it with a green squiggly line and shows a light bulb on the left | ||
|
|
||
|  ! |
There was a problem hiding this comment.
images need alt text per accessibility guidelines (some guidelines https://worldready.cloudapp.net/StyleGuide/Read?id=2818&topicid=37020)
|
|
||
|  ! | ||
|
|
||
| The Error List window contains warnings with a unique ID per deprecated API (in our example `DE004`). By clicking on the ID, you go to a webpage with detailed information about why the API was deprecated and what alternative APIs should be used. |
There was a problem hiding this comment.
don't use we or our unless it's Microsoft recommending something. So change "our example" to something like "in the following example"
| All these diagnostics are available not only in the IDE, but also on the command line as part of building your project, which includes the CI server. | ||
|
|
||
| ## Configuration | ||
| It is up to a user to decide how the diagnostics should be treated: as warnings, errors, suggestions, or to be turned off. For example, as an architect, you can decide that compatibility issues should be treated as errors, calls to some deprecated APIs generate warnings, while others only generate suggestions. You can configure this separately by diagnostic ID and by project. To do so in your project tree -> Dependencies -> Analyzers -> Microsoft.DotNet.Analyzers.Compatibility, right click on the diagnostic ID and Set Rule Set Severity and pick a desired option. |
There was a problem hiding this comment.
"It is up to a user to decide how" seems very informal. I'd change to something like "The user decides how..." or even "You decide how"
UI options need to be bold.
I'd also make the steps more clear on where to configure. For example:
"In Solution Explorer, navigate to the Dependencies node under your project. Expand the nodes Dependencies > Analyzers > Microsoft.DotNet.Analyzers.Compatibility. Right click ...
Perhaps a screenshot could help here like the following (but with the right analyzer 😄)
|
Great. Thanks! 😊
edit by @mairaw: removed email template
|
|
|
||
| The .NET API Analyzer is a Roslyn analyzer that discovers potential compatibility risks for APIs with different platforms and detects calls to deprecated APIs. It can be useful for any developers of the .NET family at any stage of development. | ||
|
|
||
| API Analyzer comes as [NuGet package](https://www.nuget.org/packages/Microsoft.DotNet.Analyzers.Compatibility/) and after you reference it in a project, it automatically monitors the code and indicates problematic API usage. You can also get suggestions on possible fixes by clicking on the light bulb.The drop-down menu includes an option to suppress the warnings. |
There was a problem hiding this comment.
Does it make sense to spell out the package name here? That way, I can install the package without clicking on the NuGet link, which is not really necessary otherwise.
| ## Discovering deprecated APIs | ||
| When a deprecated API (for example `WebClient`)is used in a code, API Analyzer highlights it with a green squiggly line and shows a light bulb on the left | ||
|
|
||
|  ! |
There was a problem hiding this comment.
I think the exclamation point at the end of the line shouldn't be there.
| Any warnings can be suppressed by right-clicking on the highlighted member and selecting **Quick Actions and Refactorings**. Here you get two suppression options: locally (in source) or globally (in a suppression file). We encourage developers to use global suppression to ensure consistency of API usage across their project. | ||
|
|
||
| ## Discovering cross-platform issues | ||
| Similar to deprecated APIs the analyzer squiggles out all APIs that are not cross-platform supported (For example `Console.WindowWidth` works on Windows but not on Linux and macOS). The diagnostic ID is shown in Error List window. You can suppress warning by right click and choosing "Quick Actions and Refactorings". Unlike deprecation cases where you have two options: either keep using deprecated member and suppress warnings or not use it at all, here if you are developing your code only for certain platform you can suppress all warnings for all other platforms you don't plan to run your code on. To do so, you just need to edit your project file and add a property `PlatformCompatIgnore` that lists all platforms to be ignored: |
There was a problem hiding this comment.
"For example" does not start a sentence of its own, so it shouldn't be capitalized.
| API Analyzer comes as [NuGet package](https://www.nuget.org/packages/Microsoft.DotNet.Analyzers.Compatibility/) and after you reference it in a project, it automatically monitors the code and indicates problematic API usage. You can also get suggestions on possible fixes by clicking on the light bulb.The drop-down menu includes an option to suppress the warnings. | ||
|
|
||
| ## Discovering deprecated APIs | ||
| When a deprecated API (for example `WebClient`)is used in a code, API Analyzer highlights it with a green squiggly line and shows a light bulb on the left |
There was a problem hiding this comment.
Should a short explanation of what "deprecated" means and how it differs from [Obsolete] be added here?
|
Just checked in, all (@mairaw , @rpetrusha, @svick ) comments should be addressed. Let me know if you don't see the changes. |
|
Thanks @OliaG. I can see the changes now. I've resolved a merge conflict and I'll get the review done shortly. |
|
|
||
| ## Discovering deprecated APIs | ||
|
|
||
| ### *What is deprecated API* |
There was a problem hiding this comment.
I don't think you need italic here and in the text. I'd also say "What is a deprecated API?" or "What are deprecated APIs"
| ## Discovering deprecated APIs | ||
|
|
||
| ### *What is deprecated API* | ||
| *The .NET Framework is a large product that is getting constantly upgraded to better serve customer needs. It is natural to deprecate some APIs and replace them with new ones. Previously old APIs were marked with `[Obsolete]` attribute. There was only one diagnostic ID (CS0612) for all obsolete APIs that lead to one description for all cases and ability to suppress warnings for either all cases or none of them. To provide information and a way to suppress a warning per each API or a class of APIs, `Deprecation` term was introduced.* |
There was a problem hiding this comment.
The concept of deprecated APIs apply to all .NET implementations, not only Framework, correct?
Missing comma after previously
missing articles before the attributes: with the Obsolete attribute, the Deprecation term, etc.
Putting thing in inline code like Deprecation will block that term from being translated. Is that what you want in this specific case? Perhaps you just want to say "the deprecation concept was introduced"?
| ### *What is deprecated API* | ||
| *The .NET Framework is a large product that is getting constantly upgraded to better serve customer needs. It is natural to deprecate some APIs and replace them with new ones. Previously old APIs were marked with `[Obsolete]` attribute. There was only one diagnostic ID (CS0612) for all obsolete APIs that lead to one description for all cases and ability to suppress warnings for either all cases or none of them. To provide information and a way to suppress a warning per each API or a class of APIs, `Deprecation` term was introduced.* | ||
|
|
||
| When a deprecated API, such as \<xref:System.Net.WebClient>, is used in a code, API Analyzer highlights it with a green squiggly line and shows a light bulb on the left as in the following example: |
There was a problem hiding this comment.
I think the \ in front of the xref link is making the link broken.
There was a problem hiding this comment.
I don't think that WebClient has been deprecated.
There was a problem hiding this comment.
It is not marked Obsolete but it is considered deprecated. Here is discussion about it in the first question to this blog post: https://blogs.msdn.microsoft.com/dotnet/2017/10/31/introducing-api-analyzer/
In reply to: 160491547 [](ancestors = 160491547)
| Any warnings can be suppressed by right-clicking on the highlighted member and selecting **Quick Actions and Refactorings**. Here you get two suppression options: locally (in source) or globally (in a suppression file). We encourage developers to use global suppression to ensure consistency of API usage across their project. | ||
|
|
||
| ## Discovering cross-platform issues | ||
| Similar to deprecated APIs the analyzer squiggles out all APIs that are not cross-platform supported (for example `Console.WindowWidth` works on Windows but not on Linux and macOS). The diagnostic ID is shown in Error List window. You can suppress warning by right click and choosing "Quick Actions and Refactorings". Unlike deprecation cases where you have two options: either keep using deprecated member and suppress warnings or not use it at all, here if you are developing your code only for certain platform you can suppress all warnings for all other platforms you don't plan to run your code on. To do so, you just need to edit your project file and add a property `PlatformCompatIgnore` that lists all platforms to be ignored: |
There was a problem hiding this comment.
missing comma after "Similar to deprecated APIs" and "for example"
missing article on "You can supress warning.." Should it be You can suppress that warning?
Bold the Quick Actions and Refactorings since it's a UI option instead of quotes
I'd put the info on the two options in parentheses, the : breaks the flow a bit
remove extra space in for all other platforms
a property PlatformCompatIgnore -> a PlatformCompatIgnore property
| Similar to deprecated APIs the analyzer squiggles out all APIs that are not cross-platform supported (for example `Console.WindowWidth` works on Windows but not on Linux and macOS). The diagnostic ID is shown in Error List window. You can suppress warning by right click and choosing "Quick Actions and Refactorings". Unlike deprecation cases where you have two options: either keep using deprecated member and suppress warnings or not use it at all, here if you are developing your code only for certain platform you can suppress all warnings for all other platforms you don't plan to run your code on. To do so, you just need to edit your project file and add a property `PlatformCompatIgnore` that lists all platforms to be ignored: | ||
| ``` | ||
| <PropertyGroup> | ||
| <PlatformCompatIgnore>Linux;MacOSX</PlatformCompatIgnore> |
There was a problem hiding this comment.
any place to see the accepted values for this property? or should we list the accepted values here?
There was a problem hiding this comment.
I'm adding accepted values here. In the next version MacOSX will be changed to macOS. I will need to update the doc.
In reply to: 160018631 [](ancestors = 160018631)
| ``` | ||
| If your code targets multiple platforms and you want to take advantage of an API not supported on some of them, you can guard that part of the code with an `if`-statement: | ||
|
|
||
| ```CSharp |
|
|
||
| ## Discovering cross-platform issues | ||
| Similar to deprecated APIs the analyzer squiggles out all APIs that are not cross-platform supported (for example `Console.WindowWidth` works on Windows but not on Linux and macOS). The diagnostic ID is shown in Error List window. You can suppress warning by right click and choosing "Quick Actions and Refactorings". Unlike deprecation cases where you have two options: either keep using deprecated member and suppress warnings or not use it at all, here if you are developing your code only for certain platform you can suppress all warnings for all other platforms you don't plan to run your code on. To do so, you just need to edit your project file and add a property `PlatformCompatIgnore` that lists all platforms to be ignored: | ||
| ``` |
| You can also conditionally compile per target framework/operating system, but you currently need to do that manually. | ||
|
|
||
| ## Supported diagnostics | ||
| Right now the analyzer handles the following cases: |
| description: Learn how the .NET API Analyzer can help detecting deprecated APIs and platform compatibility issues. | ||
| author: oliag | ||
| ms.author: mairaw | ||
| ms.date: 12/11/2017 |
| @@ -0,0 +1,69 @@ | |||
| --- | |||
| title: .NET API Analyzer | |||
| description: Learn how the .NET API Analyzer can help detecting deprecated APIs and platform compatibility issues. | |||
There was a problem hiding this comment.
nit: detecting --> detect
|
|
||
| # .NET API Analyzer | ||
|
|
||
| The .NET API Analyzer is a Roslyn analyzer that discovers potential compatibility risks for APIs with different platforms and detects calls to deprecated APIs. It can be useful for any developers of the .NET family at any stage of development. |
There was a problem hiding this comment.
with different platforms --> on different platforms
any developers --> all developers
| ### *What is deprecated API* | ||
| *The .NET Framework is a large product that is getting constantly upgraded to better serve customer needs. It is natural to deprecate some APIs and replace them with new ones. Previously old APIs were marked with `[Obsolete]` attribute. There was only one diagnostic ID (CS0612) for all obsolete APIs that lead to one description for all cases and ability to suppress warnings for either all cases or none of them. To provide information and a way to suppress a warning per each API or a class of APIs, `Deprecation` term was introduced.* | ||
|
|
||
| When a deprecated API, such as \<xref:System.Net.WebClient>, is used in a code, API Analyzer highlights it with a green squiggly line and shows a light bulb on the left as in the following example: |
There was a problem hiding this comment.
I don't think that WebClient has been deprecated.
| ## Discovering deprecated APIs | ||
|
|
||
| ### *What is deprecated API* | ||
| *The .NET Framework is a large product that is getting constantly upgraded to better serve customer needs. It is natural to deprecate some APIs and replace them with new ones. Previously old APIs were marked with `[Obsolete]` attribute. There was only one diagnostic ID (CS0612) for all obsolete APIs that lead to one description for all cases and ability to suppress warnings for either all cases or none of them. To provide information and a way to suppress a warning per each API or a class of APIs, `Deprecation` term was introduced.* |
There was a problem hiding this comment.
There are a number of problems with this paragraph:
- CS0612 is a compiler-specific error message. (The VB code is BC40000.) Does API Analyzer only support C# code right now? If so, that's not mentioned. If not, this needs to be made more language-independent. For example: "Because compilers used a single error ID (for C#, CS0612; for Visual Basic, BC40000) for all obsolete APIs, developers had the limited choice of suppressing warnings for all cases or for none."
- "old APIs" is ambiguous; are old APIs deprecated, or have they just been around a long time? It's best to describe them as "deprecated APIs", which maintains consistency with the second sentence.
- "Previously, old APIS were marked..." implies that the Obsolete attribute is no longer used to indicate new deprecated APIs. Is that true?
- The last sentence is confusing. I think that the point you're trying to make is that API Analyzer uses API-specific error codes that begin with DE (for Deprecation Error?), which allows control over the display of individual warnings.
In addition, some other smaller comments: - is getting constantly upgraded --> is constantly upgraded
- comma after Previously
There was a problem hiding this comment.
API Analyzer support only C# code right now but we are looking at ways to extend it to VB as well. Updated the first paragraph to reflect that.
In reply to: 160496715 [](ancestors = 160496715)
|
|
||
| ## Supported diagnostics | ||
| Right now the analyzer handles the following cases: | ||
| * Usage of a .NET Standard API that throws \<xref:System.PlatformNotSupportedException> (PC001). |
|
@mairaw, @rpetrusha thank you for the comments, just pushed the new version. |
There was a problem hiding this comment.
@OliaG I did an edit pass but while reviewing the tool and how it works, I had some last comments that would be good to address. Thanks! /cc @terrajobst @pjanotti
|
|
||
| **What are deprecated APIs?** | ||
|
|
||
| The .NET family is a set of large products that are constantly upgraded to better serve customer needs. It is natural to deprecate some APIs and replace them with new ones. One way to inform that an API is deprecated and should not be used is to mark it with the `[Obsolete]` attribute. The disadvantage of this approach is that there is only one diagnostic ID for all obsolete APIs (for C#, [CS0612](../../csharp/misc/cs0612.md)) that leads to one description for all cases and ability to suppress warnings for either all cases or none of them. The API Analyzer uses API-specific error codes that begin with DE (which stands for Deprecation Error), which allows control over the display of individual warnings. To avoid confusion with the `[Obsolete]` attribute, this concept is called deprecation. |
There was a problem hiding this comment.
The last sentence seems incorrect. My suggestion would be to replace with the following:
The deprecated APIs identified by the analyzer are defined in the [dotnet/platform-compat](https://github.com/dotnet/platform-compat) repo. but I wanted to make sure that was correct.
|
|
||
| Any warnings can be suppressed by right-clicking on the highlighted member and selecting **Quick Actions and Refactorings**. There are two ways to supress warnings: | ||
|
|
||
| * locally (in source) |
There was a problem hiding this comment.
I think we need to show examples of how to do both, where in the source, where I can find this global supression file, etc.
|
|
||
| > [!NOTE] | ||
| > The .NET API analyzer is still a pre-release version. | ||
|
|
There was a problem hiding this comment.
I think we need to add a prerequisites section. Which version of VS we need and what kind of project. I tested this in 2 projects: a new .NET Core project and an existing .NET Framework 4.7. It only worked on the new .NET Core.
| // More code | ||
| } | ||
| ``` | ||
| You can also conditionally compile per target framework/operating system, but you currently need to do that manually. |
There was a problem hiding this comment.
I agree with @rpetrusha that more details here would be good.
|
|
||
| The .NET API Analyzer is a Roslyn analyzer that discovers potential compatibility risks for C# APIs on different platforms and detects calls to deprecated APIs. It can be useful for all C# developers at any stage of development. | ||
|
|
||
| API Analyzer comes as a NuGet package [Microsoft.DotNet.Analyzers.Compatibility](https://www.nuget.org/packages/Microsoft.DotNet.Analyzers.Compatibility/) and after you reference it in a project, it automatically monitors the code and indicates problematic API usage. You can also get suggestions on possible fixes by clicking on the light bulb. The drop-down menu includes an option to suppress the warnings. |
There was a problem hiding this comment.
either add a comma after the NuGet package link, or make this two sentences.
|
|
||
| **What are deprecated APIs?** | ||
|
|
||
| The .NET family is a set of large products that are constantly upgraded to better serve customer needs. It is natural to deprecate some APIs and replace them with new ones. One way to inform that an API is deprecated and should not be used is to mark it with the `[Obsolete]` attribute. The disadvantage of this approach is that there is only one diagnostic ID for all obsolete APIs (for C#, [CS0612](../../csharp/misc/cs0612.md)) that leads to one description for all cases and ability to suppress warnings for either all cases or none of them. The API Analyzer uses API-specific error codes that begin with DE (which stands for Deprecation Error), which allows control over the display of individual warnings. To avoid confusion with the `[Obsolete]` attribute, this concept is called deprecation. |
There was a problem hiding this comment.
For those who don't know what the Obsolete attribute is, a link might be better here: [Obsolete](xref:System.ObsoleteAttribute)
ability --> the ability
for a later revision (no need to do it here), you might note that deprecated APIs are not necessarily marked with Obsolete.
|
|
||
| ## Discovering cross-platform issues | ||
|
|
||
| Similar to deprecated APIs, the analyzer identifies all APIs that are not cross-platform supported. For example, <xref:System.Console.WindowWidth?displayProperty=nameWithType> works on Windows but not on Linux and macOS. The diagnostic ID is shown in **Error List** window. You can suppress that warning by right clicking and choosing **Quick Actions and Refactorings**. Unlike deprecation cases where you have two options (either keep using deprecated member and suppress warnings or not use it at all), here if you're developing your code only for certain platform you can suppress all warnings for all other platforms you don't plan to run your code on. To do so, you just need to edit your project file and add the `PlatformCompatIgnore` property that lists all platforms to be ignored. The accepted values are: `Linux`, `MacOSX`, and `Windows`. |
There was a problem hiding this comment.
cross-platform supported --> supported cross-platform
in **Error List** --> in the **Error List**
using deprecated --> using the deprecated
for certain platform --> for certain platforms, (not comma after platforms)
|
|
||
| * locally (in source) | ||
| * globally (in a suppression file) | ||
|
|
||
| ### Suppresing warnings localy |
There was a problem hiding this comment.
typo: suppresing -> suppressing
localy -> locally #Resolved
| To suppress warnings localy you need to right-click on the member you want to suppress warnings for and select **Suppress *diagnostic ID***, then click **in Source**. Your code will be framed with `#pragma` like it is shown below: | ||
|  | ||
|
|
||
| ### Suppresing warnings globally |
There was a problem hiding this comment.
typo: suppresing -> Suppressing #Resolved
|
|
||
| ### Suppresing warnings globally | ||
|
|
||
| To suppress warnings globally you need to right-click on the member you want to suppress warnings for and select **Suppress *diagnostic ID***, then click **in Suppression File**. |
There was a problem hiding this comment.
look at the comments for the previous section
#Resolved
|
|
||
|  | ||
|
|
||
| A file **GlobalSuppressions.cs** will be created in your project. |
There was a problem hiding this comment.
A file GlobalSuppressions.cs will be created in your project. ->
A GlobalSuppressions.cs file is added to your project after the first suppresion. (we use italics for file names) #Resolved
|
|
||
| * locally (in source) | ||
| * globally (in a suppression file) | ||
|
|
||
| ### Suppresing warnings localy | ||
|
|
||
| To suppress warnings localy you need to right-click on the member you want to suppress warnings for and select **Suppress *diagnostic ID***, then click **in Source**. Your code will be framed with `#pragma` like it is shown below: |
There was a problem hiding this comment.
nit: missing comma after To suppress warnings localy
you need to right-click -> right-click
typo: localy -> locally
it seems you do need to click Quick Actions and Refactorings first, no?
You could put the diagnostic ID in brackets like Suppress <diagnostic ID>
After selecting in Source, they also get options on the scope of the change. By default, it's only on that specific call.
you should not use below. Replace with following.
add link to #pragma warning docs? https://docs.microsoft.com/dotnet/csharp/language-reference/preprocessor-directives/preprocessor-pragma-warning? (../../csharp/language-reference/preprocessor-directives/preprocessor-pragma-warning.md)
Try to avoid future tense. You could say something like: "The #pragma warning preprocessor directive is added to your source code in the scope defined."
| @@ -34,16 +46,31 @@ The **Error List** window contains warnings with a unique ID per deprecated API, | |||
|
|
|||
| By clicking on the ID, you go to a webpage with detailed information about why the API was deprecated and suggestions regarding alternative APIs that can be used. | |||
|
|
|||
| Any warnings can be suppressed by right-clicking on the highlighted member and selecting **Quick Actions and Refactorings**. There are two ways to supress warnings: | |||
| Any warnings can be suppressed by right-clicking on the highlighted member and selecting **Suppress *diagnostic ID***. There are two ways to supress warnings: | |||
There was a problem hiding this comment.
it seems you do need to click Quick Actions and Refactorings first, no?
| We encourage developers to use global suppression to ensure consistency of API usage across their projects. | ||
|
|
||
| ## Discovering cross-platform issues | ||
|
|
||
| Similar to deprecated APIs, the analyzer identifies all APIs that are not cross-platform supported. For example, <xref:System.Console.WindowWidth?displayProperty=nameWithType> works on Windows but not on Linux and macOS. The diagnostic ID is shown in **Error List** window. You can suppress that warning by right clicking and choosing **Quick Actions and Refactorings**. Unlike deprecation cases where you have two options (either keep using deprecated member and suppress warnings or not use it at all), here if you're developing your code only for certain platform you can suppress all warnings for all other platforms you don't plan to run your code on. To do so, you just need to edit your project file and add the `PlatformCompatIgnore` property that lists all platforms to be ignored. The accepted values are: `Linux`, `MacOSX`, and `Windows`. | ||
| Similar to deprecated APIs, the analyzer identifies all APIs that are not supported cross-platform. For example, <xref:System.Console.WindowWidth?displayProperty=nameWithType> works on Windows but not on Linux and macOS. The diagnostic ID is shown in the **Error List** window. You can suppress that warning by right clicking and choosing **Quick Actions and Refactorings**. Unlike deprecation cases where you have two options (either keep using the deprecated member and suppress warnings or not use it at all), here if you're developing your code only for certain platforms, you can suppress all warnings for all other platforms you don't plan to run your code on. To do so, you just need to edit your project file and add the `PlatformCompatIgnore` property that lists all platforms to be ignored. The accepted values are: `Linux`, `MacOSX`, and `Windows`. |
There was a problem hiding this comment.
On this comment, @pjanotti indicated the right value would be macOS and not MacOSX #Resolved
| @@ -60,7 +87,9 @@ if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows)) | |||
| // More code | |||
| } | |||
| ``` | |||
| You can also conditionally compile per target framework/operating system, but you currently need to do that manually. | |||
| You can also conditionally compile per target framework/operating system, but you currently need to do that [manually]( | |||
| https://docs.microsoft.com/en-us/dotnet/standard/frameworks#how-to-specify-target-frameworks). | |||
There was a problem hiding this comment.
relative path for the url: ../frameworks.md#how-to-specify-target-frameworks
| The .NET family is a set of large products that are constantly upgraded to better serve customer needs. It is natural to deprecate some APIs and replace them with new ones. One way to inform that an API is deprecated and should not be used is to mark it with the `[Obsolete]` attribute. The disadvantage of this approach is that there is only one diagnostic ID for all obsolete APIs (for C#, [CS0612](../../csharp/misc/cs0612.md)) that leads to one description for all cases and ability to suppress warnings for either all cases or none of them. The API Analyzer uses API-specific error codes that begin with DE (which stands for Deprecation Error), which allows control over the display of individual warnings. To avoid confusion with the `[Obsolete]` attribute, this concept is called deprecation. | ||
| The API Analyzer uses API-specific error codes that begin with DE (which stands for Deprecation Error), which allows control over the display of individual warnings. The deprecated APIs identified by the analyzer are defined in the [dotnet/platform-compat](https://github.com/dotnet/platform-compat) repo. | ||
|
|
||
| ### Working with API Analyzer |
|
|
||
| > [!NOTE] | ||
| > The .NET API analyzer is still a pre-release version. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| * Visual Studio 2017 or Roslyn 2.0 |
There was a problem hiding this comment.
we talked about this section offline. Not clear what Roslyn 2.0 means here. Does it work VS for Mac? Does it work with any kind of project?
There was a problem hiding this comment.
Made my final edits @OliaG. For me this is ready to go once builds completes. @rpetrusha can you please take a look too? Thanks!
|
|
||
| ### Using the API Analyzer | ||
|
|
||
| When a deprecated API, such as <xref:System.Net.WebClient>, is used in a code, API Analyzer highlights it with a green squiggly line. When you hover over the API call, a light bulb is displayed with information about the API deprecation as in the following example: |
There was a problem hiding this comment.
comma before "as in the following example"
|
|
||
|  | ||
|
|
||
| Global suppression is the recommended way to ensure consistency of API usage across their projects. |
There was a problem hiding this comment.
instead of "their projects", either "projects" or "your projects".
|
I've made the changes @rpetrusha. I'll merge once build completes. 🎆 |
Fixes #3807