<see cref="switch" />, for example, doesn't work - I get the compilation warning: XML comment on ... has syntactically incorrect cref attribute 'switch'
Context for those who are interested...
/// <summary>Provides base functionality for hand-coded abstractions of API method wrappers, mostly those that abstract over
/// parameters that are required to be JSON-encoded.</summary>
public class FacebookArgs : Dictionary<String, Object>
{
/// <summary>Initializes an instance of <see cref="FacebookArgs" />.</summary>
public FacebookArgs() { }
/// <summary>Intializes an instance of <see cref="FacebookArgs" />, that contains elements copied from <paramref name="dictionary "/>.</summary>
/// <param name="dictionary"></param>
public FacebookArgs(IDictionary<String, Object> dictionary)
: base(dictionary) { }
/// <summary>Gets or sets the value associated with the specified key.</summary>
/// <param name="key">The key of the value to get or set.</param>
/// <returns>The value associated with the specified key.</returns>
/// <remarks>This implementation hides the base indexer implementation such that specifying a key that does not exist returns null rather than throwing a <see cref="KeyNotFoundException" />.</remarks>
public new Object this[String key]
{
get
{
Object value;
if (this.TryGetValue(key, out value)) return value;
else return null;
}
set { base[key] = value; }
}
/// <summary>In derived classes, provides specialized serialization logic for specific properties contained in this object.</summary>
/// <param name="key">The key of the property to serialize.</param>
/// <param name="args">A reference to a dictionary of arguments that will be passed directly to a <see cref="FacebookRequest" /> object.</param>
/// <remarks>
/// <para>This method allows specialized serialization logic, such as JSON encoding, to be applied to specific properties.</para>
/// <para>To implement, use a <c>switch</c> (<c>Select</c> in VB.NET) statement to filter based on <paramref name="key" /> and provide the property-specific logic.
/// The resulting value should then be added to <paramref name="args" /> using the same <paramref name="key "/>.
/// </para>
/// <para>Properties that do not require additional processing (strings, integral values, etc) should be ignored.</para>
/// </remarks>
protected virtual void SerializeProperty(String key, ref IDictionary<String, Object> args) { }
/// <summary>Returns a dictionary of key/value pairs suitable to be passed a <see cref="FacebookRequest" /> object.</summary>
/// <returns>A dictionary of key/value pairs suitable to be passed a <see cref="FacebookRequest" /> object.</returns>
/// <remarks>This method calls the <see cref="SerializeProperty" /> for each key in the object, which allows property-specific processing
/// to be done on any property.</remarks>
/// <seealso cref="SerializeProperty" />
public IDictionary<String, Object> GetArgs()
{
IDictionary<String, Object> args = new Dictionary<String, Object>();
foreach (String key in this.Keys)
{
this.SerializeProperty(key, ref args);
if (!args.ContainsKey(key) && this[key] != null)
{
args.Add(key, this[key]);
}
}
return args;
}
}
The tag in question can be found in the <remarks> tag for SerializeProperty. I'm erring on the side of verbose documentation. I also plan on providing some <example>s, I just haven't gotten around to it yet.
cref is meant to refer to another member - a class, a method etc.
What would you expect it to link to in this case? In general, what do you want the overall effect to be?
According to this excellent XML doc guide, the <see> tag has an undocumented attribute langword:
<see langword="switch" />
Would that help you? It might be worth trying it just to see what it does.
If you just want to use a normal hyperlink, use href instead of cref:
<see href="http://msdn.microsoft.com/en-us/library/06tc147t.aspx">switch</see>
Related
I have done a bunch of looking and messing with code and I haven't found a way to do Linq Queries against the IReliableDictionary. I know it's not the same as standard IDictionary, but I was curious if anyone has had any luck. I'm starting to think it's just not possible unfortunately.
Currently, there's no normal way to do a linq query on a reliable dictionary. That being said, there are a few things you can do. As previously stated, the reason the CreateEnumerableAsync method exists is because service fabric pages reliable dictionaries to disk, but if you know that the underlying collection is small and you're okay with a performance hit, then the following class will work.
public static class AsyncEnumerableExtensions
{
/// <summary>
/// Converts the collection to a list
/// </summary>
/// <typeparam name="TValType">value type of the collection</typeparam>
/// <param name="enumerator">enumerator to convert</param>
/// <param name="ct">cancellation token for the async operations</param>
/// <param name="tx">tx to enforce that this is called in a transactional context</param>
/// <returns>a list containing all elements in the origin collection</returns>
public static async Task<IList<TValType>> ToListAsync<TValType>(
this IAsyncEnumerator<TValType> enumerator,CancellationToken ct, ITransaction tx)
{
IList<TValType> ret = new List<TValType>();
while (await enumerator.MoveNextAsync(ct).ConfigureAwait(false))
{
ret.Add(enumerator.Current);
}
return ret;
}
/// <summary>
/// Converts the collection to a list
/// </summary>
/// <typeparam name="TValType">value type of the collection</typeparam>
/// <param name="enumerator">enumerator to convert</param>
/// <param name="tx">tx to enforce that this is called in a transactional context</param>
/// <returns>a list containing all elements in the origin collection</returns>
public static Task<IList<TValType>> ToListAsync<TValType>(
this IAsyncEnumerator<TValType> enumerator, ITransaction tx)
{
return enumerator.ToListAsync(CancellationToken.None,tx);
}
/// <summary>
/// Converts the collection to a list
/// </summary>
/// <typeparam name="TValType">value type of the collection</typeparam>
/// <param name="enumerable">enumerator to convert</param>
/// <param name="ct">cancellation token for the async operations</param>
/// <param name="tx">tx to enforce that this is called in a transactional context</param>
/// <returns>a list containing all elements in the origin collection</returns>
public static Task<IList<TValType>> ToListAsync<TValType>(this IAsyncEnumerable<TValType> enumerable,
CancellationToken ct, ITransaction tx)
{
return enumerable.GetAsyncEnumerator().ToListAsync(ct,tx);
}
/// <summary>
/// Converts the collection to a list
/// </summary>
/// <typeparam name="TValType">value type of the collection</typeparam>
/// <param name="enumerable">enumerator to convert</param>
/// <param name="tx">tx to enforce that this is called in a transactional context</param>
/// <returns>a list containing all elements in the origin collection</returns>
public static Task<IList<TValType>> ToListAsync<TValType>(this IAsyncEnumerable<TValType> enumerable, ITransaction tx)
{
return enumerable.GetAsyncEnumerator().ToListAsync(tx);
}
}
You could also implement your own custom enumerators and extension methods to perform linq-query like operations on your data in an efficient manner. I have written a few that I would like to release but they need some polish first. I have a sneaking feeling that the service fabric team might already be on it, but if or when that happens your guess is as good as mine.
Looks like MS removed the ability to do linq queries in the latest SF release.
If you need to handle operations that are more involved than simple GetByKey(), you would need to explicitly create a local collection of it via the IReliableDictionary.CreateEnumerable() method, which you would then be able to query similar to the following example from the comments in this discussion :
IAsyncEnumerable<KeyValuePair<int, string="">> enumerable = await myDictionary.CreateEnumerableAsync(tx);
using (IAsyncEnumerator<KeyValuePair<int, string="">> e = enumerable.GetAsyncEnumerator())
{
while (await e.MoveNextAsync(cancellationToken).ConfigureAwait(false))
{
doSomething(e.Current);
}
}
This may not fit your scenario at all, but it seems that it's likely the only way to perform any kind of "advanced queries".
Right LINQ will not work with IAsyncEnumerator
var wgEnumerable = await voteDictionary.CreateEnumerableAsync(tx);
using(IAsyncEnumerator<KeyValuePair<string, int>> enumerator = wgEnumerable.GetAsyncEnumerator())
{
while(await enumerator.MoveNextAsync(CancellationToken.None))
{
//Do something
}
}
It is possible to use Async Linq after converting SerivceFabric's IAsyncEnumerable to a dotnet one.
Please refer to this answer:
Convert IReliableDictionary to IList
Is there a way to refer to the generic parameter of another class? I know I can do this with the current class using <typeparamref>.
One example would be when writing the documentation of an async methods. These return Task and people would commonly need to refer to TResult. Look at the "Return Value" on this page, for instance. They used <paramref> which obviously didn't do the job.
/// <returns>
/// A task that represents the asynchronous create operation.
/// The value of the <paramref name="TResult"/> parameter contains the number of documents created.
/// </returns>
public static async Task<int> CreateDocumentsAsync(string filename)
What shall I use instead of <paramref>?
I don't quite understand your question, so I'll post a couple of examples that may help you in regards to generics with the XML documentation.
/// <summary>
///
/// </summary>
/// <typeparam name="T"></typeparam>
/// <param name="obj"></param>
private void IDoSomething<T>(T obj)
{
}
/// <summary>
/// See type <see cref="T:My.Namespace.MyObject"/>
/// </summary>
private MyObject MyObj;
public class MyObject
{
}
I do not think that is possible (and the example with System.IO.Stream.ReadAsync seems to be an example of an invalid reference, see my comment to the question above).
The rest of this post is not an answer to your question but a suggestion for a more correct documentation:
In your concrete example, you could refer to the Result property inside Task<> instead of the impossible reference to the type parameter TResult itself. That is:
/// <returns>
/// The value of the <see cref="Task{_}.Result" /> property contains ...
/// </returns>
public static async Task<int> CreateDocumentsAsync(string filename)
If you do not like the _ hack above, you can do:
/// <returns>
/// The value of the <see cref="Task{Int32}.Result" /> property contains ...
/// </returns>
public static async Task<int> CreateDocumentsAsync(string filename)
Of course, you can refer to int with <see cref="Int32" />.
I need to fill some dropdown boxex from some reference data. i.e City List, Country List etc. I need to fill it in various webforms. I think, we should cache this data in our application so that, we don't hit database on every form. I am new to caching and ASP.Net. Please suggest me how to do this.
I always add the following class to all my projects which give me easy access to the Cache object. Implementing this, following Hasan Khan's answer would be a good way to go.
public static class CacheHelper
{
/// <summary>
/// Insert value into the cache using
/// appropriate name/value pairs
/// </summary>
/// <typeparam name="T">Type of cached item</typeparam>
/// <param name="o">Item to be cached</param>
/// <param name="key">Name of item</param>
public static void Add<T>(T o, string key, double Timeout)
{
HttpContext.Current.Cache.Insert(
key,
o,
null,
DateTime.Now.AddMinutes(Timeout),
System.Web.Caching.Cache.NoSlidingExpiration);
}
/// <summary>
/// Remove item from cache
/// </summary>
/// <param name="key">Name of cached item</param>
public static void Clear(string key)
{
HttpContext.Current.Cache.Remove(key);
}
/// <summary>
/// Check for item in cache
/// </summary>
/// <param name="key">Name of cached item</param>
/// <returns></returns>
public static bool Exists(string key)
{
return HttpContext.Current.Cache[key] != null;
}
/// <summary>
/// Retrieve cached item
/// </summary>
/// <typeparam name="T">Type of cached item</typeparam>
/// <param name="key">Name of cached item</param>
/// <param name="value">Cached value. Default(T) if item doesn't exist.</param>
/// <returns>Cached item as type</returns>
public static bool Get<T>(string key, out T value)
{
try
{
if (!Exists(key))
{
value = default(T);
return false;
}
value = (T)HttpContext.Current.Cache[key];
}
catch
{
value = default(T);
return false;
}
return true;
}
}
From other question of yours I read that you're using 3 layer architecture with dal, business and presentation layer.
So I assume that you have some data access class. Ideal thing to do would be to have a cached implementation of the same class and do caching in that.
Eg: If you have an interface IUserRepository then UserRepository class would implement it and add/delete/update entries in db via methods then you can also have CachedUserRepository which will contain instance of UserRepository object and on get methods it will first look into the cache against some key (derived from method parameters) and if the item is found then it will return it otherwise you call the method on internal object; get the data; add to cache and then return it.
Your CachedUserRepository will also have instance of cache object obviously. You can look at http://msdn.microsoft.com/en-us/library/18c1wd61(v=vs.85).aspx for details on how to use Cache object.
When specifying summary tag comments, is there a way with the <param> tag to note that a parameter is optional, ie. the client can supply a value or null, such as: <param name="Mime" optional="true">.
Googling has failed to provide me with a set list of attributes or allowed values.
/// <summary>
/// Sets data associated with instance
/// </summary>
/// <param name="Key">The key defining the data</param>
/// <param name="Value">The data</param>
/// <param name="Mime">The mime type of the data (optional)</param> <----- Mark as optional
Thanks
No, you can't. The only attribute being recognized by VS is the name, like that:
<param name="FileName" >The filename of the file to be loaded.</param>
The only thing that you can do - is to set xsl transform for your output document. But this won't have any effect on Intellisense.
You should provide an overload that omits the optional parameter:
/// <summary>
/// Sets data associated with the instance using the default media type.
/// </summary>
/// <param name="key">The key defining the data.</param>
/// <param name="value">The data.</param>
public void SetData(object key, object value)
{
SetData(key, value, null);
}
/// <summary>
/// Sets data associated with the instance using the specified media type.
/// </summary>
/// <param name="key">The key defining the data.</param>
/// <param name="value">The data.</param>
/// <param name="mime">The media type of the data.</param>
public void SetData(object key, object value, string mime)
{
...
}
Alternatively, you can declare the parameter as optional:
/// <summary>
/// Sets data associated with the instance.
/// </summary>
/// <param name="key">The key defining the data.</param>
/// <param name="value">The data.</param>
/// <param name="mime">The media type of the data.</param>
public void SetData(object key, object value, string mime = null)
{
...
}
You can use <remarks></remarks> tag. Doesn't exist special tag for optional params.
As the name states, I have no idea how to reference a dictionary indexer. Any help here? :)
FYI, I've tried:
<see cref="Item"/>
<see cref="Item(Int32)"/> //Highly doubted this would work.
<see cref="Item(TKey)"/>
<see cref="Item[TKey]"/>
You can use the full property syntax to reference indexers:
namespace ConsoleApplication1
{
/// <summary>
/// See indexer <see cref="P:ConsoleApplication1.MyDictionary`2.Item(`0)"/>
/// </summary>
/// <typeparam name="TKey"></typeparam>
/// <typeparam name="TValue"></typeparam>
public class MyDictionary<TKey, TValue>
{
/// <summary>
/// Indexer
/// </summary>
/// <param name="key"></param>
/// <returns></returns>
public TValue this[TKey key]
{
get { return default(TValue); }
set { }
}
}
}
You can check that the property was resolved properly by inspecting the generated XML file:
<doc>
<assembly>
<name>ConsoleApplication1</name>
</assembly>
<members>
<member name="T:ConsoleApplication1.MyDictionary`2">
<summary>
See <see cref="P:ConsoleApplication1.MyDictionary`2.Item(`0)"/>
</summary>
<typeparam name="TKey"></typeparam>
<typeparam name="TValue"></typeparam>
</member>
<member name="P:ConsoleApplication1.MyDictionary`2.Item(`0)">
<summary>
Indexer
</summary>
<param name="key"></param>
<returns></returns>
</member>
</members>
</doc>
Notice how the first P: matches the second one.
Finally, make sure it's working with Intellisense:
Update by Original Poster (myermian):
I did a little bit of digging and have discovered that the shortform of an indexer property is just "this". Ex: <see cref="this"/>
Try <see cref="P:Item(System.Int32)" /> (the name is Item, not Items)