Adding Swift to the Files project
This article describes how to install Swift into an existing Files project
You don't necessarily want to start with an empty Files project - like you added in the previous article. Most of the time, you want a different starting point such as DynamicWeb Swift. There are a couple of ways to get Swift, e.g.:
- Download a pre-built release from the Swift releases on GitHub
- Clone the repository
If you decide to clone the repository, you also need to build the client-side bundles that Swift uses.
We're also going to install the Swift database. This process requires that you have access to a database server that is compatible with Microsoft SQL Server 2016 or newer.
Options 1: a pre-built Swift bundle
To add an existing Swift bundle, extract the files from the bundle into the Files project. In this example, we're creating a folder structure that looks like this /MyCustomerProject.Files/Files, but if you want your folder structure to be different, feel free to change it to your liking.
We're going to download the latest Swift release package from GitHub. At the time of writing, this is 1.26.4. Since the zip file already contains the Files folder structure we want, we simply extract it into the root of the Files project. It might also be worth downloading the product demo images, but that depends on your specific use-case.
Option 2: clone from repository
If you want finer control over the Swift files, and want a way to get changes faster than they are published to the pre-built bundles, you can add Swift from the repository on GitHub. This does require more steps and tools, and is therefore a more complex procedure.
You can use either your favorite git client or the DynamicWeb CLI. They do things slightly different, so let's go over some of the important differences.
This requires the DynamicWeb CLI to be installed.
The DynamicWeb CLI is able to pull the latest Swift version directly from the GitHub repository but it does not clone. Therefore, you can use it to add Swift to your Files project without a lot of juggling. To add the latest version of Swift using the DynamicWeb CLI, run this command.
dw swift ./MyCustomerProject.Files/Swift
The reason we put the files in a folder called Swift instead of Files - as we do in other examples - is because this approach not only adds the files Swift needs to run, but also the config files and build scripts needed to build Swift. Therefore, it's recommended to label it as such to avoid confusion.
The final path to the actual Files folder will look like this /MyCustomerProject.Files/Swift/Swift/Files.
Note
Using the DynamicWeb CLI, you get the latest released version, not the main branch. To get that instead, use the flag -n or --nightly.
dw swift --nightly ./MyCustomerProject.Files/Swift
Read more about getting Swift using the CLI.
Building Swift
No matter if you chose to use the DynamicWeb CLI or git, the client-side bundles for Swift need to be built. To that end, make sure that NodeJS and NPM are installed.
npm install
npm run build:webpack
Finally, we need to copy the Files folder to the Files project:
Copy-Item -Recurse "./Swift/Swift/Files" "./MyCustomerProject/MyCustomerProject.Files/Files"
Note
If you added Swift using the DynamicWeb CLI directly into your Files project as suggested above, this step is redundant and you can skip it.
Installing the database
Once all relevant files have been extracted or copied, we need to install the Swift database.
Download the latest database that matches the version of Swift downloaded in the previous step. Refer to the guide on the Swift repository or the Swift downloads section to find the latest database. Extract the zip file to a temporary location and ensure the Swift.bacpac file was extracted correctly. On Windows, you may need to unblock the zip file before extracting the database.
As with creating the project structure, we're going to use the dotnet CLI to install the database, but first we need to make sure we have the necessary .NET tool installed. The tool we need is called SqlPackage and is provided by Microsoft.
Let's install it:
dotnet tool install -g microsoft.sqlpackage
The tool enables us to interact with a SQL Server instance from the terminal.
In this example, it's assumed the database server is running locally. If that's not the case for you, modify the following command to fit your scenario.
SqlPackage /Action:Import /SourceFile:"Swift.bacpac" /TargetServerName:"localhost" /TargetUser:"[YOURUSER]" /TargetPassword:"[YOURPASSWORD]" /TargetDatabaseName:"Swift" /TargetTrustServerCertificate:True
It's recommended to create a Globalsettings.Database.config in the root of the Files folder. This is because Swift doesn't ship with separate database config file. Refer to th setup guide for installing Swift for testing for more information.
Warning
To install the database, you need a user account with access and modify permissions. This is not discussed further in this article, but be aware that the import might fail silently if the correct permissions are not present.
Using Swift
Once all files have been copied and the database is installed, we need to set up the solution to use Swift. Again, there are different ways to do that depending on your preferences, but the simplest way to get the solution to use our newly installed Swift files and database is to start the solution and follow the setup guide.
You need to make sure to select the option to use an existing Files folder. This path can be relative to the Host application, so it is completely valid to specify a path like ../MyCustomerProject.Files/Swift/Swift/Files. You should also point to the database we just installed.
The installer will then create a file called appsettings.Development.json in the Host project that points to the Files folder inside in the Files project.
Updating Swift
Updating Swift files is a simple process if the guidelines for customizing Swift are followed. Simply repeat the process used to add the files in the first place.
Note
If the DynamicWeb CLI was used to install Swift, subsequent updates must use the --force flag to overwrite existing files locally.
It's a different story with the database. Generally, it's not recommended to update the database of a running solution, rather it's necessary to manually (re)create new or updated features.
Next steps
If you're collaborating on a DynamicWeb customer project, it might be relevant to read about working in teams. It may also be useful to review recommendations for setting up CI/CD pipelines for deployment.