New for RC0 – the .layout file

  • Article

If you look at my previous post on the tabular project structure, you’ll see this teaser: “There are a couple of other files in the project folder, an optional ABF file and a hidden user settings file, but I’ll talk about those another day.” The ABF file description I just put off because it was complicated, but I finally got around to describing the ABF file. The user settings file I put off deliberately because I knew we were going to change the design for RC0. Now the design is done, I can tell you about it.

The user settings file

First, the user settings file. When I refer to the user settings file, I am referring to the hidden file called “Model.bim_<username>.settings”. For RC0 models, this file is very small. It does a few things. This file is created whenever a project (new or existing) is opened for the first time by this user. The file stores personal settings such as the workspace database name, the workspace database retention policy, and the back up policy. Also, it stores a bit of metadata that is used to populate the error list on open as needed. This is all private, per-user data that you should not be mucking about with and also not sharing with other users. It is OK to delete this file if you want to force usage of the ABF (as described in my previous article), but you should not ever modify this file nor check it into source control.

The .layout file

Now, the Model.bim.layout file. We created this new file for RC0 to solve a specific problem. The problem is with persistence of view state information. We save out a lot of view state information for tabular models. Some of this view state information is something that you would want to share with other developers in a shared development environment. The position of measures in the measure grid and the position of tables and connectors in the diagram are two such examples. If you have ever rearranged a complicated diagram, you know how much work this takes and you would want to share your hard work with others!

We did not want to save this information in the .bim file. The reason – developers have a hard enough time trying to figure out what changed in the model between iterations without adding the view state information. Last thing you need is to force a change to the .bim file whenever you move something with your mouse in the table. It becomes very difficult very quickly to differentiate real changes (such as add/remove of measures, tables, columns, etc) vs simply cosmetic changes. What to do?

Thus, the .layout file is born. It stores all the view state information. This new .layout file is very smart. Triggering a view state change (such as moving a table in the diagram) shows the dirty flag on the .bim file, even though the .bim file itself is not dirty. This enables VS to prompt for save on close, so you never lose your view state changes (unless you close without saving). The .layout file is renamed automatically when the Model.bim file is renamed. Should the .layout file ever disappear, don’t worry. All the model metadata is safe. Only view state information is lost, and models can still be opened and edited without issue. Also, stale information in the .layout file (anything not matching model metadata) is simply ignored. We tested this pretty thoroughly and it works pretty well.

Behind the design of the .layout file

You might wonder where we had this view state information before RC0, as it wasn’t in the bim file. Previously, it was in the user settings file. That approach was problematic because the user settings file cannot be shared in a source control environment. The designer ensures that you only use the user settings file with your name on it. The .layout file is much better because it can be shared.

You might also wonder why, if this information in the .layout file is so important, the .layout file isn’t added by default to the .smproj. This is a cut we had to make due to time constraints. Getting the Solution Explorer to work with your custom project types is actually quite tricky and time consuming, so we took a shortcut there. Another shortcut that we made was that we just put all the view state information into the .layout file, which includes personal information such as sheet tab selection, diagram vs. grid view selection, filter selection, etc. So if you choose to share the .layout file, you are sharing all non-metadata things that each user can see. This is not ideal, but it beats the alternative of not being able to share anything at all.

Sharing the .layout file

If you are in a source control environment and you want to share the diagram and measure grid settings, here is what you do:

  1. Create a new project or open an existing project.
  2. Open the Solution Explorer. Right click the .smproj, select Add->Existing item.
  3. Select the Model.bim.layout file (in the same folder as the .bim file you are currently using), OK.
  4. Add the Model.bim.layout file to source control and check it in.

Obviously, sharing is optional. If you don’t want developers to be dirtying your project by switching back and forth between diagram and grid view, don’t share the file. However, I do highly recommend sharing out the layout settings as setting up the diagram is time consuming and there is no point in making every developer do it manually.

Wrap-up – the final file structure

With this, we can now summarize the final project structure for tabular models. You have a parent .smproj project file, with a single child .bim file that contains model metadata. To this project, you can optionally add the .bim.layout file to the project/source control that contains view state information.

We have a couple of auxiliary files in the project folder that help the designer know how to load data. These are the Model.bim_<username>.settings file and the ABF backup of the project.

When you build the project, you get three outputs – the .asdatabase file, the .deploymentoptions file, and the .deploymenttargets file. These build outputs are designed to be used by the Deployment Wizard, but can be used by anybody that wants to deploy the project using any method (AMO/PowerShell/executing XMLA in SSMS).

Eight files – that’s all you need to build and deploy your tabular project, with only two files (the .smproj and .bim) that are absolutely essential to manage. Pretty simple.