TheSwamp

Code Red => .NET => Topic started by: Kerry on November 24, 2015, 03:06:08 AM

Title: .NET Documentation questions.
Post by: Kerry on November 24, 2015, 03:06:08 AM
We have been given an opportunity to resolve some issues and/or shortcomings with the .NET documentation for AutoCAD (and verticals).

In the 10 (or so) years that .NET has been used in AutoCAD there have been quite a few changes, in both the .net and AutoCAD assemblies. If we do a web search for information chances are some will be out of date , some misleading, some guesses and some just plain incorrect.

Wouldn't it be 'nice' if the documentation for the AutoCAD API could be used as a complete and single resource for developers/customizers/hobbyists without the need to comb through forums and blogs to get the information we need to successfully add value to AutoCAD with economical solutions to service our client's particular requirements. 

Personally I'd enjoy telling someone to "Read the Flipping Manual" and be confident they would resolve their issues.

What information do you want included in the documentation that is not currently there ?

The ground rules are simple.
Be explicit.
No bitching.
Be realistic.

If you come across documentation that is terse , technically challenging , or incomprehensible please include it as well.

Beginners are encouraged to participate.

I imagine this process will be ongoing so please keep the forum relatively clean and on topic.

Regards,
Be kind to each other.
Title: Re: .NET Documentation questions.
Post by: Kerry on November 24, 2015, 03:21:20 AM
In case you're wondering, I mean these docs too.
http://help.autodesk.com/view/ACD/2016/ENU/?guid=GUID-C3F3C736-40CF-44A0-9210-55F6A939B6F2

ObjectArx_2016
http://images.autodesk.com/adsk/files/objectarx_2016_documentation_vs2012.zip
Title: Re: .NET Documentation questions.
Post by: Andrey Bushman on November 24, 2015, 03:29:23 AM
For example, I want to see in the official documentation additionally such info (for AutoCAD .NET API):

1. Working with the styles: text styles, table styles, dimension styles, etc (the EACH option of them what I see in their dialog windows). I spent a lot of time to know how to work with some of these options in the AutoCAD 2009 in the past (some of the problems are not exist in the newer AutoCAD versions). :(
2. Detailed info about the check standards (I read this (http://through-the-interface.typepad.com/through_the_interface/2008/08/implementing-a.html)  but this has errors and is not enaugh for me). Also I read some info in the ObjectARX SDK 2010, but it was for C++ instead of .NET and has not the expanded code samples.
3. Unit testing of the managed\unmanaged plagins of AutoCAD. By Autodesk I saw this (https://www.google.ru/url?sa=t&rct=j&q=&esrc=s&source=web&cd=3&ved=0ahUKEwim39ad4qjJAhUrAXMKHduMAzwQFgg0MAI&url=http%3A%2F%2Faucache.autodesk.com%2Fau2012%2FsessionsFiles%2F2654%2F4291%2Fhandout_2654_CP2654_Automated_Testing.docx&usg=AFQjCNFVCACHwZVv6w6G-wR3KDdHfCuu7A&sig2=GEIYXyn8xPiNH1H-O2BQLQ&cad=rja) only.
4. Creating the definitions of the dynamic and parametric blocks (if this is possible).
5. Known API bugs and the workarounds.
6. The code samples of working with DXF through .NET API. Something I see for VB6 in the documentation, but current information is not enough (for me).
7. Examples of the mistakes which are made by developers most often (when they use AutoCAD .NET API). Sometimes it may be interesting not only for beginners.

Some of these themes I know decissions, but I didn't see the necessary info in the documentation when I was searching it in the past.
Title: Re: .NET Documentation questions.
Post by: Kerry on November 24, 2015, 03:43:27 AM
What information do you want included in the documentation that is not currently there ?
Whether correctly I understood you what you are asking about what I (like the user or developer) want to see in the documentation additionally?

Yes Andrey.
Additional content,
Content to be fixed,
To be expanded,
To be clarified.

I'd like to think of the document as something we could give to a programmer and then lock her away for a couple of weeks , knowing they had all the information they would need.

Far fetched and fanciful ? yes ; a reasonable goal ? yes.
Title: Re: .NET Documentation questions.
Post by: Andrey Bushman on November 24, 2015, 03:56:38 AM
Oops... I rewrote my last comment instead of creating the new ones... Read it again, please.
Title: Re: .NET Documentation questions.
Post by: Andrey Bushman on November 24, 2015, 05:13:27 AM
What target of the topic? Is the question by Aytodesk? Will be reading the wishes by Autodesk and the new themes into the official documentation can be appeared in the future as a result?
Title: Re: .NET Documentation questions.
Post by: Kerry on November 24, 2015, 05:18:30 AM
Have a look at the comments here
http://through-the-interface.typepad.com/through_the_interface/2015/11/au-2015-handout-virtual-reality-viewing-of-3d-models-using-autodesks-view-and-data-api.html#comment-2375809400

This is why the ground rules I mentioned in the first post are important.

Be explicit.
No bitching (complaining)
Be realistic.
Title: Re: .NET Documentation questions.
Post by: Andrey Bushman on November 24, 2015, 05:33:03 AM
Be realistic.
At this case I haven't any wishes.
Title: Re: .NET Documentation questions.
Post by: Kerry on November 24, 2015, 05:59:51 AM
Be realistic.
At this case I haven't any wishes.
Not even a little funny.
We may as well all retire and forget about it.
Title: Re: .NET Documentation questions.
Post by: Andrey Bushman on November 24, 2015, 06:06:01 AM
Yes it would be right. I incorrect understood the theme purpose (maybe because my English is bad). On the base of first message of this theme I thought the Autodesk has the plans for editing documentation and therefore they want to get the wishes about it.
Title: Re: .NET Documentation questions.
Post by: Keith Brown on November 24, 2015, 09:40:53 AM
The number one issue for me would be the lack of xml documentation included with the API's.  It just boggles my mind that 10 years after creation this is still not implemented.


There should at a minimum be a short summary, a description of each parameter and what it does, and a description of each exception that could be thrown.
Title: Re: .NET Documentation questions.
Post by: dgorsman on November 24, 2015, 11:21:40 AM
Oh yeah.  XML documentation to provide some contextual assistance would be huge.
Title: Re: .NET Documentation questions.
Post by: MexicanCustard on November 24, 2015, 01:15:35 PM
The number one issue for me would be the lack of xml documentation included with the API's.  It just boggles my mind that 10 years after creation this is still not implemented.


There should at a minimum be a short summary, a description of each parameter and what it does, and a description of each exception that could be thrown.

^^^^ THIS!

Oh, and for the verticals too!


SIde Mission:
Can we do anything about adding the properties palette to .NET without using COM?
Title: Re: .NET Documentation questions.
Post by: dgorsman on November 24, 2015, 02:13:27 PM
I think that would essentially involve creating your own palette.  Creating your own simple properties palette should make for a really good "How to" example.
Title: Re: .NET Documentation questions.
Post by: Kerry on November 24, 2015, 09:25:38 PM
Advice regarding the use of Transactions is contradictory.

Refer the ..\ObjectARX 2016\Samples\dotNet\ files

Typically the Tables are instantiated using the GetObject method of the TransactionManager.
The AddNewlyCreatedDBObject method variously uses the Transaction and the TransactionManager
Code - C#: [Select]
  1.         Database db = Application.DocumentManager.MdiActiveDocument.Database;
  2.         Autodesk.AutoCAD.DatabaseServices.TransactionManager tm = db.TransactionManager;
  3.         using (Transaction myT = tm.StartTransaction())
  4.         {            
  5.                 BlockTable bt = (BlockTable)tm.GetObject(db.BlockTableId,OpenMode.ForRead,false);
  6.                 BlockTableRecord btr = (BlockTableRecord)tm.GetObject(bt[BlockTableRecord.ModelSpace],OpenMode.ForWrite,false);
  7.                 using (Line myline = new Line(start, end))
  8.                 {
  9.                         myline.ColorIndex = 3;
  10.                         btr.AppendEntity(myline);
  11.                         myT.AddNewlyCreatedDBObject(myline, true);
  12.                 }
  13.                 myT.Commit();
  14.         }
  15.  

Advice and examples elsewhere use the methods of the Transaction, which I understand is correct.


Why are they different ?



Title: Re: .NET Documentation questions.
Post by: Kerry on November 24, 2015, 09:44:19 PM
Determining or making Table Records.

Invariably there is no advice to make allowance for Records that have been erased.
Typically the advice is to simply check if the Table Has the record and either return the Id of Add a new Record and return it's Id.

This causes havoc if the Record has been erased in the current session.

One way to resolve this is to check  the IsErased property and take action accordingly
example :
Code - C#: [Select]
  1.     ObjectId layerId;
  2.     Database db = HostApplicationServices.WorkingDatabase;
  3.  
  4.     using(Transaction tr = db.TransactionManager.StartTransaction()) {
  5.         LayerTable lt =  (LayerTable)tr.GetObject(db.LayerTableId, OpenMode.ForWrite);
  6.  
  7.         if(lt.Has(layerName)) {
  8.             layerId = lt[layerName];
  9.             if(layerId.IsErased) {
  10.                 LayerTableRecord ltr =  (LayerTableRecord)tr.GetObject(layerId, OpenMode.ForWrite, true);
  11.                 ltr.Erase(false);
  12.             }
  13.         }
  14.         else // create the layer here.
  15.         { // do mojo here
  16.  

I believe this should be documented prominently because it can be a real trap.
Title: Re: .NET Documentation questions.
Post by: Kerry on November 24, 2015, 09:45:34 PM
The number one issue for me would be the lack of xml documentation included with the API's.  It just boggles my mind that 10 years after creation this is still not implemented.

There should at a minimum be a short summary, a description of each parameter and what it does, and a description of each exception that could be thrown.

Yes, It's time the product grew up.
Title: Re: .NET Documentation questions.
Post by: CADbloke on November 24, 2015, 11:08:28 PM
The number one issue for me would be the lack of xml documentation included with the API's.  It just boggles my mind that 10 years after creation this is still not implemented.

There should at a minimum be a short summary, a description of each parameter and what it does, and a description of each exception that could be thrown.
Yeah, this. All those crazy bools that do...do what!?!?! Having the facts in front of me would save me going to the .NET chm file, then off to the ARX chm file because the .NET one had nothing.

Code samples are also handy. It's all well and good to talk about how to use something but I'm sure I am not the only one who sees an actual example and says "oh, that's what they meant there". They are also handy for showing best practices.
Title: Re: .NET Documentation questions.
Post by: Kerry on November 24, 2015, 11:39:13 PM
I'd like to see Hyperlinks working in the CHM Help files.

Title: Re: .NET Documentation questions.
Post by: Kerry on November 25, 2015, 12:59:51 AM
< .. > On the base of first message of this theme I thought the Autodesk has the plans for editing documentation and therefore they want to get the wishes about it.

Essentially, this is correct.

Why don't you try again :)

I think it is better if we deal with one item per post and give as much information as possible to help these guys make any changes.

Regards,
Title: Re: .NET Documentation questions.
Post by: Andrey Bushman on November 25, 2015, 03:32:02 AM
Why don't you try again :)
Because I am forced to be a realist.
Title: Re: .NET Documentation questions.
Post by: Andrey Bushman on November 25, 2015, 04:46:37 AM
If Autodesk through Kerry implies the editing of spelling and a punctuation, then I don't see the sense in this theme. I very much doubt that Autodesk is capable to enter to documentation essential editings (except the punctuation) on the basis of programmer's desires.

In my opinion when Kerry or any other customer creates such themes he is to designate the border of sandbox more clearly...
Quote from: Kerry
Be explicit.
No bitching.
Be realistic.
Where a wish stops being "realistic"? In my opinion the volume of work for adding XML comment to API is not less than the work for any my wish which was pointed by me. Then on the basis of what criteria the "reality" or "unreality" is defined? Also, I thought my wishes are explicit and are not bitching...

So, I don't understand Kerry and his request. Therefore I haven't any wish.
Title: Re: .NET Documentation questions.
Post by: Kerry on November 25, 2015, 05:58:11 AM

I'm sorry I can't make myself understood better Andrey.

We are not dealing with wishes. The offer made by Kean was very simple.
If we provide examples of where the documentation is lacking he will pass the information on to the documentations team.
... or more precisely :
Quote
Please send me an email listing the documentation gaps you care about most and I'll pass it on to the person managing the docs.

I took this for a real offer. Rather than just submit a personal list I thought I'd throw the discussion open to people who use the documentation on a daily basis.

The conditions you quote are mine, not Kean's.
From past experience I believe you are a sensible man and I don't think you need worry about your comments being unrealistic.

I'm sorry you won't be participating because I know you have had some targeted questions in the past that weren't easily resolved from the documentation.

 Stay well,
Title: Re: .NET Documentation questions.
Post by: dgorsman on November 25, 2015, 10:17:45 AM
Code samples are also handy. It's all well and good to talk about how to use something but I'm sure I am not the only one who sees an actual example and says "oh, that's what they meant there". They are also handy for showing best practices.

I'll have to disagree on that.  Short, concise code samples showing an optional parameter, object, etc. don't necessarily follow best practices such as error handling.  Perhaps a two-pronged approach: short examples local to the object at hand, plus several overall examples, referenced in multiple places, that also demonstrate overall coding techniques?
Title: Re: .NET Documentation questions.
Post by: Kerry on November 25, 2015, 10:28:26 AM
Code samples are also handy. It's all well and good to talk about how to use something but I'm sure I am not the only one who sees an actual example and says "oh, that's what they meant there". They are also handy for showing best practices.

I'll have to disagree on that.  Short, concise code samples showing an optional parameter, object, etc. don't necessarily follow best practices such as error handling.  Perhaps a two-pronged approach: short examples local to the object at hand, plus several overall examples, referenced in multiple places, that also demonstrate overall coding techniques?

I'm a big advocate of samples and I agree with David's comment here.
I think that the samples belong in the same document ( or document collection) as the documentation.
2 reasons :
Makes reference linking more efficient
The samples can be updated and/or corrected and re-released with the documentation.
This way we don't end up with snippets scattered from here to breakfast ; all in various states of 'correctness'

The forums and blogs can then be used to help solve efficiency and edge problems instead of second guessing about the documentation.

 
Title: Re: .NET Documentation questions.
Post by: CADbloke on November 26, 2015, 03:40:04 PM
I totally agree with David & Kerry. A comprehensive, well done example is far more useful than a snippet. It is great to see things in context and a complete example is the best way to show how to do it properly.

Docs for methods, properties etc should point to a line in the example code.
Title: Re: .NET Documentation questions.
Post by: Chumplybum on November 26, 2015, 05:31:28 PM
something along the lines of CodePath (maybe?): https://guides.codepath.com/android (https://guides.codepath.com/android)
Title: Re: .NET Documentation questions.
Post by: Kerry on November 26, 2015, 08:40:10 PM
something along the lines of CodePath (maybe?): https://guides.codepath.com/android (https://guides.codepath.com/android)

That would be excellent Mark.
... but I think and  I'm sure AutoDesk would agree : that would be mixing our expectation and AutoDesks capability.

Title: Re: .NET Documentation questions.
Post by: CADbloke on November 29, 2015, 04:59:26 PM
What would also be wonderful is if the web team at Autodesk could Internet properly, or at least learn what a permalink (https://www.google.com/search?q=permalink) is.

How good would it be if a URL like www.autocad.com/api/2016/dotnet/DatabaseServices/Database (http://www.autocad.com/api/2016/dotnet/DatabaseServices/ObjectId) worked and never changed? Then the docs could live online, be discoverable, up-to-date and also easily accessible by a simple local link-builder that could be written for anything (eg. a Visual Studio plugin).

I tried Googling "Autodesk.AutoCAD.DatabaseServices.ObjectId" - the closest to any sort of canonical documentation I found was http://docs.autodesk.com/CIV3D/2014/ENU/API_Reference_Guide/html/b16967c7-44ea-d59c-bf26-486269d9e717.htm - GUID in a URL. Golf clap.
Title: Re: .NET Documentation questions.
Post by: Jeff H on December 07, 2015, 05:06:57 PM
I'm sure a number nerds at Microsoft have good reason for using this and messed with it a little and seems to work nicely, gives you live docs and pdf to download, etc., but lets development team and users communicate while documentation is being created.

https://github.com/aspnet/Docs/blob/master/CONTRIBUTING.md
https://docs.asp.net/en/latest/
Title: Re: .NET Documentation questions.
Post by: Kerry on December 07, 2015, 10:21:31 PM
For Kean, or the assigned tech :
Has this ever been done.
If so, Where ?

Just to follow up on this... the docs do indeed need to be fixed. You can rely on Editor.Command() completing commands for you rather than cancelling them: so you should only need a while loop if you need finer-grained control over the command tokens.

Kean
Title: Re: .NET Documentation questions.
Post by: Kean on December 08, 2015, 05:12:31 AM
For Kean, or the assigned tech :
Has this ever been done.
If so, Where ?

I just checked and it doesn't appear to have made it into the shipping docs (not surprisingly - this thread came up after the SDK docs had already shipped for 2016). I've reminded the docs team.

I've also just received this notification, in case it's of interest (I see that CAD Standards was mentioned, earlier in the thread):

>>>
CAD Standards Plug-in and Transmittal Object library docs have been released and now have .NET sample code.
 
CAD Standards Plug-in library
http://help.autodesk.com/view/ACD/2016/ENU/?guid=GUID-F126AABA-FE9E-4E26-B51D-88D3E54512B5
 
Transmittal Object library
http://help.autodesk.com/view/ACD/2016/ENU/?guid=GUID-667D1179-3A76-437E-BBB7-12ADF3E614F7
<<<

More is in the works, it seems. You might want to check Lee Ambrosius's AU class, once it gets posted. It previews more of what's coming:

>>>
IT10489 - Harnessing the Power of the AutoCAD COM APIs
https://events.au.autodesk.com/connect/sessionDetail.ww?SESSION_ID=10489
 
The session also covers the use of the Database Connectivity Automation Object and Sheet Set Object libraries which also will have full sample projects.
<<<

Kean
Title: Re: .NET Documentation questions.
Post by: Kerry on December 08, 2015, 05:19:00 AM

Thanks Kean.

Is it worth pointing to this thread with a blog article ?

The more input we get the better. There is a certain amount we take for granted after playing with the API for 10 years ... beginners don't have that 'luxury'.
Title: Re: .NET Documentation questions.
Post by: Jeff H on December 09, 2015, 05:10:47 AM
Advice regarding the use of Transactions is contradictory.

Refer the ..\ObjectARX 2016\Samples\dotNet\ files

Typically the Tables are instantiated using the GetObject method of the TransactionManager.
The AddNewlyCreatedDBObject method variously uses the Transaction and the TransactionManager
Advice and examples elsewhere use the methods of the Transaction, which I understand is correct.

Why are they different ?
No matter which one used they end up calling the same methods but for many calls it might matter which one used for AddNewlyCreatedDBObject.
Maybe better stated as how it is accessed as shown below.

For ObjectARX the GetObject and AddNewlyCreatedDBObject methods are duplicated in TransactionManager and uses last transaction added(TopTransaction) to call Getobject() and AddNewlyCreatedDBObject.
Since GetObject and AddNewlyCreatedDBObject can only be used by the last transaction added the TransactionManager will always use the correct Transaction to call both methods , and do not have to keep up with a instance to pass between methods.

The way it is implemented in .NET is Transaction and TransactionManager GetObject call a static method defined in TransactionManager which calls GetObject of the last Transaction

Transaction GetObject
Code - C#: [Select]
  1.         public virtual unsafe DBObject GetObject(.....)
  2.         {
  3.             this.CheckTopTransaction();
  4.             return Autodesk.AutoCAD.DatabaseServices.TransactionManager.GetObjectInternal(.....);
  5.         }
  6.  

So Transaction.GetObject calls TransactionManager.GetObjectInternal to call back to its unmanged Getobject (), so it does not matter which one and will
end up calling the same methods.

The same goes for AddNewlyCreatedDBObject but how you access it could make a difference when used many times in loop.

Transaction's AddNewlyCreatedDBObject
Code - C#: [Select]
  1.         public virtual void AddNewlyCreatedDBObject(DBObject obj, [MarshalAs(UnmanagedType.U1)] bool add)
  2.         {
  3.             this.TransactionManager.AddNewlyCreatedDBObject(obj, add);
  4.         }
  5.  

AddNewlyCreatedDBObject does not use a static method and uses a instance of TransactionManger.
The Transaction's property named TransactionManager of type TransactionManager is used to call TransactionManager.AddNewlyCreatedDBObject.

But Look at Transaction's property for TransactionManager
Code - C#: [Select]
  1.         public virtual Autodesk.AutoCAD.DatabaseServices.TransactionManager TransactionManager
  2.         {
  3.             get
  4.             {
  5.                 IntPtr unmanagedPointer = new IntPtr(AcDbImpTransaction.transactionManager((AcDbImpTransaction* modopt(IsConst) modopt(IsConst)) this.GetImpObj()));
  6.                 return (Autodesk.AutoCAD.DatabaseServices.TransactionManager) RXObject.Create(unmanagedPointer, false);
  7.             }
  8.         }
  9.  

Notice how the property getter creates a new manged wrapper each time it is called(return ...RXObject.Create(unmanagedPointer, false))

So for adding many objects it might be best to create a variable to use same TransactionManager.
Title: Re: .NET Documentation questions.
Post by: Jeff H on December 09, 2015, 05:20:06 AM
Determining or making Table Records.
Invariably there is no advice to make allowance for Records that have been erased.
Typically the advice is to simply check if the Table Has the record and either return the Id of Add a new Record and return it's Id.
Fundamental information about the API would help I think.

If they explained why they choose the SymbolTable data structure back in the 80's or whenever and how it is implemented(hashtable, linklist, etc...) would provide value.
Maybe then would understand why it does not expose a delete or remove method, etc...
Then things like this would not be a surprise but make sense and expect it instead of having to assume and react.
Title: Re: .NET Documentation questions.
Post by: kdub_nz on January 30, 2016, 08:57:47 PM
Can we please have a  definitive description of the full technical meaning of the noDocument parameter for the Database constructor.

purpose,
ramifications
side effects
traps

added:
Are there any special considerations regarding Transactions or DocumentLocking associated with either option ??


Title: Re: .NET Documentation questions.
Post by: Kean on February 01, 2016, 03:55:11 AM
Can we please have a  definitive description of the full technical meaning of the noDocument parameter for the Database constructor.

purpose,
ramifications
side effects
traps

added:
Are there any special considerations regarding Transactions or DocumentLocking associated with either option ??




I assume you've seen what's in the ObjectARX docs, already:

Quote
bool noDocument = false
Boolean specifying whether or not to associate this database to the current document. When noDocument = true, then the database is standalone, which means the database does not use the documents undo controller, locking, and other services. 

I only ever use side databases independently of documents, myself.

Kean
Title: Re: .NET Documentation questions.
Post by: kdub_nz on February 01, 2016, 04:11:38 AM

Hi Kean,
This particular issue started here
http://forums.autodesk.com/t5/net/about-insert-a-block-to-a-new-database/m-p/5988683#U5988683

I went looking for a self contained answer and was only able to provide breadcrumbs.
I'm pretty sure I have a rough idea of the ramifications, but I'm not comfortable with the limitations of my understanding.

Yes, most of the information I have comes from the native docs, not the .net.

I sure wish Tony T had written his book.

... in the mean time a web article from someone who knows about the .Net API would be great. Do you know anyone who understands this stuff completely?


Title: Re: .NET Documentation questions.
Post by: Kean on February 01, 2016, 06:19:20 AM
Hi Kerry,

I went looking for instances where we either set this second flag to "Adesk::kFalse" or use the default value. Most were in samples or our test harness. In my opinion it's one of those arguments that was exposed from the AcDbDatabase constructor, back in the day, which isn't of real significance to people. The default value (IMO) should have been "true", given the fact the vast majority of cases set it to this, but it was presumably set this way for a reason, and was then propagated when we implemented the .NET wrapper to it.

I've never set this to false (or accepted the default) and never expect to. I've flagged it (mentally) as such.

Regards,

Kean
Title: Re: .NET Documentation questions.
Post by: kdub_nz on February 01, 2016, 06:42:22 AM

I have an old ( ac2008 ) ObjectARX Delevopers Guide book .. before they stopped chopping down trees.

Chapter 4 Database Operations
 --> Initial Database
 --> Creating and populating a Database

was another breadcrumb.

The difficulty with old references is that they CAN get out of date and cause embarrassment.