Visual Studio 2012 (Update 2) and later includes the ability to publish Web Site projects to the Web server. Using either IIS WebDeploy or FTP, you can basically publish an entire Web site - all the HTML templates, HTML, CSS, Scripts and configuration files and even your executables if they exist as part of the live application.
The Web Publish feature is designed for ASP.NET or plain HTML projects, and is drop dead easy for those deployments, a few small adjustments have to be made to ensure smooth publishing for Web Connection projects. With a little forethought you can even make Web Deploy deploy both HTML and FoxPro executable content.
IIS Web Deploy
IIS Web Deploy is a Microsoft IIS related transfer protocol that allows you to publish files from a client machine to the Web Server. This is a two-way service protocol that has some smarts associated with it to know what's been published on the server and transfers only the content that has been changed. FTP deployment is also available but this deployment is generally less efficient and currently at least doesn't support individual file publishing.
If you're going to use this feature - Web Deploy is the preferred choice.
To run Web Deploy you have to install it on the IIS Web Server. The latest version is Web Deploy 3.5 which can be installed using the IIS Web Platform Installer.
The latest version - unlike older version - is completely self-configuring and once installed is ready to go. Older versions required multiple steps and service startup, but the current version once installed just works.
If you can't install Web Deploy you can also use FTP to publish. The rest of this tutorial assumes Web Deploy, but most features work the same except configuration, and as of VS 2012 Update 2 individual file publishing was supported only with Web Deploy.
What can you publish?
Before digging in on Web Publishing works, let's discuss how Web Deploy fits with Web Connection. Web Deploy is typically meant for ASP.NET based Web sites. Web Connection doesn't quite fit that profile, but you can still use Web Deploy to publish all the Web related files of a project. This means you can publish all your HTML templates (ie. your script mapped templates), all static files (HTML, CSS, JS, Images etc). For Web Sites projects Web Deploy basically copies ALL files in your folders to the server. Exceptions are the Web Deploy related files, and user specific configuration files.
If you decide to hold your executables in a subfolder of the Web folder (like the Web Connection.deploy folder for example), you can also publish an executable this way. But you have to be careful - if the executable is running and locked the publish will fail at that point and not update files based on the locked file failure. In order to copy executables you'll likely have to stop the application before updating.
Using Web Deploy with a Web Connection Project
By default Web Connection uses what is known as a Web Site project in Visual Studio. A Web Site project is a free file project which means that there's no explicit project file, but rather the project is simply a directory with files in it. This works well for Web Connection because in although Web Connection simulates ASP.NET applications, it's not really an ASP.NET application.
To publish files you can simply go the Site's root node and right click, and select Publish Web Site:
Here I'm on the TimeTrakker project and then selecting the Publish Web site option from the context menu.
Create Publish Profile
The first thing you need to do is create a Publish Profile where you specify where to copy files to on the server. To do this click the drop down on the publish dialog and select <New Profile> (note: the pic below shows an existing profile of mine in the dropdown- for a new one it'll be blank).
In the dialog that pops up give it a name and press enter. I'm going to use FoxMobile for my project, and I'm going to install it as a virtual directory underneath a TimeTrakkerFox Web site on my server.
Next you're presented with connection properties. Here you specify the root Web Server URL and a site name:
The Server is the root Web server name or IP address. If you have multiple sites any site will work - this is just to connect to IIS and connect with Web Deploy on the server. The Web Deploy client then hits this url: http://yoursite.com/MSDEPLOYAGENTSERVICE).
The Site name is the name of the IIS site *as entered in the IIS Service Manager* and this is where files are copied to. If the site does not exist yet Web Deploy will crate it in its default configuration. I don't recommend this - pre-create your site and virtual folder and disk location for your files.
So if you look in IIS under the Sites node, you'll find the name of the site. If you're installing to the root of a Web site, just use the sitename. If you're installing into a virtual folder below a root site as I'm doing here provide the name of the virtual with a forwardslash after the site name:
if you just publish to the site root the syntax is simpler:
Finally provide your username and password and check the checkbox to remember your credentials. Next validate the connection - this is important. Click the validate button to ensure that the connection actually works before moving on. If you have a problem you'll get a reasonably useful error message here such as site doesn't exist or invalid credentials etc.
If the connection validates go ahead click Next and/or Publish and Visual Studio will now copy all your project files to the server.
What gets copied
Because Web Site Projects that Web Connection uses by default are based on simple file structure, Web Publish copies everything in all of your folders to the server. There are a few exceptions of Visual Studio work files, but otherwise everything gets copied.
One thing that is important when you publish to a live server is that your configuration setting for the local machine and the server might be different. If you're using the Web Connection module configuration settings are stored in the web.config file and you typically have a few values that are different between the local test environment and the live site.
Web Deploy includes a feature called config transformations that allow you basically create different configurations and based on that configuration apply some transformations to the configuration file. This allows you to customize the handful of keys that might be different between local and remote installs.
AFAIK this is the only way to really handle configuration files because at least on Web Site projects there's no easy way to exclude files from uploading. So the web.config file is always sent. Config transformations allow you to customize the settings however.
To create a config transformation go to App_Data/PublishProfiles/YourProject.pubxml in your project:
This enables config transforms in the project and adds a new web.debug.config file to the project. This file is the transformation file. 'Debug' refers to the build configuration which by default is 'Debug' and which you can see in the top toolbar. You can create additional build configurations, so it's possible to associate multiple deploy targets in the publishing configuration. For example, you can publish to staging and live servers with different configuration.
The transformation file uses XSL syntax to allow you to replace sections and values in the config file. Here's the one I use for the FoxMobile app:
<?xml version="1.0" encoding="utf-8"?> <configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform"> <system.web> <compilation xdt:Transform="RemoveAttributes(debug)" /> </system.web> <webConnectionConfiguration> <add key="ExeFile" value="d:\Web Sites\fox\FoxMobile.exe" xdt:Transform="Replace" xdt:Locator="Match(key)" /> <add key="ServerCount" value="1" xdt:Transform="Replace" xdt:Locator="Match(key)" /> <add key="TempPath" value="d:\temp\wc\" xdt:Transform="Replace" xdt:Locator="Match(key)" /> </webConnectionConfiguration> </configuration>
A transformation file is basically a file that only has all the changes to the original. So web.config is the base file, and web.debug.config (where 'debug' is the name of the build configuration) contains all the overrides and changes specific to the live setup. This allows me to have two sets of configuration settings - one locally and on the remote site so that both sites can run.
With this in place I can now simply publish the entire site without having to worry about Web Deploy writing over my configuration file.
In the example above I only override a couple of the webconnectionConfiguration settings that are different between local and remote setup. All other settings are left alone. It's also possible to apply the Replace transform to the entire webConnectionConfiguration section by using the Replace transform without a locator. You can find much more detail on what you can do with Web.config transformations here:
Publishing Individual Files
You can also publish individual files rather than the whole site. To do this highlight one or more files in the Web project and then choose Publish Files from the context menu:
This is a quick and easy way to send up individual files to the server. Note that this option only works once you've set up a publish profile as described earlier. You don't have to publish a full project first, but you have to at least go through the Profile setup and validate steps for this option to work.
Unless Publish Web Site is too inclusive for you or you have a special need where you don't want to push everything up to the server just yet, there should be little need for individual publishing of files over publishing the project. Remember that Web Deploy is smart and only publishes stuff that has actually changed, so a site publish tends to send only a few files after the initial publish. The advantage of using a full deploy is that you don't have to keep track of what's changed - the publish feature does that for you.
What about Binaries?
So far I've only talked about the Web site content. But you can also deploy binary content in the same way.
In recent versions of Web Connection we've provided a webConnection.deploy folder which was meant for just this purpose. You can copy your executables to this folder and if you do those files get published as well. The webconnection.deploy folder should be set up just like you would set up your main application folder, but because it lives under the Web site it can be deployed all at once along with the rest of the application.
Here's what the deploy folder looks like for the Time Trakker project:
The root folder contains the executable and configuration files. Also wconnect.h is there (required for dynamic compilation) of dynamic pages.
You also optionally can add a Data folder for the first deploy to push application data in DBF files up to the server. But you'll want to remove those files from the deployment folder after the first deploy so that you don't overwrite the data captured on the server. Also be very careful if you try to run the application out of this folder locally as some files are auto-created. wwSession, wwWebRequestLog and foxUser and you don't want to end up pushing these large files to the server each time :-).
If you update the server when it's running the update will likely fail because the EXE server is actually running and the EXE file on disk can't be updated. So in order for subsequent deploys to work (only when the EXE has changed) you'll have to stop the EXE. If you're running in COM mode, or you're running the Web Connection .NET Module and EXE based servers you can temporarily stop servers using the administration page.
For standalone EXE servers make sure you have the following key set:
<webConnectionConfiguration> <add key="ExeFile" value="~\WebConnection.deploy\FoxMobile.exe" xdt:Transform="Replace" xdt:Locator="Match(key)" /> <add key="ServerCount" value="1" xdt:Transform="Replace" xdt:Locator="Match(key)" /> </webConnectionConfiguration>
This points Web Connection at where the EXE file lives and allows it to remote start and stop the server, assuming your service account has rights to start and stop processes.
In file mode use:
The process is:
- Unload File Servers on Admin page
- Run the Web Publish operation from Visual Studio
- Load File Servers on Admin page
The Unload File Servers option unloads all of the running EXE servers by killing them. After unload run the publish operation. When that's done you can hit Load File Servers to start the servers back up.
For COM operation you can click on the Hold Requests | Switch option to flip the server into ON HOLD mode:
The process is:
- Click on Hold Requests Switch to show Servers ON HOLD
- Run the Web Publish operation from Visual Studio
- Clock on Hold Requests Switch to show Servers running
Clearly, once you add executables to the mix things get a little more complicated with publishing due to FoxPro's specific needs of updating executable files. You may even have to resort to this same mechanism if you're updating only FXP/APP files as well as these files can also get locked at times.
Web Publish makes it almost too easy to publish so you'll want to decide when it's good to push a full deploy to the server. Typically you can work locally until you got everything right then push to the server.
If you do decide to deploy your EXE to the server using Web Deploy I'd recommend that you treat the webconnection.deploy folder as just that - a deployment folder with the files in that folder only changing when you actually want to deploy a new EXE, rather than building your EXE directly into this folder. You don't want to be sending up a new EXE every time your recompile even if there are no changes in the EXE, especially since Web Connection EXEs tend to be at least 1meg in size just for the base features plus your application code.
So develop your app in some other folder, debug and tweak as needed and then when the EXE is ready, copy it into the webconnection.deploy folder for publishing.
The Visual Studio Web Publish feature is very nice, especially in recent versions of Visual Studio that have made it possible to use Web Publish for Web Connection projects. It's an easy way to very quickly and effectively copy your Web projects files - and potentially your executable files to the Web server more easily. Between quick publish operations for the individual files and full project publishing, it's one of the cleanest way to deploy your applications to a live Web site that beats manual FTP deploys.