The most typical, and most robust, deployment of the EntityServer is with Internet Information Services (IIS).
Hosting the EntityServer WCF services in IIS has several benefits:
The EntityServer can be hosted on any version of IIS from 7 forward. You'll generally use the IIS Manager (available from Control Panel | Administrative Tools to manage your application.
Setup follows the same steps you would take for any IIS application. The only DevForce-specific requirements are:
It's usually easiest to use the Visual Studio Package/Publish features to create a deployment package and deploy your web application to an IIS server supporting web deployment. We have a walk through with more information and resources.
If you want to do a manual setup, here are the steps (shown in Internet Information Services Manager for IIS 7.5):
Be sure to use an application pool which supports ASP.NET 4.5 and the integrated pipeline mode. Note that the "v4.0" framework version will equate to .NET 4.5 if it is installed.
To add a new application, right click the Default Web Site and choose Add Application. Here we're creating the "BadGolf" application using the DefaultAppPool.
If your IIS application will also host the Silverlight application you need to take a few additional steps.
XML | <compilation debug="false"> |
XML | <system.web> <httpRuntime targetFramework="4.5" /> </system.web> |
Now it's time to discuss what to put in the folders you've created for the IIS application.
The following assemblies are always required:
IdeaBlade.Core.dll
IdeaBlade.EntityModel.dll
IdeaBlade.EntityModel.Edm.dll (version 7.2.2 and later: IdeaBlade.EntityModel.Edm.EF5.dll or IdeaBlade.EntityModel.Edm.EF6.dll)
IdeaBlade.EntityModel.Server.dll
IdeaBlade.EntityModel.Web.dll
IdeaBlade.Linq.dll
IdeaBlade.Validation.dll
You'll also need the .config file:
web.config
Optional but strongly encouraged:
global.asax
Optional (and deprecated):
EntityService.svc
EntityServer.svc
If you're deploying a Code First model, you'll also need the following:
EntityFramework.dll
IdeaBlade.Aop.dll
PostSharp.dll
You'll of course also need all of your own "server-side" assemblies. These are the assemblies holding your entity model(s), and any custom extensions you've implemented.
All assemblies should be placed in the bin folder. You may place the DevForce assemblies in the GAC, although there's generally no compelling reason to do so, unless you have a large number of DevForce applications installed and they are all using the same DevForce version.
All other files listed above should be placed in the application root folder.
You do not need to, and in most cases should not, install DevForce to the target machine. Runtime license information is found in your model assembly and not the registry.
All configuration information will be in the web.config.
You'll usually need the <connectionStrings> for any databases your application uses. (You can also use <edmKeys> instead of or in addition to connectionStrings, but they may be deprecated in the future.)
Remember the credential information in the connection string: if you include a userid and password you may want to think about encrypting the connection strings section if the server cannot be secured. If you use Windows integrated security for your database connections, the account used to access the database will be the application pool identity, which if you aren't using a custom application pool will be DefaultAppPool. In this case, using a custom application pool and identity with only the system and database privileges is a good option. See the security topic for additional information on securing the database.
If you are using a SQL Server Express database (for ASP.NET security for example), consider instead deploying the database to a standard SQL Server instance for improved security.
If you are using a custom DataSourceKeyResolver to dynamically provide connection information, you will not need to define connection information in the config file.
You can use the <logging> element to set the file name and location of the debug log, or to turn logging off altogether. You also might want to archive log files. Generally other logging attributes are not needed, or used only for debugging purposes.
A typical config file might contain the following logging information:
XML | <logging logFile="log\MyAppDebugLog.xml" archiveLogs="true" /> |
... to create a file named MyAppDebugLog.xml in the log folder and archive files automatically.
Remember in the IIS Setup above we discussed the special access requirements of the log. In IIS, unless you restrict access, anyone can browse to your debuglog file and discover much more about your application than you probably want to share. To see if your debug log is browsable, just point your internet browser to it - for example http://localhost/badgolf/log/myappdebuglog.xml.
One final note: do not put the log file in the bin folder. Doing so will cause your assemblies to be repeatedly recompiled.
Also see the Log and Secure topics for more information.
Unlike other EntityServer deployments, the service, port and URL information on the <objectServer> element are not used when hosting in IIS. This is because your IIS application configuration has already determined the base address(es) to use.
If you've modified any of the defaults for the <serverSettings> element, such as the allowAnonymousLogin or loginManagerRequired settings, you'll also need to include that information here. If you're using ASP.NET Security you'll need to include the appropriate configuration information too.
As an example, your <objectServer> element might have something like the following when using ASP.NET security and load balancing is required:
XML | <objectServer> <serverSettings allowAnonymousLogin="false" loginManagerRequired="true" sessionEncryptionKey="mysecretkeyhere" useAspNetSecurityServices="true" /> </objectServer> |
A note on load balancing: load balancing is only supported with the Data Center Enterprise license. You must use the same non-blank value for the sessionEncryptionKey on every load-balanced EntityServer hosting the application. The key you use is up to you, but remember that it functions like a password. If you're planning an Azure deployment with multiple instances you'll need to set the sessionEncryptionKey.
The <clientSettings> apply only to the client application.
As with any DevForce server or client, you can use a WCF <system.serviceModel> section to configure communications. See the samples for more information.
Global.asax
You'll usually include a Global.asax in your application folder. The default generated for you with the Visual Studio templates registers a "virtual path provider" in the application start logic. What this does is remove the need for you to provide *.svc files for the various EntityServer services. The provider instead creates in-memory files on demand.
You can also use the start logic for other actions:
.svc files
You'll notice in the file list above that we called the various *.svc files, such as EntityService.svc and EntityServer.svc optional. These files, when present, control the activation of the WCF services comprising the EntityServer. If you've registered the virtual path provider in the Global.asax as discussed above, then there's no need to have physical files present, as the provider will create them virtually on demand.
If you don't wish to use the provider or you have customized service activation, then you can still use the .svc files. You will need a single EntityService.svc file, and one file for each EntityServer instance your application will use. If you are using either a data source extension or custom composition context when you create the EntityManager in your client application, then it will communicate with a specific EntityServer service having those same characteristics. For example, if you're using a tenant extension of "ABC", you'll need a file named EntityServer_ABC.svc. The file contents will also need to be customized: see the samples for more information.
IIS troubleshooting information can be found in the Troubleshooting IIS topic.