No more head-scratching

Lee Kah Seng

Feb 15, 2018·6 min read

Starting from Xcode8, Apple has added a new Codegen setting in the Xcode data model editor to help developer manage and maintain their NSManagedObject subclasses. The Codegen setting consist of 3 possible configurations:

• Manual/None
• Class Definition
• Category/Extension

These 3 configurations might look a bit confusing at first, and I found out that it is actually quite difficult to find a good article that explain the differences between each configuration and which one to use.

In this article I will go through each configuration and analyse the differences between each of them and I will also give some suggestion on which one you should use and how you should use it for your Core Data project. Without further ado let’s get started!

Manual/None

This is the default behaviour prior to Xcode8 where developer have to manually create and maintain the changes of the NSManagedObject subclasses.

You can try to create a sample core data project, add a new entity call TestEntity and generate NSManagedObject subclass following the step in this link.

If you follow the step correctly, Xcode will generate 2 files:

TestEntity+CoreDataClass.swift
TestEntity+CoreDataProperties.swift

After these 2 files been generated, you should be able to use TestEntity in your project. Try copy the following line of code into your app delegate, your project should compile without any error.

let _ = TestEntity(context: persistentContainer.viewContext)

Class Definition

This configuration is the default Codegen configuration when you create an entity in the data model editor. With this configuration, Xcode will automatically generate the required NSManagedObject subclass as part of the project’s derived data.

To see this in action, open the sample core data project that you created previously and delete both TestEntity+CoreDataClass.swift and TestEntity+CoreDataProperties.swift. You will notice that after both files been deleted, your project no longer able to compile. This is because you are using the Manual/None configuration for Codegen.

Now try change the Codegen configuration to Class Definition, you will notice that your project now able to compile without any error again.

To see the auto generated file, cmd + click on TestEntity, then select “Jump to Definition”.

Right click on the opened TestEntity+CoreDataClass.swift and select “Show in Finder”.

Now you should be able to see both TestEntity+CoreDataClass.swift and TestEntity+CoreDataProperties.swift (auto generated by Xcode) in the finder window. However notice that both files are not located in your Xcode project, in fact both of them are located in the “Derived Data” folder of Xcode.

You should never edit the auto generated files as they are managed by Xcode, thus they will be overwritten by Xcode every time you build your project.

Category/Extension

This configuration can be describe as in between of Class Definition and Manual/None. Xcode will only automatically generate TestEntity+CoreDataProperties.swift for you and you will have to manage and maintain TestEntity+CoreDataClass.swift yourself.

Change the Codegen configuration of your sample project to Category/Extension, you will notice that in your derived data, Xcode no longer auto generate TestEntity+CoreDataClass.swift for you, and your project is failing to compile again.

To fix the error, you can use the same method described above to request Xcode to create TestEntity+CoreDataClass.swift for your project, however Xcode will also create a copy of TestEntity+CoreDataProperties.swift for your project, thus make sure you remove it from your project to avoid it conflicting the auto generated version at the derived data folder.

Which One to Use?

Hopefully the explanation above give you a clearer picture on how each Codegen configuration works. But which one you should be using for your next core data project?

Class Definition

This configuration is good for developing simple app or during prototyping phase. You do not need to worry about updating or maintaining the NSManagedObject subclass when you edit your data model, Xcode will take care of that for you. However, you do not have any control on the NSManagedObject subclass, thus causing this configuration less flexible to use.

Category/Extension

This configuration is suitable for most of the core data app. Most of the time you do not need to do anything when you update your data model. However, you will have the flexibility to add any custom functions that you desire to the NSManagedObject subclass. Let’s take a look at the following use case:

Imagine your TestEntity have an attribute named base64 which represent the base64 encoded string of an image. By using Category/Extension configuration, you can customiseTestEntity+CoreDataClass.swift by adding a computed property named image and custom functions that helps to perform base64 encoding / decoding operation. Here’s a sample of TestEntity+CoreDataClass.swift:

To set value to base64, you just need 2 line for code:

let entity = TestEntity(context: persistentContainer.viewContext)
entity.image = UIImage(named: "sample-image")!

pretty neat isn’t it? 😃

Manual/None

Most of the time, Category/Extension configuration is good enough for your core data app. However if you are a control freak like me 😆, you can take it one step further by using Manual/None configuration. Let’s revisit the previous base64 example, and see how you can improve from there:

Since your code only accessing image of TestEntity, you should encapsulate base64 attribute by making it private. Furthermore, you can also make base64 as a non-optional attribute if you know that base64 should never be nil.

To implement this, remove base64 declaration from TestEntity+CoreDataProperties.swift and add a non-optional private base64 declaration in TestEntity+CoreDataClass.swift.

With great power come great responsibility… By using Manual/None Codegen configuration, Xcode no longer maintain the NSManagedObject subclass for you, thus you will have to update it manually every time you make changes on the data model.

Final Thoughts

If you are new to core data, you can start with Class Definition configuration. After you get familiar with core data and wanted to have more control on the NSManagedObject classes, you can always switch your project to use other Codegen configuration that suits your project needs.

Hope this article helps you to clear up your confusion on core data Codegen. If you have any comments or questions, feel free to drop it in the comment section below.

Please do not hesitate to hit the 👏 button or share this article if you like it. You can also follow me on Medium or Twitter if you want to read more article like this in future.

For those who interested, here’s my LinkedIn and Github.