Document how to change a document

[blackorzar]

Hello, could you point out in the documentation what is the right way to deal with changes in the structure of the stored document? In particular when there is data already saved in the database. I am unsure if you need to create a new class or if there is a way to describe the new structure, etc. Thanks!

[sebastienros]

You can write a custom serializer/deserializer class with Json.NET, that would solve the issue, and also store a version number with the document that you could use to handle how to transform the document.

We could also add an event before a document is deserialized such that you could change its structure before.

[blackorzar]

I may not being understanding correctly; is the serializer/deserializer with json.net intended to be used once to adjust the entries in the Document table to the new schema, or are you talking about adjusting the structure when the document is retrieved? (The second part of your comment makes me think about this second option)

[sebastienros]

When you update your classes, the data which is already stored might be incompatible, and you might lose content. What I suggest is to create your own deserializer logic to tell Json.NET how to read the document and construct the POCO from it. Example: https://github.com/OrchardCMS/OrchardCore/blob/dev/src/OrchardCore/OrchardCore.ContentManagement.Abstractions/ContentItem.cs#L9

https://github.com/OrchardCMS/OrchardCore/blob/dev/src/OrchardCore/OrchardCore.ContentManagement.Abstractions/ContentItemConverter.cs

[blackorzar]

Sounds good. So this is called every time the document is retrieved or saved. And this is how the document is used in the session: https://github.com/OrchardCMS/OrchardCore/blob/dev/src/OrchardCore/OrchardCore.ContentManagement/DefaultContentManager.cs correct?

[sebastienros]

Yes, the conversion is transparent when using the session, that one of the values of yessql.