Contacts Server with File System Back-end Example, C#
CardDAVServer.NtfsStorage is a contacts server example that runs on IIS or IIS Express. It is validating user credentials against Windows Active Directory or local Windows accounts and can be configured to use Basic, Digest or Integrated Windows Authentication. All contacts data is stored in the NTFS file system.
This sample stores vCard data in the format submitted by the client application as a plain text stream inside a file. When iOS / OS X client requests a contact data, the vCard is converted to the format understood by Apple contacts, including conversion of e-mails, telephones, URLs, addresses, instant messengers, etc. and its labes.
If the contacts file is created by Apple client and contains non-standard properties and parameters, the vCard is converted into standard vCard format when output is generated, so its content could be corresctly interpreted and displayed by the non-Apple CardDAV client.
To run this example you will need:
ASP.NET 4.5 on Windows Server 2012, Windows Server 2008, Windows 10, Windows 8, Windows 7 or Windows Vista.
NTFS file system.
For simplicity of evaluation Visual Studio 2013 or Visual Studio 2012 are recommended. This sample does not support Visual Studio 2010.
Important! Because this sample uses TAP interfaces you need .NET 4.5 or later to run it. If you need to support .NET 4.0 or 3.5 use the 'ASP.NET CalDAV/CardDAV Server Application' wizard or other WebDAV wizards in Visual Studio and select .NET 4.0 or .NET 3.5 in a New Project dialog.
Installation and Configuration
By default contacts server with file system back-end example is installed to C:\Users\<UserName>\Documents\IT Hit\WebDAV Server Engine\vX.X.X\Samples\CardDAVServer.NtfsStorage\ folder.
Setting the License
To run the example, you will need a valid IT Hit WebDAV Server Engine License. You can download the license here. Note that the Engine is fully functional with a trial license and does not have any limitations. The trial license is valid for one month and the engine will stop working after this. You can check the expiration date inside the license file.
Place the license file in the root folder of the contacts server cxample (\Samples\CardDAVServer.NtfsStorage\).
The files are stored in the file system in \Samples\CardDAVServer.NtfsStorage\App_Data\WebDav\Storage\ folder. You can change the storage location in RepositoryPath tag in web.config.
Running the Sample from Visual Studio
If you have Visual Studio, the simplest way to run the sample is to run it from Visual Studio. In this case, you do not need to configure the web application in IIS.
Run the Visual Studio with Administrative privileges (required for IIS Express impersonation, see below) and open the project. In the project properties, you will see that this sample is configured to use Windows authentication:
Run the project from Visual Studio. The web browser will be opened and request for authentication. You will provide your Windows account credentials:
This example stores address books as folders in the file system. During first login, the ProvisioningModule will create several address books for the loged-in user. It will also grant the logged-in user permissions in the file system to access user home folder. The sample server will display the path to each address book on a default page that is shown when accessing any folder on a server:
To find out how to connect to your contacts server from various CardDAV clients see: Connecting to Your CardDAV Server article.
To examine your repository click on “Examine your server content with IT Hit Ajax Browser” link:
Note that to be able to see the above folder structure, the user that you used to log-in to the website must have List Folder Contents permissions in your \Samples\CardDavServer.NtfsStorage\App_Data\Repository\ folder.
On the above screenshot, you can see the several .vcf files. Each file represents a vCard contact while the folder itself represent an address book. These files were created by the CardDAV client, you would not find them before you connect with a client application and create contacts.
Note that ACL folder and its content is not present in the file system, it comes from your Active directory or local Windows accounts.
To create initial address books as well as for other file system operations this sample is using impersonation. In case you run your project in IIS Express and log-in to your web application as the user that is different from the one running Visual Studio (and IIS Express) the impersonation will fail. If after the log-in you get the error, consider the following:
- The account under which your application is running does not have enough permissions to impersonate the logged-in user. Usually, this is because you are running your application in IIS Express and Visual Studio is started with non-administrative privileges. Restart Visual Studio as Administrator.
- Your web application does not have enough permissions in the file system to create the required folders, access web.config file or grant permissions on the file system folder for the logged-in user during the first login. In case, your application is running in IIS read ‘Deploying Your Contacts Server to IIS’ section and make sure the user has enough permissions in the file system.
Access Control List
This sample provides ACL implementation that is mapped to Windows accounts. User credentials will be validated against Active Directory or local Windows accounts. Below you can see ACL users and groups mapped to Windows accounts:
These sample contains a broad ACL implementation that is not required in many cases. You can truncate ACL implementation removing functions for manipulating users and groups leaving a read-only implementation of truncated browsing functions.
Deploying Your Contacts Server to IIS
Follow the steps below to deploy the contacts server sample to IIS 7 and later:
Configure a new website in IIS as described in Configuring Your WebDAV Website in IIS article.
Give Full Control permissions to the identity under which your web application is running in \Samples\CardDavServer.NtfsStorage\App_Data\WebDAV\Repository\ folder. In case you have set up ApplicationPoolIdentity in step 1 and named your pool DavAppPool, give Full Control permissions to IIS APPPOOL\DavAppPool account:
When user accesses your contacts server for the first time, the ProvisioningModule will create initial address books in file system and grant permissions to the logged-in user on his home folder in file system.
Configure Windows Authentication as described in Configuring Windows Authentication article.
Optionally, to be able to connect with iOS Contacts applications faster on iPhone and iPad, configure SSL with a self-signed certificate on default SSL port 443, as described in Configuring SSL on your WebDAV Server Running in IIS.
- Configuring Your WebDAV Server in IIS
- Configuring WebDAV Server Windows Authentication
- How to Connect to CardDAV Server
- WebDAV Server Samples Problems and Troubleshooting