[DOCS-16354] Realm .NET SDK docs typos/inconsistency reported by customer. Created: 30/Aug/23  Updated: 13/Sep/23  Resolved: 13/Sep/23

Status: Closed
Project: Documentation
Component/s: Realm
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major - P3
Reporter: Mark Brown Assignee: Caleb Thompson
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Participants:
Days since reply: 21 weeks, 6 days ago

 Description   

From a customer at Husqvarna who is trying out Realm and Atlas Device Sync, some document typos/inconsistency:



 Comments   
Comment by Caleb Thompson [ 07/Sep/23 ]

https://github.com/mongodb/docs-realm/pull/3004

Comment by Caleb Thompson [ 07/Sep/23 ]

Thanks again, mark.brown@mongodb.com! Here's the PR: https://github.com/mongodb/docs-realm/pull/3004

 

Comment by Mark Brown [ 06/Sep/23 ]

Some more doc feedback; the examples on this page should probably use interfaced (e.g. IRealmObject) instead of the older base classes:
https://www.mongodb.com/docs/realm/sdk/dotnet/model-data/relationships/#relationships---.net-sdk

And the example for "See the following example for how to query a one-to-many relationship:" on the same page does not provide a one-to-many query, it just shows a filter on a collection.

I am nitpicking stuff but usually these things are only visible during an initial read-through so I take the chance to mention the things I find, do with it what you like.

Comment by Mark Brown [ 06/Sep/23 ]

Another:
https://www.mongodb.com/docs/realm/sdk/dotnet/model-data/relationships/#inverse-relationship
In this example, note that: * The Task object's Assignee property is a User object.

  • The User object's Tasks property inverts the relationship and refers to all Task objects that contain this specific User in their Assignee property.
  • This, then, allows us to query the Task collection to get all Tasks assigned to a specific User.

Should be (Task -> Item etc.):In this example, note that: * The Item object's Assignee property is a User object.

  • The User object's Items property inverts the relationship and refers to all Item objects that contain this specific User in their Assignee property.
  • This, then, allows us to query the Item collection to get all Items assigned to a specific User.
Comment by Mark Brown [ 06/Sep/23 ]

More customer comments:

Small document improvement here:
https://www.mongodb.com/docs/realm/sdk/dotnet/model-data/data-types/embedded-objects/#realm-object-models

"To define an embedded object, derive a class from EmbeddedObject. Use the syntax "<YourClass> : EmbeddedObject {}{}" to accomplish this."

Should probably be (use interface instead of deprecated base class):

"To define an embedded object, derive a class from IEmbeddedObject. Use the syntax "<YourClass> : IEmbeddedObject {}{}" to accomplish this."

Comment by Mark Brown [ 30/Aug/23 ]

More Feedback:
 
The documentation for App creation/connection is a bit misleading, it shows setting {{LogLevel }}(even though it is commented out) that is, I assume, deprecated since a while back. It is not available in the SDK or in the detailed API documentation at least.
https://www.mongodb.com/docs/realm/sdk/dotnet/app-services/connect-to-app-services-backend/#configuration
 
Not available here either:
https://www.mongodb.com/docs/realm-sdks/dotnet/latest/reference/Realms.Sync.AppConfiguration.html
 
 

Comment by Mark Brown [ 30/Aug/23 ]

And some kudos as well! –

I really like the documentation though! And the .NET SDK. It is evident a lot of effort has been put into this - making complex tech and concepts appear fairly simple is not easy 

Comment by Mark Brown [ 30/Aug/23 ]

More:

The same goes for the snippet here:
https://www.mongodb.com/docs/realm/sdk/dotnet/crud/write-transactions/#check-the-status-of-a-transaction

Comment by Mark Brown [ 30/Aug/23 ]

And further customer comments:
Also - that original code snippet does not explicitly dispose the transaction in case the write goes successfully, possibly leading to some form of resource leak, it only dispose of it in the {{catch }}statement. I may be completely off here of course.
Proposal:

// Open a thread-safe transaction.
using var transaction = realm.BeginWrite();
// At this point, the TransactionState is "Running":
// transaction.State == TransactionState.Running
try
{
// Perform a write op...
realm.Add(myDog);
// Do other work that needs to be included in
// this transaction
if (transaction.State == TransactionState.Running)
{ transaction.Commit(); }
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
// Something went wrong; roll back the transaction
if (transaction.State != TransactionState.RolledBack &&
transaction.State != TransactionState.Committed)
{ transaction.Rollback(); }
}

 

Comment by Mark Brown [ 30/Aug/23 ]

Further customer comments:

Another possible improvement for .NET docs, I think the docs regarding (explicit) transactions here could benefit from adding a using }}statement to {{realm.BeginWrite(); in order to not risking it not being disposed (in case of some untimely exception) and to not have to explicitly call transaction.Dispose() in the {{catch }}statement (in the original code).
https://www.mongodb.com/docs/realm/sdk/dotnet/crud/write-transactions/#initiate-a-transaction

Generated at Thu Feb 08 08:15:12 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.