Linking to Core files - official instructions don't work and Xamarin Studio alpha bugs

tcabtcab Andy BulkaUSMember

Given that one of the main points of Xamarin is to be able to link to a cross platform core, I'm finding some conceptual explanatory holes in the idea of linking core files into a project using technique 1. File Linking into each App Project, not to mention some buggy behaviour in this area within Xamarin Studio 4.1.11 alpha. (Since adding files is, unbelievably, actually broken in stable Xamarin Studio as of Sep 17th 2013).

Let's assume that the 'Core' source folder is a physical file system sibling of the iOS (or whatever) project, but not known by the solution. The solution would contain perhaps one, two or three projects wanting to use that Core.

Do I really need to create an empty folder e.g. 'Core' inside my iOS project which has the same name as the e.g. 'Core' root folder containing the files I'm linking to? The official instruction screenshot seems to say that I need to, but...

Alternative method: Interestingly, I seem to be able to right click on project, Add/Add existing Folder... and select the root folder e.g. 'Core' of the folder I'm trying to link to, select 'link' when asked, and the iOS project gets the proper Core folder structure created in the project. Not physically, just in the iOS project. This works.

The CONTRADICTS the advice which suggests (I think) that you physically have to create a folder in your iOS project with the same name as the source Core folder you are linking files out of. Look at the annotations on screenshot in the advice. The example given is Tasky.Core. And the article further suggests that you link files in one by one (using right click on project, Add/Add Files...) - but following this advice results in files being added flat inside your iOS (or whatever) project instead of being nested inside the proper Core folder structure.

In fact, the only time that the nested folder structure is created during a (right click on project, Add/Add Files...) link operation is if the source file is coming from a folder that is physically INSIDE your iOS project. Yet the Xamarin doco talks about putting the Core common code in a sibling folder to your iOS project. If you do that, and link in the files, they come in flat, not inside a Core folder structure. Try it.

To make matters worse Xamarin Studio has bugs in this area. Linking files into your project works, but referring to namespaces defined in those files is a hit and miss affair. Sometimes it works, sometimes the "using namespace_abcd" goes red and Xamarin Studio can't find the namespace even though the file is there and linked into the project. A complete reboot of Xamarin Studio clears the problem. I tried this on a couple of macs, lion and mountain lion, stable Xamarin and alpha.

  • Can anyone please step me through the process of linking in a core directory structure?
  • Can anyone explain why the official instructions don't seem to work, and why my alternative method does?
  • Can anyone confirm the bugs that I am having in Xamarin Studio re namespaces in linked files sometimes not being seen and a Xamarin Studio quit and restart being needed?


  • tcabtcab Andy Bulka USMember

    I have successfully been able to link in core folders and now better understand how to link a core set of files into multiple Xamarin projects.

    The problems I was having were a combination of

    • there being multiple techniques which achieved the same result, with
    • some techniques involving the idea of empty directories and other techniques not doing so.
    • there were (are) some Xamarin Studio bugs which made it appear that my linking wasn't working, but in fact my linking was working and all it required was a reboot of Xamarin Studio to see that (bug described later).

    So in the interests of perhaps helping others and clarifying the situation, here is a step by step tutorial of how to link core files into multiple projects, using the linking technique.


    How to link a core folder of files into your project:

    Preliminary setup.

    Step 1: Create a New Xamarin Project - iPhone / Single View Application “unify3”

    Step 2: Add a directory “core” as a sibling folder to the unify3 project containing a file called “mylib1.cs”, all created outside of Xamarin Studio. Thus this core directory is not currently visible by the Xamarin Studio solution. So the directory structure looks like:

      /unify3     <- default project
      unify3.sln   <- solution file
      /core     <- shared core that I want to link in, incl. this core folder

    Given the above directory structure is in place, and you are in Xamarin Studio, and your aim is to link in a core common folder of functionality into your project then:

    Technique 1:

    • Create a new folder “core” in your project by right clicking on your project in Xamarin solution view and selecting Add/New Folder. This will also create a physical folder.
    • Right click on that folder and
    • Add/Add files…
    • choose the core file “mylib1.cs”
    • select 'link' when asked,
      The linked file will appear inside the folder you just created in solution view, but of course will not be present on disk.

    This technique probably accounts for the official instructions mentioning “empty folders” as indeed, we have just created an empty folder “core” in our project.

    Adding any file using linking will add that file to the solution underneath the folder or project node that you right clicked on when you selected the Add/Add files… command.

    The only benefit that I can see of actually creating the physical folder “core” in your own project is that you could call it something different, ie. not “core” but e.g. “mycorestuff”. Of course the files that are linked into the solution do retain their original names.

    Technique 2:

    • Do not create a new physical folder “core” in your project, simply
    • right click on your project,
    • Add/Add existing Folder... and
    • select the root folder you want to refer to e.g. 'core',
    • select 'link' when asked,
      and the iOS project gets the proper core folder structure created in the project. Not physically, just in the iOS project.

    This is the technique that I originally stumbled on and which did not produce any empty physical folders called “core” in my projects. So the benefit is just that - it doesn't involve the existence of potentially confusing empty folders in your projects, and seems to me to be the technique of choice. Arguably the official instructions should be updated to reflect this technique.

    Note that when using Add/Add existing Folder… and linking, you can choose the folder “core” or just the file “mylib1.cs” or both (there are checkboxes offered in the interface). No matter what you choose, the proper folder structure is created in the solution, which is a good thing especially if you are linking to a more complex folder structures involving BL and DAL subfolders etc.

    Also, when using this technique, no physical files or folders are created inside your projects, which I think is a good thing.

    Warning: After doing any linking using the techniques above, you will probably want to resist referring to core namespaces etc. till you reboot Xamarin Studio. See bug below:


    Steps to reproduce.

    Step 1. New Xamarin Project - iPhone / Single View Application “unify3”

    Which results in:

      /unify3     <- default project

    Step 2. Outside of Xamarin, add a directory “core” as a sibling to the unify3 project. Put a file in there called “mylib1.cs” containing


    using System;
    namespace core {
      class MyLib1 {}

    so that the directory structure now looks like

      /unify3     <- default project
      /core     <- shared core

    Step 3. Within Xamarin, right click the unify3 project and select Add/Add files… and select the mylib1.cs file within the core directory. Answer “Add a link to the file” when asked.

    The linked file appears flat, with no parent directory core. This is ok, as we are only reproducing the bug here. If you want your file to appear inside the proper core folder structures - see my tutorial above.

    To reproduce the linking referencing errors: Edit any .cs file in the unify3 project and type in “using” at the top, code completion offers the “core” namespace as an option - which is good. But you won’t be so lucky in additional projects that reference core. So just create another project within the same solution and link in that file again viz:

    Step 4. Right click on solution, select new project, iOS single view application, call it “unify3A”. This is going to be the second project referencing core.

    Step 5. Right click the new unify3A project and select Add/Add files… and select the mylib1.cs file within the core directory. Answer “Add a link to the file” when asked. (just as before)

    Step 6. Now Edit any .cs file in the newly added project and type in “using” at the top, code completion may not offer the “core” namespace as an option. Type it in anyway. It appears red and won’t compile of course. If the core namespace IS offered to you by code completion, then repeat steps 4-6 with a new project within this solution until it fails, which it always will on the 3rd project.

    Expected behaviour: The linked file’s namespace should be offered by code completion.
    What I see: Code completion doesn’t always list the “core” namespace in all my projects, even though the file is linked in.

    Remember, if you do see the core namespace, then the bug is being elusive (Xamarin Alpha 4.1.11 (build 10) as of Sep 23rd 2013. Simply create yet another project within the solution and repeat steps 4-6 till it fails. It always fails for me on the 3rd project, sometimes on the 2nd.

    Step 7. Quit and restart Xamarin and try code completion where it wasn’t working before. It now works and offers the “core” namespace correctly.

Sign In or Register to comment.