Please document the change to when EF traverses a graph and TrackGraph.

[sam-wheat]

This post mentions:

...if you want to set the state of a single entity then context.Entry(myEntity).State = EntityState.Added is probably the easiest. >>TrackGraph will work... but that is really designed for iterating over a graph of entities and setting the state for each one.

...EF Core is now ok with having tracked entities reference entities that are not tracked.

The above is the most wonderful thing ever to happen to EF surely it is worth mentioning here.

Also worthy of mention is TrackGraph.

Given the above changes it is unfortunate that the Add() api was not synchronized to reflect them.
I am two years too late to comment on this but perhaps in some future version of EF core it will be fixed:

var blog = null;
using (var context = new BloggingContext())
{
   blog = context.Blogs.First();
}

using (var context = new BloggingContext())
{
	var post = new Post {Title = "Hello World", BlogID = blog.ID, Blog = blog };
	context.Posts.Add(post);
	context.SaveChanges();  // Exception!!!
}

Here we are newing up a context, newing up an entity, and adding that specific entity to a specific dbset in the context. Yet our add fails due to a PK conflict that relates to an entity that our dbcontext should know nothing about! I don't want to sound critical but that api is really unintuitive. Having it come up for consideration in the above referenced link and not be changed is very sad.

Even more baffling and ironic is that the syntax that should traverse the graph does not:

db.Entry(post).State = EntityState.Added;

Here we are adding the entity to the context versus a specific DBSet/table. In my mind this syntax is much more liberal and gives the context freedom to traverse the graph and add as necessary.

[ajcvickers]

@sam-wheat Are you asking that we document more clearly that Add adds a graph of entities, while setting the state of an entity only changes the state of that single entity?

[sam-wheat]

Are you asking that we document more clearly that Add adds a graph of entities,

No that is quite clear.

while setting the state of an entity only changes the state of that single entity?

This is not mentioned (perhaps I missed it) and is invaluable. I will add it is especially important for guys like me who are coming over from EF 6 and don't know about the change. So glad I discovered it, it solves so many problems for me.