P3.NET

Documenting Web APIs

14 November 2015
No comments
Categories: ASP.NET, Web API

Prerequisite: This post assumes you understand what web APIs are, what they are designed for and how to write them. If not then take a look at this MSDN article first.

In order for web APIs to be useful they need documentation. Unlike traditional APIs there is no function signatures to look at. Even if you know the name of the “function” there is no easy way to get the parameters or return value. Hence documentation is important to anyone wanting to use such an API. If you are writing a REST API then the documentation is technically where the HATEOAS concept comes in. The reality is, for now at least, most people write web APIs using the REST API philosophy but without HATEOAS. Hence documentation is still needed.

The biggest issue with documentation is keeping it in sync with the code. We have XML doc tags for .NET languages and can use them with web API. But to be useful we have to ensure the documentation is refreshed whenever the API changes.  ASP.NET solves this problem by relying on the existing XML doc tags that you’re likely already using. At runtime the documentation is rendered on demand based upon the existing comments. This is one approach to solving the problem. In this article I will take a look at the “built in” functionality, identify when it might not be useful to you and provide an alternative approach that I use.

Read More

WebHooks vs Message Bus

7 November 2015
2 Comments
Categories: ASP.NET, MVC, WebHooks

WebHooks are a relatively new concept in ASP.NET but they have been around for a while with other platforms. GitHub, PayPal and even Dropbox support them already. If you are unfamiliar with the concept of a webHook then go read the introduction first. Recently I needed to solve a problem for which WebHooks seemed like a possible solution. This is my journey through that decision process.

Read More

ASP.NET MVC Is the New ASP

11 February 2011
10 Comments
Categories: ASP.NET, MVC

I have to admit that ASP.NET MVC is cool.  The ability to interleave UI elements with control flow statements makes things a lot easier than the traditional databinding of ASP.NET.  The ability to pass strongly-typed objects to methods and auto-magically have pages appear with the data without ugly hacks is just awesome.  The new Razor engine in MVC 3 takes this to an entirely new level with its much simplified, less ASP-like syntax.

But there is a problem in MVC land.  We’re building UIs so why can’t I visually see what my page is going to look like within the designer?  It brings back memories of the ASP/HTML days where you’d write your UI and then run IE to see what it looks like.  From a UI designer perspective this is insane.  One of the really big features of ASP.NET (and perhaps Visual Interdev) was that I could write my UI and then switch over and view it without leaving VS.  I could even drag and drop controls onto the form and voila I could make changes until it is just right.  No such ability in MVC.

Pundits generally justify this lack of functionality in MVC in one of the following ways:

  • It’s MVC, you don’t care about the view layout since you’ll use CSS to format it – Bull.  CSS controls basic layout, coloring, fonts, etc but there is absolutely no way to verify how your view and CSS play together without actually running it.  One of the big “advantages” of MVC is that we are suppose to be able to pass our view on to a UI author but how many authors do you know that could read MVC blocks and understand them.  It isn’t simply a matter of ignoring the blocks because those blocks control what gets generated when.  So a UI author has to understand MVC just to write the view.  All we’ve accomplished here is to move the complexity from our code to the UI.
  • MVC has extensible view engines so a VS designer would have to support them – So?  IIS renders the various webpages without regard for the underlying rendering engine.  VS itself is designer agnostic.  How hard is it to create a separate designer for each of the view engines that can then be invoked within VS just like in ASP.NET?  All it really takes is some prioritizing.  A UI designer seems pretty important for a UI technology.  Even more so then some of the other features that have been added into MVC.
  • Browsers render things differently so the designer might be wrong – That is true but didn’t ASP.NET have the same issue?  Technically though one of the big benefits of MVC is that most of the view is browser-agnostic.  The various support files are there to help ensure that it renders the same across all browsers.  What better way to test this functionality then by using VS as a testbed?
  • It would just be too difficult – I bet they said the same thing before ASP.NET came out.  I don’t believe there is any technical problem that cannot be resolved.  ASP.NET, in my opinion, is the harder technology to design for since it is so monolithic and structured so it seems that MVC should be easier to create a designer for.
  • Use ASP.NET for your UI and MVC for everything else if it is such a big deal – What?  That would be like C# not supporting integers and the justification being that you can just use Fortran for the math.  Mixing and matching equivalent technologies, while useful when necessary, should be avoided.  It complicates the project, requires more skills from the dev team and can cause interop issues. 

Here’s my solution – add full UI designer support for MVC!!!  How hard can it be to invoke the correct view engine in the VS designer?  MVC view engines are far less heavy than ASP.NET so it seems like a relatively easy task.  Since ASP.NET is already supported the infrastructure needed to host a web-based engine is there.  It just needs to be tweaked to allow MVC engines to run.  Even if we cannot guarantee that a page will look exactly the same when rendered in a browser it would at least give us a better idea of how it might look.  The ASP.NET designer supports loading the CSS correctly so an MVC engine should be able to render pretty close to what we’d expect.

To me the lack of a UI designer (IE doesn’t count) is a really big mark against using MVC in a project.  I started using MVC in a couple of projects but since most web apps are UI-heavy I had to back away.  It was simply to painful trying to build the UI in an MVC-friendly manner.  The whole concept of MVC is great.  I just can’t understand why the V part of MVC is so difficult.  After all isn’t the entire purpose of MVC to allow us to separate M, V and C to simplify development?  It’s really ironic.  They say history repeats itself and I agree.  We started with HTML, moved on to ASP, then to ASP.NET and now we’re back to MVC.  UI designer wise we’ve come full circle.  Perhaps the next great framework innovation will take all the great things of MVC and combine it with a usable designer so we can actually get our work done.  Just my opinion

Web Sites vs Web Applications

23 May 2010
No comments
Categories: ASP.NET

(Originally published: 3 January 2009)

One of the biggest confusions in the ASP.NET world is that of web project type.  Visual Studio (VS) supports two web project types: web sites and web applications.  Unfortunately, they are different enough that it is important to understand which type you are using and why.  In this article we will discuss the differences between the two types by looking at their history.  By the end of the article you should be comfortable enough to determine which type is best for you.

Web Application

When Visual Studio .NET (VS.NET) was released it supported a single web project type, the web application.  A web application looks and acts like a regular Windows or console application.  A web application contains a set of project property pages which the developer can set including build and debugging options.  This allows, for example, the developer to generate documentation for any code contained in the project.

When a web application is compiled all the source files (including the codebehind files) are compiled into a single assembly and stored in the Bin directory.  The ASPX files are deployed with the binaries.  At runtime the ASP.NET runtime compiles the ASPX files into an assembly when they are first needed.  If an  ASPX file ever changed then a new assembly is generated.  The initial version of .NET did not support dynamic code generation like it does now so the performance overhead was a little high when recompilation occurred.  As of v2.0 ASP.NET compiles the ASPX files differently to reduce performance hit and to optimize memory.

The fact that web applications work similarly to other project types is also one of its greatest disadvantages.  A web application has to be deployed as one entity.  If different parts of the application are managed by different teams then some repository is needed to allow changes to be consolidated and deployment to occur.  This infrastructure also slows down the rate of the site changes.

Web applications are designed for projects where the entire site is a single entity.  Any changes to the project requires redeployment.  Multiple teams must synchronize their code before a build can occur.  The application code itself is protected from prying eyes when it is compiled into an assembly.

Web Sites

When Visual Studio 2005 (VS2005) was released Microsoft removed the web application project type and replaced it with a web site.  Somebody at MS dropped the ball here because these project types are completely different.  A web site project is more ideally suited for intranet sites where separate teams are responsible for different areas of the site.  In an intranet environment the safety of the source code isn’t as important as a fast turnaround time.  In a web site project almost all the project settings are either removed or stored in the application configuration file.  Options like whether to generate documentation files or do code analysis simply don’t exist in web sites.  This fits in with the web site philosophy of compile as needed.

Only code residing in the App_Code directory is compiled down into an assembly at build time.  The remaining code becomes deployment items along with the ASPX files.  This has advantages and disadvantages.  Making changes to a web site requires that you merely replace the corresponding source or ASPX files.  The ASP.NET runtime will recompile the code as needed.  The turn around is therefore high.  Pushing most of the project settings to the configuration file also means that upgrading to newer components or tweaking build settings requires a simple change to the config file rather than compilation and redeployment.

Perhaps the biggest weakness of the web site project type is that the source code is visible and changeable to the outside world.  Outside world, here, meaning anyone with file access to the web directory.  IIS prevents web access to the source and configuration files.  Another issue is performance.  As files change recompilation has to occur.  ASP.NET only does this when a page is first referenced so viewing a page is noticeably slower the first time after a refresh.

After the VS2005 release there was an uproar in the community about the new web site project.  It wasn’t that nobody liked it but rather many people didn’t want to be forced to use the new model, especially since it didn’t fit in with many application models.  MS remedied the situation by shipping an addin that would add the web application project type back in.  In VS2005 SP1 web applications were formally added back into the VS project list.

Web Deployment Projects

One area that neither type of web project covers is the compilation of ASPX files to assemblies.  In the initial release each ASPX file resulted in a separate assembly.  This was great for ASPX files that changed a lot but bad for performance as each page was compiled, not to mention the number of assemblies generated.

After VS2005 was released MS released the Web Deployment Project (WDP) addin (here).  This addin exposed some new options for controlling how web sites were deployed.  Rather than compiling the ASPX files when they are needed the addin allows for precompilation of the site to speed things up.  This has no impact on the site behavior because if an ASPX file changes then a recompilation will occur anyway.  The benefit of this approach is that the initial load of the site will be fast since the ASPX files are already compiled.

Another area where the addin is useful is controlling how the site is compiled.  The addin allows: all the ASPX files in the site, all the ASPX files in a directory or each individual ASPX file to be compiled into separate assemblies.  The best choice depends upon the site in question.  The more ASPX files you combine into a single assembly the better the performance and memory usage will be but at the cost of more overhead when any of the files change.

The addin supports several additional features that makes it worthwhile if you are managing a web project.  I recommend that you take a look at it.  The multiple configuration file support is especially interesting although it was difficult to use in the initial release.

The addin technically doesn’t do a lot on its own.  Instead it relies on a couple of ASP.NET tools that ship with .NET: aspnet_compiler and aspnet_merge.  (aspnet_compiler is responsible for compiling the ASPX files.  It is used to for precompilation and to control whether ASPX files can be updated after deployment.  Refer to MSDN for full documentation.

aspnet_merge works in conjunction with aspnet_compiler to merge the various ASPX assemblies into a new assembly or set of assemblies.  It also is responsible for determining what gets combined and what remains separated.  Refer to MSDN for full documentation if you are interested.  It is probably just better to use WDP instead.

Note that VS supports publishing web projects (site or app) directly without the need for deployment addins.  However the publishing tool is strictly for publishing the existing project without changing most of the options.  The deployment project is for taking more control over the publishing process.

Feature Comparison

We will now compare the two web project types so that you can make a more informed decision.

Web Applications 

Advantages

  • Ideally suited for web projects that have little or no changes over time and in cases where the project code is proprietary.  Applications that use a web front end are good examples. 
  • Standard project settings are available so a developer can configure the application.
  • Since most of the code is pre-compiled the application performance is good.
  • Deployment involves copying the ASPX files and the Bin directory.

Disadvantages

  • Other than minor UI changes any application changes require recompilation and redeployment.
  • Upgrading to newer third-party components requires recompilation and redeployment.
  • Turn around time for changes can be long depending on deployment process.
  • Sites where different teams are responsible for the content are harder to synchronize.

Web Sites

Advantages

  • Faster turnaround for code and UI changes.
  • Multiple teams can be working on different areas of the same site without compilation or deployment issues.
  • Configuration and dependency changes can occur with a configuration file change.

Disadvantages

  • Page loading is slower after any changes are made.
  • Source code is visible to anyone with file system access.
  • Deployment requires shipping the ASPX files, Bin directory and source files.