The short answer is that the method is missing because someone in the development team forgot to use an Obsolete attribute. This method in the TelemetryClient class in the Microsoft.ApplicationInsights NuGet package is used very often. After the latest update of the package, it just disappeared. Surprisingly, the method isn’t listed in IntelliSense, but the older code where this method is used can be successfully compiled without any error or warning.
The case
The chronological order of events that forced me to write this article was as follows:
May 23, Microsoft.ApplicationInsights, 2.6.4
The TelemetryClient.TrackMetric method does not contain any summary or attribute that would affect the IDE.
August 7, Microsoft.ApplicationInsights, 2.7.1
The TelemetryClient.TrackMetric method gets the summary Documentation Comment. There is nothing inherently wrong with this, but the information it contains does not have the right semantics. The summary tag is used to describe a type or a type member. It isn’t intended to mark the stage of its lifecycle.
/// <summary>
/// This method is deprecated...
/// </summary>August 11, Microsoft.ApplicationInsights, 2.7.2
Four days later, the TelemetryClient.TrackMetric method is hidden from IntelliSense. There is nothing inherently wrong with this, but this step makes it impossible to see the content of the summary tag above.
[EditorBrowsable(EditorBrowsableState.Never)]My recommendation
- Tell users of your library about method deprecation by attributing it with the
Obsoleteattribute and giving them several months to adapt their code to your changes. - Use the summary tag for describing functionality, not for announcing lifecycle progress.
- Use TFVC’s Code Review. If you must use Git, adopt a code review process.
- In general, hiding a method from IntelliSense isn’t a good idea because the overhead for backward compatibility is hidden. It makes sense in rare cases only, for example, when making a new framework compatible with legacy code written for the framework’s predecessor.