Obeying MSDN documentation

[John Browning]

Hi there,

I've frequently noticed quite a few .NET functions with the following MSDN
caveat:

"This method supports the .NET Framework infrastructure and is not intended
to be used directly from your code."

Does anyone know whether this officially means you can't use the function or
it's potentially dangerous if you do (and/or it's subject to possible change
by MSFT). If a function says it's for MSFT internal use only that's one
thing (I've seen these though I don't think MSFT should be publishing them
if they're off-limits). But, as an example, "Form.CenterToParent()" has the
above disclaimer but it still works and it's useful for re-centering a
window after manually alterting its size in some handler (e.g., "OnLoad()"
for instance). Is it therefore safe to use this function (and others) when
the circumstances warrant it or do you have to roll your own. Thanks in
advance.

 

[Jon Skeet [C# MVP]]

I've frequently noticed quite a few .NET functions with the following MSDN
caveat:

"This method supports the .NET Framework infrastructure and is not intended
to be used directly from your code."

Does anyone know whether this officially means you can't use the function or
it's potentially dangerous if you do (and/or it's subject to possible change
by MSFT). If a function says it's for MSFT internal use only that's one
thing (I've seen these though I don't think MSFT should be publishing them
if they're off-limits). But, as an example, "Form.CenterToParent()" has the
above disclaimer but it still works and it's useful for re-centering a
window after manually alterting its size in some handler (e.g., "OnLoad()"
for instance). Is it therefore safe to use this function (and others) when
the circumstances warrant it or do you have to roll your own. Thanks in
advance.

There are a few instances of this where it's clearly sensible to call
the method directly - I seem to remember that some classes have Dispose
documented in this way. I'd be cautious, but not worry *too* much.

 

[=?ISO-8859-1?Q?G=F6ran_Andersson?=]

Hi there,

I've frequently noticed quite a few .NET functions with the following MSDN
caveat:

"This method supports the .NET Framework infrastructure and is not intended
to be used directly from your code."

Does anyone know whether this officially means you can't use the function or
it's potentially dangerous if you do (and/or it's subject to possible change
by MSFT). If a function says it's for MSFT internal use only that's one
thing (I've seen these though I don't think MSFT should be publishing them
if they're off-limits). But, as an example, "Form.CenterToParent()" has the
above disclaimer but it still works and it's useful for re-centering a
window after manually alterting its size in some handler (e.g., "OnLoad()"
for instance). Is it therefore safe to use this function (and others) when
the circumstances warrant it or do you have to roll your own. Thanks in
advance.

Try to avoid using those methods if you can. If they change in the
future, the will probably not show up in the list of breaking changes.

Also, there may be limitations on how the methods can be used that isn't
mentioned in the public documentation, as the entry for the method is
mostly to explain why the method is there at all.

You can look up the method using .NET Reflector, and if it's easy to
implement you can just make your own method, and you are safe.

 

[John Browning]

There are a few instances of this where it's clearly sensible to call

the method directly - I seem to remember that some classes have Dispose
documented in this way. I'd be cautious, but not worry *too* much.

Thanks for the feedback. I'm probably secure using them as you said but MSFT
should really spell things out more clearly (if it's documented then
presumably it can be used under the right circumstances regardless of the
disclaimer - hopefully). Thanks again.

 

[John Browning]

Try to avoid using those methods if you can. If they change in the future,

the will probably not show up in the list of breaking changes.

In theory they shouldn't break functions however, only render them
"obsolete" (IMO anyway). I think the documentation hasn't matured enough yet
in any case (too sparse in general and there are even functions that have no
descriptive info at all)

Also, there may be limitations on how the methods can be used that isn't
mentioned in the public documentation, as the entry for the method is
mostly to explain why the method is there at all.

Agreed on the potential (hidden) limitations but I don't see why they
publish these functions if they're actually off-limits (or dangerous in the
absence of what these limitations are)

You can look up the method using .NET Reflector, and if it's easy to
implement you can just make your own method, and you are safe.

Agreed and it's probably safer but I didn't want to reinvent the wheel
either. Anyway, thanks for the info (appreciated).

 

[Mark Rae]

There are a few instances of this where it's clearly sensible to call
the method directly - I seem to remember that some classes have Dispose
documented in this way. I'd be cautious, but not worry *too* much.

IIRC, there used to be a method in v1.x of the Framework which was used to
pop the Directory Browser dialog which was marked as being for Microsoft's
exclusive internal use or somesuch...