Microsoft's Half Cooked APIs

So when you publish APIs, what should you usually do? Say -

public string IWillReturnCaps(string anycase)
{
}

This is kind of self explanatory, and it tells me that If you give string in any case it will return Capital Letter String.

Microsoft has done a great job on publishing APIs on ActiveDirectory, called System.DirectoryService. These APIs look great on Surface! the time you dive in, you are almost dead, because when you prepared for diving in. You thought its 10 Ft Deep Water. But as soon as you get into water, you hit the face with rock solid surface and there is nothing to penetrate further. Some of the APIs are like this :

public willreturnobject IWillDoSomething(object givemesomething, object somethingmore, object andsoemthingmore)
{
}


This is called half cooked apis, you have the API, you need to figure it out what its going to do! The more concrete example can be - if you ask for properties - then documentation says, returns strings or values of properties? How many properties? Where are the properties, go figure out! Or do a enum or properties collection, use ADSI. Agreed! but why are properties not listed there. More over - if you are trying to do something, then you need to have basic concepts clear, should be able to write code in C++ or Visual Basic. There are not many examples which provide you with C# Code samples.

IRONY is that you are trying to do something with .NET but you need to use ActiveDS and COM Interop. Any way! if you go in that way - long time back you could not write a plugin for Visual Studio .NET in .NET Itself. If your plugin involves little bit of of GUI, you must use ActiveX.

If you are trying to do something with System.DirectoryServices then go here.

Btw- I am trying to write a Active Directory Web Administration Interface in ASP.NET - which will be available here soon.