add auth page with code snippets

[MongoCaleb]

Pull Request Info

Issue JIRA link:

https://jira.mongodb.org/browse/DOCSP-12591

Docs staging link (requires sign-in on MongoDB Corp SSO):

https://docs-mongodbcom-staging.corp.mongodb.com/realm/docsworker-xlarge/12591/dotnet/authenticate.html

[nirinchev]

Some wording comments + code snippet suggestions. None of these are "must fix" or anything, so if you don't agree, feel free to disregard.

[nirinchev]

Not sure if that's the style of the docs, but I feel that using the fully qualified name is overly verbose and doesn't convey much useful information. It's also not very copy-pasteable as in my experience most projects use vars for variables and a few use the type name (without the namespace).

[MongoCaleb]

@nirinchev - the reason I had the FQDN here was because we have a user-defined class called "User", so the compiler complained. I've updated the custom class names because they are semi-arbitrary.

[nirinchev]

My suggestion would be to always use var as the variable name should be indicative enough. E.g. anonUser is obviously a User, so explicitly specifying the type is redundant. This also lets you avoid some of the type collisions.

[nirinchev]

The .NET method is LogInAsync - I don't think anyone would get confused over it, but it's always better to use the exact method names.

"to authenticate a user and create a User object" sounds a bit repetitive. Additionally, the "create a User" wording is a bit imprecise as it implies constructing the instance as opposed to obtaining a reference to it by calling a method. Don't have suggestions for avoiding the repetition, but "create a User object" can probably be reworded as "obtain a User instance".

[nirinchev]

This sounds a bit heavy - perhaps if we inverted the flow, it would be easier to follow. I.e. something like "The Credentials class exposes factory methods for each authentication provider."

[nirinchev]

Would be nice if those linked to the API docs for that method as those typically contain valuable information about parameters, return types, etc.

I can send you a .zip containing the API docs for the v10 SDK if that would help.

[MongoCaleb]

Yes, please...or a link would be fine, too.

[nirinchev]

This will work, but the code can be simplified by using anonymous objects:

var functionParameters = new
{
    username = "caleb",
    password = "shhhItsASektrit",
    someOtherProperty = "cheesecake"
};
var functionUser = await app.LogInAsync(Credentials.Function(functionParameters));

Note that when using the anonymous object syntax, you can also hint that properties don't have to be strings only. Any serializable .NET type, including embedded objects will work:

var functionParameters = new
{
    biometricsValidated = false,
    todaysDate = DateTime.UtcNow
}

Of course, don't have to go overboard with the extra properties, just FYI.

[MongoCaleb]

niiiiice

[nirinchev]

I think we're calling this google auth code now as using the access token flow doesn't work.

[nirinchev]

FYI: this message will change when you upgrade to the latest v10 package - the generic wording was due to a bug that has now been addressed and the message should be more meaningful (I don't think that's exposed in the docs, but will break your test, so don't be surprised).

[nirinchev]

Probably move realm to a class-level variable as well to avoid the Realm realm = await Realm... repetition.

[MongoCaleb]

Since these code snippets live "alone" within the docs, and the user won't be seeing this unit test file as a whole, I think it's useful to have the Realm there to be clear what we are building.

[nirinchev]

Right, but it's in the variable name as well - i.e. knowing that I have a variable called realm of type Realm isn't that much more useful than just knowing that I have a variable called realm.

[nirinchev]

Same here - RealmTask testTask = new RealmTask is fairly repetitive. Also, you can drop the () from the constructor when using the property initializer syntax - there are different opinions about it, but most high profile .NET people seem to omit them.

[nirinchev]

We shouldn't encourage people to .ToList() query results as that removes the "liveness" from the collection.

[nirinchev]

Same here - materializing the collection is generally viewed as a bad practice unless you have very specific needs. Instead, you should operate on the query as much as possible.

[nirinchev]

Hahaha... I guess explains the password 😅

[MongoCaleb]

Can you tell I was getting punchy?

[ccho-mongodb]

Strange, my review seems to never have gone through. Sorry about that.
I'm certain that I typed a message, selected Approve, and submitted, but I don't see that message nor the approval.
Anyway, hope these are helpful.

[ccho-mongodb]

Would it be better to call it <JWT_token> similar to the fb and google examples? And is this a real credential that should be removed prior to commit?

[ccho-mongodb]

Since you've added Authentication to Anonymous and Email/Password headers, should you also update the rest of the authn method headers?

[ccho-mongodb]

Nitpick: I think we prefer past tense over past perfect. E.g. "If you enabled ..." instead of "If you have enabled..." Applies to all instances.

[nirinchev]

Final nitpick from me.

[nirinchev]

I don't think we should prefix the variable name with the provider type - in the iOS/Android docs, we're using user for all the examples. Since that will result in compilation errors here, you can add a scope around each snippet:

public async System.Threading.Tasks.Task LogsOnManyWays()
{
    {
        // :code-block-start: logon_anon
        var user = await app.LogInAsync(CredentialAnonymous());
        // :code-block-end:
        Assert.AreEqual(UserState.LoggedIn, user.State);
        await user.LogOutAsync();
    }

    {
        // :code-block-start: logon_EP
        var user = await app.LogInAsync(
            Credentials.EmailPassword("[email protected]", "shhhItsASektrit!"));
        // :code-block-end:
        Assert.AreEqual(UserState.LoggedIn, user.State);
        await user.LogOutAsync();
    }
    // ...
}