<!-- 
RSS generated by JIRA (9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66) at Wed Feb 07 21:39:34 UTC 2024

It is possible to restrict the fields that are returned in this document by specifying the 'field' parameter in your request.
For example, to request only the issue key and summary append 'field=key&field=summary' to the URL of your request.
-->
<rss version="0.92" >
<channel>
    <title>MongoDB Jira</title>
    <link>https://jira.mongodb.org</link>
    <description>This file is an XML representation of an issue</description>
    <language>en-us</language>    <build-info>
        <version>9.7.1</version>
        <build-number>970001</build-number>
        <build-date>13-04-2023</build-date>
    </build-info>


<item>
            <title>[CSHARP-1428] InsertOneAsync use and documentation are incosistent</title>
                <link>https://jira.mongodb.org/browse/CSHARP-1428</link>
                <project id="10041" key="CSHARP">C# Driver</project>
                    <description>&lt;p&gt;The implementation of the &lt;tt&gt;InsertOneAsync&lt;/tt&gt; is not consistent with its documentation. The method signature of &lt;tt&gt;InsertOneAsync&lt;/tt&gt; is listed as &lt;tt&gt;Task InsertOneAsync(...&lt;/tt&gt;, and the documentation (both in the code and &lt;a href=&quot;http://api.mongodb.org/csharp/current/html/M_MongoDB_Driver_IMongoCollection_1_InsertOneAsync.htm&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;online&lt;/a&gt;) states:&lt;/p&gt;

&lt;p/&gt;
&lt;div id=&quot;syntaxplugin&quot; class=&quot;syntaxplugin&quot; style=&quot;border: 1px dashed #bbb; border-radius: 5px !important; overflow: auto; max-height: 30em;&quot;&gt;
&lt;table cellspacing=&quot;0&quot; cellpadding=&quot;0&quot; border=&quot;0&quot; width=&quot;100%&quot; style=&quot;font-size: 1em; line-height: 1.4em !important; font-weight: normal; font-style: normal; color: black;&quot;&gt;
		&lt;tbody &gt;
				&lt;tr id=&quot;syntaxplugin_code_and_gutter&quot;&gt;
						&lt;td  style=&quot; line-height: 1.4em !important; padding: 0em; vertical-align: top;&quot;&gt;
					&lt;pre style=&quot;font-size: 1em; margin: 0 10px;  margin-top: 10px;   width: auto; padding: 0;&quot;&gt;&lt;span style=&quot;color: black; font-family: &apos;Consolas&apos;, &apos;Bitstream Vera Sans Mono&apos;, &apos;Courier New&apos;, Courier, monospace !important;&quot;&gt;Return Value&lt;/span&gt;&lt;/pre&gt;
			&lt;/td&gt;
		&lt;/tr&gt;
				&lt;tr id=&quot;syntaxplugin_code_and_gutter&quot;&gt;
						&lt;td  style=&quot; line-height: 1.4em !important; padding: 0em; vertical-align: top;&quot;&gt;
					&lt;pre style=&quot;font-size: 1em; margin: 0 10px;   width: auto; padding: 0;&quot;&gt;&lt;span style=&quot;color: black; font-family: &apos;Consolas&apos;, &apos;Bitstream Vera Sans Mono&apos;, &apos;Courier New&apos;, Courier, monospace !important;&quot;&gt;Type: Task&lt;/span&gt;&lt;/pre&gt;
			&lt;/td&gt;
		&lt;/tr&gt;
				&lt;tr id=&quot;syntaxplugin_code_and_gutter&quot;&gt;
						&lt;td  style=&quot; line-height: 1.4em !important; padding: 0em; vertical-align: top;&quot;&gt;
					&lt;pre style=&quot;font-size: 1em; margin: 0 10px;   margin-bottom: 10px;  width: auto; padding: 0;&quot;&gt;&lt;span style=&quot;color: black; font-family: &apos;Consolas&apos;, &apos;Bitstream Vera Sans Mono&apos;, &apos;Courier New&apos;, Courier, monospace !important;&quot;&gt;The result of the insert operation.&lt;/span&gt;&lt;/pre&gt;
			&lt;/td&gt;
		&lt;/tr&gt;
			&lt;/tbody&gt;
&lt;/table&gt;
&lt;/div&gt;
&lt;p/&gt;

&lt;p&gt;This is inconsistent with the previous version of the API as well as with the original mongo api, which both return a &lt;tt&gt;WriteResult&lt;/tt&gt; (see &lt;a href=&quot;http://docs.mongodb.org/manual/tutorial/insert-documents/#insert-a-document-into-a-collection&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;this&lt;/a&gt; section of the tutorial). The importance of the &lt;tt&gt;WriteResult&lt;/tt&gt; is that it includes an error message that can be logged to help diagnose the issue. With just the &lt;tt&gt;Task&lt;/tt&gt;, there is not enough information to help determine why the insert had failed.&lt;/p&gt;</description>
                <environment></environment>
        <key id="232348">CSHARP-1428</key>
            <summary>InsertOneAsync use and documentation are incosistent</summary>
                <type id="4" iconUrl="https://jira.mongodb.org/secure/viewavatar?size=xsmall&amp;avatarId=14710&amp;avatarType=issuetype">Improvement</type>
                                            <priority id="4" iconUrl="https://jira.mongodb.org/images/icons/priorities/minor.svg">Minor - P4</priority>
                        <status id="6" iconUrl="https://jira.mongodb.org/images/icons/statuses/closed.png" description="The issue is considered finished, the resolution is correct. Issues which are closed can be reopened.">Closed</status>
                    <statusCategory id="3" key="done" colorName="success"/>
                                    <resolution id="9">Done</resolution>
                                        <assignee username="-1">Unassigned</assignee>
                                    <reporter username="pauldfaria">Paul Faria</reporter>
                        <labels>
                    </labels>
                <created>Thu, 1 Oct 2015 14:07:17 +0000</created>
                <updated>Fri, 2 Oct 2015 17:32:40 +0000</updated>
                            <resolved>Fri, 2 Oct 2015 17:32:40 +0000</resolved>
                                    <version>2.0</version>
                    <version>2.0.1</version>
                                                    <component>API</component>
                                        <votes>0</votes>
                                    <watches>1</watches>
                                                                                                                <comments>
                            <comment id="1050069" author="craiggwilson" created="Fri, 2 Oct 2015 17:32:34 +0000"  >&lt;p&gt;We should probably have better linking &lt;img class=&quot;emoticon&quot; src=&quot;https://jira.mongodb.org/images/icons/emoticons/smile.png&quot; height=&quot;16&quot; width=&quot;16&quot; align=&quot;absmiddle&quot; alt=&quot;&quot; border=&quot;0&quot;/&gt;.&lt;/p&gt;

&lt;p&gt;Thanks for the feedback. I&apos;m going to close this ticket. Feel free to re-open or comment further if necessary.&lt;/p&gt;

&lt;p&gt;Craig&lt;/p&gt;</comment>
                            <comment id="1050064" author="pauldfaria" created="Fri, 2 Oct 2015 17:31:36 +0000"  >&lt;p&gt;Hi Craig,&lt;/p&gt;

&lt;p&gt;Yes, this does. I apologize for the confusion on my part. Those didn&apos;t come up during my research.&lt;/p&gt;</comment>
                            <comment id="1050042" author="craiggwilson" created="Fri, 2 Oct 2015 17:12:56 +0000"  >&lt;p&gt;Hi Paul,&lt;/p&gt;

&lt;p&gt;I see you are looking at the quickstart guide on our mongodb docs site. While this is good for getting up and running, more comprehensive documentation is &lt;a href=&quot;http://mongodb.github.io/mongo-csharp-driver&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;here&lt;/a&gt;. For instance, there is a whole document on &lt;a href=&quot;http://mongodb.github.io/mongo-csharp-driver/2.0/reference/driver/error_handling&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;error handling&lt;/a&gt; with a section on &lt;a href=&quot;http://mongodb.github.io/mongo-csharp-driver/2.0/reference/driver/error_handling/#write-exceptions&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;write errors&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Does this satisfy your documentation needs?&lt;/p&gt;

&lt;p&gt;Craig&lt;/p&gt;</comment>
                            <comment id="1049941" author="pauldfaria" created="Fri, 2 Oct 2015 15:44:06 +0000"  >&lt;p&gt;Hi Craig,&lt;/p&gt;

&lt;p&gt;I&apos;ve talked it over with some members of my team, and we understand now why you removed the result from the return. I think the documentation surrounding this should be a little clearer, especially in the &lt;a href=&quot;https://docs.mongodb.org/getting-started/csharp/insert/&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;Getting Started Guid&lt;/a&gt; where it states, &quot;The [InsertOneAsync] method does not return a result&quot; (This conflicts with the documentation above). The text in this &lt;a href=&quot;https://www.mongodb.com/blog/post/introducing-20-net-driver&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;blog post&lt;/a&gt; about the release also states, &quot;InsertOneAsync returns a Task with no result value. When the insert is completed the Task will be in either a completed or faulted state depending on whether the insert was successful.&quot;&lt;/p&gt;

&lt;p&gt;I think it would be very useful to have documentation that showed recommended ways of handling the errors. It would clear up a lot of confusion around this, especially since placing try/catch around &lt;tt&gt;Task&lt;/tt&gt;&apos;s doesn&apos;t behave like a normal try/catch (due to everything being wrapped in an &lt;tt&gt;AggregationException&lt;/tt&gt;).&lt;/p&gt;</comment>
                            <comment id="1048635" author="craiggwilson" created="Thu, 1 Oct 2015 14:34:15 +0000"  >&lt;p&gt;Hi Paul,&lt;/p&gt;

&lt;p&gt;The return value in the previous version of the API was problematic. It would never actually contain errors because any errors would get thrown as an exception.&lt;/p&gt;

&lt;p&gt;In the case of InsertOneAsync, there is literally nothing to tell. Exceptions will be thrown for errors, and when there is no error, there is nothing to put in a result object. We could create an InsertOneResult class, but it would contain nothing.&lt;/p&gt;

&lt;p&gt;Thoughts?&lt;/p&gt;</comment>
                    </comments>
                    <attachments>
                    </attachments>
                <subtasks>
                    </subtasks>
                <customfields>
                                                                                                                                                                                                                        <customfield id="customfield_10011" key="com.atlassian.jira.plugin.system.customfieldtypes:radiobuttons">
                        <customfieldname>Backwards Compatibility</customfieldname>
                        <customfieldvalues>
                                <customfieldvalue key="10012"><![CDATA[Major Change]]></customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                <customfield id="customfield_15850" key="com.atlassian.jira.plugins.jira-development-integration-plugin:devsummary">
                        <customfieldname>Development</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    <customfield id="customfield_12550" key="com.pyxis.greenhopper.jira:gh-lexo-rank">
                        <customfieldname>Rank</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>2|hsdfyv:</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10558" key="com.pyxis.greenhopper.jira:gh-global-rank">
                        <customfieldname>Rank (Obsolete)</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>9223372036854775807</customfieldvalue>
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            </customfields>
    </item>
</channel>
</rss>