KastroNYC wrote:
I've been using LLBLGen for a few months and I still can't seem to figure out how the framework works. The documentation provided is okay i guess but far from complete.
I can take a lot of critizism, but I can't accept a qualification of the documentation as 'far from complete'. It's over 400 (!) printed A4 pages, and often stated as a great documentation. I agree that it's not perfect, but NO documentation is perfect, there are always things to improve.
The documentation is build in 3 layers: first the concepts, then the designer, and then the generated code. Every feature is explained, often with an example.
I'd like to know how the architecture for the framework works from beginning to end. I'm trying to convince my clients and business partners to use the LLBL generated layer but i'm having a hard time doing so when faced with simple questions like how the framework works and what the various classes in the generated code library do.
That are two different things. What the various classes are is documented in the reference manual, located in the installation folder, or downloadable in .chm form for .NET 2.0 from the website. How these classes work depends on what you want, which then results in the selection of a set of classes and methods to perform a task, e.g. fetching entities, saving a couple of entities and so on.
What I find odd is why you havent contacted us with these questions and we could have helped you out, as often these questions are documented somewhere in the documentation (which is so big I don't even know what's in there anymore, so I won't be surprised it's hard to remember everything in the docs and how it works after just reading how it works) or easy to explain.
What you should focus on however is 'how to do this' or 'How to do that', then go to the manual, look at the feature you need, and apply that feature in your code. that's also how you use .NET. I'm sure you didn't look at every class in the massive .net class lib, what the class does etc.. As you are an ASP.NET trainer, you will know that for example the ASP.NET 2.0 documentation isn't perfect either.
I was asked recently by one of my business partners while reviewing the code for the framework what alot of the properties and methods were doing and whether it was even neccessary to include such fields and methods and I was having real trouble figuring it all out. Additionally I've been asked what the DQE and ORM classes are, how they work as well and without a definative answer my business partners have advised against using LLBL because of the complicated nature of the framework, the array of properties and methods which we do not understand and instead build our own business layer using datasets/datatables, etc.
Why? I hope you didn't think we wouldn't answer your questions, because we would have been and still are happy to answer your question, no matter how little the question might be.
The generated code contains XML comments, precisely for this purpose. You can generate a reference manual from the build generated code easily with Sandcastle for example or if you're using .net 1.x, with NDoc. Add the ormsupportclasses dll and .xml file to the project and you'll get complete inheritance hierarchies, documentation what which method does, which field is mapped onto which table field etc. etc.
For the ormsupportclasses and dqe's, we ship the reference manual ourselves, which is often enough to get documentation on the majority of methods.
They are pushing in this direction and mentioning that because we'd have complete control of the business objects we could make them alot lighter than the LLBL type classes and since we don't really understand what all of the properties and methods do in every class they are essentially useless to us.
It sounds as if they're looking for a reason to do their own framework. Well, as a person who has been there and has written a full blown DAL with a lot of features: it's a lot of work and takes a lot of time.
Building user interfaces and tying them to the llbl layer is very easy which is why i haven't had many issues so far, i've been building simple prototypes based on a complex data model, but trying to take the layer to the next step and adding in the business rules and so on is where i'm stuck.
I think it's wise to formulate these problems into smaller questions and post them here, or in the general forum. In general it's easy to get you going. What's hard is to come up with proper examples which suit everybody, as your situation and your project is likely very different from the next guy's project or our own big example project (this forum system) which will go open source next week. Even with this big example project at hand, it won't be the case that you'll find the answer for every question you might have as it's likely your project is perhaps a little different, has different requirements or you just don't like a given solution.
BUt that's ok, llblgen pro is very flexible and offers multiple ways to get things done, so there's always a way. So I'd like to ask you to explain brief but clear the problems you ran into and we'll have a look and try to help you get on your way.
Expert one-on-one business objects by Rockford Lhotka is a great book which described his CSLA.NET framework initmately and gives us the ability to understand the "why" behind building the framework as well as the "how". Since LLBL is such an extensive framework it would be a dream come true to have similar documentation (and yes I understand that the documentation I mention is actually a complete book!).
Our documentation is indeed a thick book, over 400 A4 pages, so in bookformat, it's about 600 pages. Though that doesn't make it a great read of course, it's a manual, not a bed-book, so it can be dull at times and perhaps boring. But it doesn't lack descriptions of features which are there, it might be the context in which the feature could be applied is unclear, or you're uncertain how to get started with a feature. That's often easily solved by a small example tailored to your situation so you fully understand what the meaning is as the example matches the question you're asking.
I hate to say it but the documentation included with LLBL is far from complete. It has a great FAQ which is perfect for quick answers to common questions, but the documentation is completely oblivious to those of us who want a complete understanding of everything which LLBL generates.
I don't see a FAQ in the docs, do you mean the How do I section?
Some background about me, I'm an Microsoft Certified Trainer teaching ASP.NET development courses in New York and as I mention, I'm a big fan of LLBLGen, i'd like to refer the software to my students during class but i've been reluctant thus far because of my lack of understanding the details of LLBL framework. I've tried thumbing through the code and trying to glean an understanding that way but still i'm somewhat lost.
Code isn't a good teacher, so you should start a couple of abstraction levels above that.
Please let me know what I have to do to get detailed explanations of each class, method, property and event in the framework as well as the inheritance hirearchy and a complete understanding of what the generated LLBLGen code is capable of.
What it capable of is described in the manual, as every feature is documented. I sound like a broken record, I know, but that's simply the case. What every class does, what every method does, that's not in the manual, that's in the reference manual, also on your system, in the installation folder. In v2.0 we shipped only the runtime library reference manual as every generated code assembly is different, so it's better that the user him/herself generates these reference manuals from the generated code together with the ormsupportclasses dll/.xml files and dqe dll/xml files. As said, the generated code contains documentation texts so the reference manual you'll get out of that is documenting your entities, fields, methods in the generated code like GetMultiOrders(..) etc. complete with inheritance hierarchy. It's a little sad that ndoc doesn't support .net 2.0 so you'll need Sandcastle CTP for that (form microsoft).
For the problems: please formulate them into questions so we can help you get started, you're not alone, we're here to help you and I'm sure we'll get you started.
One sidenote: I still have the feeling your business partners try to find a reason to get their own code into the app no matter what, but let's sidetrack for a second and focus on solving your problems first.
.