Mathew Nolton Blog

Software dementia unleashed...
Be Careful Generating XML Documentation with .Net

If you are like me, you like to use the XML commenting feature that comes with .Net. Personally, I only turn this feature on when I am creating a release build. However, if you do this make sure that you turn-off the read-only property on the output xml file. Failure to do so can will cause your build to fail.

This happened to me recently with a rather large solution set and I could not for the life of me figure out why all of a sudden when I switched to release build my solution set failed to build properly. If it was just a single project solution or a small solution set, it might have appeared obvious. It was only after I did a 'clean' of my obj and dll files that I was able to see that it was unable to write the output xml file that the error became more pronounced in my output. I quickly turned off the read-only attribute and it finally built. I hit this problem a while ago...but my memory must be fleeting.

Note to self: When doing a release build make sure to turn off the read-only attributes on the generated xml file (I keep this file in source safe with the rest of my project files).

-Mathew C. Nolton

Posted: Jan 17 2005, 03:50 PM by MatiasN | with no comments
Filed under:
Too Funny. George Forman Grill meets WebServer Technology

A friend of mine sent this to me. It is too funny. The guy turned his George Forman grill into a WebServer. It takes a while to bring up the page. Apparently the George Forman Grill/WebServer is actually serving up the web pages.

http://www.igrill.co.uk

Ha.Ha.

-Mathew Nolton

 

Posted: Jan 11 2005, 03:48 PM by MatiasN | with 1 comment(s)
Filed under:
Using the <remove> tag with web.config can be helpful.

Most people use the web.config file to define features or pieces of functionality to be used by their application. You may or may not know it, but there is a feature of the web.config file that enables you to remove definitions defined by a parent web.config file. This is especially important when an application (either rightly or wrongly) places a web.config file in the root web directory or your parent directory that adds functionality or puts a constraint on all child directories that you do not want or that will break your application.

The web.config file has a heirarchy of sorts. All applications pick up their defaults from the machine.config file. Your application then uses any parent directory web.config file before using it's own web.config file. This means that if you are a couple levels deep and your parent directories have web.config files defined, you will pick up your defaults first from them before your own is processed.

This heirarchy is helpful when carefully planned; however, if a parent directory makes assumptions that are not valid or the person deploying the application does not consider all avenues, it presents a problem. I ran across this situation when a commerce server implementation added some .net functionality and placed a web.config file in the root web directory. When I deployed my .net application I inherited all of its defaults....which would have broken my application. To get around this, I used the <remove/> tag of the web.config. For example, the CommerceServer implementation defined a number of commerce server pieces that I did not want...nor could my application handle:

<configuration>
   <configSections>
      <remove name="CommerceServer/application"/>               <---- Most sections enable you to remove
      <remove name="CommerceServer/authentication"/>
      <remove name="CommerceServer/pipelines"/>
      <remove name="CommerceServer/caches"/>
      <remove name="CommerceServer/messageManager"/>
      <remove name="CommerceServer/catalog"/>
      <remove name="CommerceServer/orders"/>
      <remove name="CommerceServer/profiles"/>
      <remove name="CommerceServer/contentSelection"/>
      <remove name="CommerceServer/commerceEvent"/>
   </configSections>
   <system.web>
      <httpModules>
         <remove name="CommerceApplication"/>                        <---- Most sections enable you to remove
         <remove name="CommerceAuthentication"/>
         <remove name="CommerceOrder"/>
         <remove name="CommerceProfile"/>
         <remove name="CommerceExpressionEvaluator"/>
         <remove name="CommerceCache"/>
         <remove name="CommerceContentSelection"/>
         <remove name="CommerceCatalogModule"/>
   </httpModules>
............................
   <compilation defaultLanguage="c#" debug="false">
      <assemblies>
         <remove assembly="Microsoft.CommerceServer.Runtime, Version=4.5.2002.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>           <---- Most sections enable you to remove
      </assemblies>
   </compilation>
  <customErrors mode="RemoteOnly" />
............................
 </system.web>
</configuration>

Be carefule using the <clear/> tag, it will clear out everything for that section including defaults from the machine.config file....Typically, you do not want to do this.

Overall, if you have a parent application or parent web directory that isn't well-behaved, you do have options in working around this problem.

-Mathew C. Nolton

Posted: Jan 10 2005, 11:35 AM by MatiasN | with 6 comment(s)
Filed under:
How good are you at spotting a fake smile?

I found this on the Internet. It tests whether or not you can spot a fake smile. I got 12 out of 20 correct.

http://www.bbc.co.uk/science/humanbody/mind/surveys/smiles/

-Mathew Nolton

Posted: Dec 29 2004, 09:28 AM by MatiasN | with 9 comment(s)
Filed under:
WebServices are just an implementation of SOA

I am guilty. Too often I equate a WebService and its implementation with the overall definition of SOA. (For example here). In reality it is nothing more then an implementation. A good implementation, but just an implementation. Clemens Vasters gave a nice definition of the tenets of SOA called PEACE.

  • Policy-Based Behavior Negotiation
  • Explicitness of Boundaries
  • Autonomy
  • Contract Exchange
  • It is a nice acronym that attempts to summarize exactly what a service is. Much like ACID does for transations (Atomic, Consistent, Isolated and Durable...). There is some debate about this ACRONYM, but it is fair to say that most if not all agree with the 4 basic tenets...

    However, nothing in this definition speaks to platform independence. Does this mean that distributed system design and some of their implementations (e.g. think DCOM/CORBA/RMI/Remoting) and their platform dependence mean are OR are NOT SOA. They are. All these implementations do follow these tenets. I am not an RMI/CORBA expert but I did worked extensively with DCOM in a prior life. It did allow you to work in a more OO manner then a WebServices implementation. There were rules especially around transactions and how the state of your object could be affected, but you could do it. However, it's Contract followed a binary format that was not readily understood by other platforms. RMI had a similar flaw only working with the Java language.

    A WebService on the other hand is platform and language independent. It's use of Xml enables different platforms to communicate with one another. Additionally, a WebService is very procedural in nature. Some have argued that they are object based. Or that because methods are verbs they act as objects. Personally, I don't buy it...however, in the grand scheme of things this is more an argument of semantics.... Given that, there are also a number of rules about how client proxies are generated and this does effect how you construct your tiers. I discuss this here (same blog entry reference as above).

    In the end, I am guilty of confusing terms. A WebService is just an implementation of SOA. It is not the only implementation.

    -Mathew C. Nolton

    Posted: Dec 15 2004, 10:53 AM by MatiasN | with 3 comment(s)
    Filed under:
    New Version of XmlPreCompiler Available for Download

    I updated the XmlPrecompiler tool on my website. It is an enhancement to the version I posted in my blog a couple of weeks ago. http://weblogs.asp.net/mnolton/archive/2004/12/01/273027.aspx

    It is available for free download. For those who haven't used it before, I put a user interface on top of a tool Chris Sells wrote called XmlSerializerPreCompiler.Exe and you can download it here:

    http://www.cybral.com/solutions/tools.htm

    The tool solves the xml serialization problem when you get those nasty serialization messages that really don't tell you anything. Like "File or assembly name ctewkx4b.dll, or one of its dependencies, was not found". This tool checks to see if a type can be serialized by the XmlSerializer class and if it can't, it shows the compiler errors happening behind the scenes.

    The updates I made to the tool are as follows:

    1. If the application gets a ReflectionLoadTypeException, the application will spin through the inner LoaderExceptions in order to give a more detailed reason as to why a problem occurred.
    2. Added the ability to view assemblies referenced by the selected assembly.
    3. Sorting. Ward Bekker suggested sorting and it was a good idea. I also now display all types regardless. I used to only show classes. I also added a column that will display what it is (e.g. class, enum, interface, etc.) and I let you sort on this as well.

    Happy Programming,

    -Mathew Nolton

    Posted: Dec 13 2004, 07:58 PM by MatiasN | with no comments
    Filed under:
    Is Less Code Better?

    The answer is, it depends.

    I have spent a large portion of my career developing products for a software vendor(s) in the ERP, B2B and B2C spaces. More recently I have been working as a consultant at large companies and I often here different managers suggest that less code is better and is a packaged solution better then a custom solution? Earlier in my career and while working at these software vendor(s) I had the pleasure of going on a number of sales calls and watched sales people work their magic. I've heard the statement "with a Customization of our product, you can do what you want". The questions every company should ask is or things they should consider are:

    1. Time to market is typically key to success for many companies. This means you must know your business and know exactly how the 3rd party software will grow with you. It does little for a company to quible over $X dollars in software costs if you can't get to market in a timely fashion. Nor make the changes that the business requests or that you foresee the business requesting in the near future.

      The question to ask, "Does the vendor truly understand my business?" If the answer is yes, then look deeper, it may be the right choice. If the answer is No or you are not sure, dig even deeper and come to a conclusion. It does little for you or your company if your time to market will be adversely affected.

      If the answer is No they do not understand my business, then writing less code means you cannot adapt to a changing competitive landscape. So either look for another vendor or consider doing it yourself.

    2. Not all vendor code is created equally. There is a lot of crap out there. Enough said.
    3. Less code is not always better code. I have seen people write less code that is terribly inefficient and error prone. Or write code that takes advantage of a piece of software that is error prone. I have also seen some developers write very efficient and performant code that has more lines of code but with less bugs. This means, know your architects and developers. A good one makes all the difference in the world in the success of any project whether customized packaged software or a custom solution.
    4. When buying a solution, determine exactly what customizations are required and can the consultants you hire who are familiar with the product do it in such a way that minimizes customizations and maximizes value. Keep in mind that for many companies who customize the solution spend at least $2-3 for every dollar spent on software. If the customizations are large, the number goes up considerably from their. Furthermore, the cost of upgrading to a new release also goes up considerably with every customization made. So, are you still writing less code? Remember follow-up service contracts are where vendors have large profit margins. This isn't a bad thing at all for you or the vendor, but keep that in mind when you are determining how much customization is required.
    5. Sometimes the customizations are so large that you spend so much time figuring out how to make the tool/product do what you want that you are truly better off writing it from scratch. Or leveraging a software factory or smaller piece of 3rd party code that provides the small piece of functionality you are looking to achieve.

    I have seen a number of software package implementations with so much customization that they might have well been written it from scratch.

    Posted: Dec 09 2004, 08:26 AM by MatiasN | with no comments
    Filed under: ,
    Another List on SOA.....Ohh and SOA != OO

    The term Service Oriented Architecture (e.g. SOA) is thrown around quite a bit these days and it always amazes me the speed in which people jump into them and the assumptions they make. There is no doubt that SOA adds a positive dimension to any application architecture. I have been building and deploying webservices for close to 2 years now. Before that I worked on a number of other service based architectures and there are things to consider before jumping into them.


    1. SOA is just one dimension of a good architectural scheme. It is not THE architecture. 
    2. In some respects (but not all) SOA and OO are orthoganal. OO is about keeping data and the methods and properties that act on the data in the same class. With an SOA architecture, client proxies are generated by the WSDL. Only public properties with getters and setters are created in the proxy. All methods and any business logic is NOT generated on the client nor included in the client proxy. This leads some to actually put the class that is being serialized onto the client as well (yes I have seen people do this/try to do this on a # of occassions) which can cause name collisions and really negates the positive aspects of SOA. If you want to put the class being serialized on the client, then you should take a serious look at Remoting.

      The fact that the client proxy only contains the class's getters/setters, leads many developing SOA architectures to seperate business logic classes from their business entity classes. The benefit of this seperation is a positive one but clashes with some OO principles because you are seperating data from the methods and Business Logic (BL) that act on the data. The BL that supports acting on the data is on the WebService machine and the class that gets serialized from the webservice is a seperate Business Entity object and the basis for the Client Proxy (via WSDL).

      This is not to say that you cannot follow a stricter OO model by keeping the two together but often times it causes confusion by users of your libraries who are unfamiliar with the way client proxies are generated on the client and expect the methods and business logic to show up on the client in the same proxy ...which does NOT occur. Personally, I recommend the seperation by keeping business entity classes and business logic classes seperate and knowing full well that I have broken the OO model to some degree...the benefit (IMHO) outweighs the costs.


    3. Remoting and SOA are not the same. Remoting follows the OO paradigm much more closely by providing a Marshal-By-Ref (or a MBV if you know what you are doing) proxy to the actual objects and its methods and properties. This means you can actually call the methods on the object itself via a client proxy and the business logic remains in tact. This follows the OO paradigm much more closely then a WebMethod because the client proxy is aware of the business methods and the business logic encapsulated in the object itself which isn't available with a WebMethod implementation. Furthermore, remoting assumes a .Net implementation which enables you to keep (and often requires) the class being proxied to exist on the client.
    4. Exception handling with an SOA architecture is different. You can still use the try/catch metaphor but all exceptions are of type SoapException (there is also SoapHeaderException but this means no detail block). This means that their is no differentiation in error typing. In other words, all exceptions emanating from a web service are of type SoapException. There is no way to distinguish between exception types without looking at the DetailBlock in the SoapException and developing your own "contract" between server and clients. I wrote a blog that provides some insight into how to use this detail block to your advantage http://weblogs.asp.net/mnolton/archive/2003/09/17/28015.aspx; however, there are some shortcomings of this approach. The client must know to look at the detail block correctly in order to act on the information it contains. The only alternative is to just show your client whatever error information comes back from the service...but this prevents your client application from acting on the exception in a meaningful manner (which I personally think is a bit of a hack because you cannot really control what a server is going to tell you).

      It would be nice feature to provide a "Throws" construct similar to what Java does that would enable someone to decorate a method with a custom attribute(s) that details the exceptions that can emanate from the client. Then in the client proxy, generate an exception proxy (I think this is already supported) but then also generate proxy code that evaluates error conditions and throws the correct exception from within the client (not supported with WSDL.exe).  Hmmm, it would be a nice feature for Christian Weyer's WsContractFirst tool :)


    5. Just because you can create a WebService doesn't mean you should. The cost of traversing the SOA boundary is high. For example, I have seen a number of people try to put a WebService interface over their database. What's the point? If you want to talk to a database, use native libraries in your language of choice. It is much more efficient. Also, a WebMethod should expose a business contract...not a data contract. If you provide just data to your client then you are now tying your client to your data implementation. If that should change then your client is screwed. Instead, create a business contract and make data access a concern of your BL that is called by your WebService. Don't tie your client to it. Often times when I see this it is by a developer who just want to create a WebService.

    As always comments and feedback are encouraged.

    -Mathew C. Nolton

    Posted: Dec 08 2004, 06:45 PM by MatiasN | with 4 comment(s)
    Filed under:
    CodeMax-A component worth looking at.

    About 3-4 years ago I wrote a tool called TemplateX that enabled the building of an application or a piece of an application using a template and an ASP syntax. I did much of this prior to .Net and it had much of the functionality plus some of what Eric Smith's CodeSmith does (but Eric did a much better job of marketing his tool and taking it to the next level with actually compiling .Net code. He also realized that you must charge little as well as provide a large library of templates to get people to use it..kudos Eric). At the time I needed an editor and I selected CodeMax. This is an awesome component and worthy of consideration for anyone doing syntax highlighting. It now costs $199 (it used to be free) but if anyone has actually ever considered writing the code for an editor that does syntax highlighting for a large document you understand the complexity and performance considerations you must take into account. It can be found here. http://winmain.com/

    -Mathew C. Nolton

    Posted: Dec 06 2004, 10:47 AM by MatiasN | with 7 comment(s)
    Filed under: ,
    Top 10 Things to do on a software project (err 9 things...I got tired).

    I have been a software professional for about 15 years and I have lead and/or architected a number of them. Here is a list of the top 10 things to do and/or avoid. Please add to the list if you are so inclined.

    1. Define requirements in a declarative fashion. Never give a dissertation about why. You can do this in a supporting document if required; however, the requirements themselves should concisely dictate what is "Required" (regardless of the methodology you follow). I recently had the pleasure of looking at a 77 page requirements document. The intentions were good but it was almost impossible to design a system from it.
    2. Requirements are not about implementation: Always keep implementation details out of your requirements document....enough said.
    3. Understand the business. Often times developers/programmers just want a spec and code to it. Although important, go to meetings with the business sponsors/customers and understand their needs. Doing so gives you insight into what they are trying to accomplish and better enables you to satisfy their needs and grow as a professional.
    4. Never underestimate what it takes to roll-out/implement a system. If you have a complex data-driven system, gathering data can take a large amount of time and must be accounted for in your project plan and conveyed to management. Underestimating this can kill a project.
    5. Always pick a small highly-competent team over a large army. Larger teams require more communication and the management of the communication is much higher as you add more people to your team. A friend of mine made the analogy of using the Navy Seals versus the Army (also consider brook's mythical-man month "Adding manpower to a late software project makes it later.").
    6. Sell your system. Whether you work in an IT department of a large corporation or a software vendor, selling your system is key to your success. Good software houses spend a large amount of their time and money selling their software and keeping their customer's happy. IT departments sometimes forget that they too must sell and evangelize their products (competing budgets, teams et. al).
    7. Provide vision. Selling your system requires a vision, a problem statement, the solution and the costs and benefits of the system. Also, most complex systems have a life-cycle that defines what it will look like in each stage of its development from infancy to maturation. If you follow best practices and define a tiered architecture, you can also provide a vision as to how a collection of libraries and services can grow to become the basis for many projects.
    8. Documentation is about communication: This shouldn't be a problem for most developers :). Many processes have a set of documentation to be completed. But often times there is also a lot of latitude in how deep you can go with your documentation. The problem is "when is enough enough". Years ago while working on my first UML project and I was trying to determine what this balance is and my VP said that documentation is about communication. You must convey what your team requires to get the job done and then support the system. Smaller highly competent teams means that many/all of the members can make the leap of logic to fill in any gaps.
    9. Don't bother documenting your entire API by hand, use documentation generators. C# provides the /// construct that enables the auto-generation of your API. There are also a number of tools out there such as NDoc and DocumentX that further refine documentation generation. (including your database). This isn't a substitute for a design document that defines the process you are designing but don't bother with all of the tactical implementation details and documenting every method/property signature ad naseum. They get out of date so quickly. Instead, invest in one of these tools and auto-generate API docs on a periodic basis.

    -Mathew Nolton

    Posted: Dec 02 2004, 08:53 AM by MatiasN | with 4 comment(s)
    Filed under:
    More Posts « Previous page - Next page »