F# Azure storage docs #1079
F# Azure storage docs #1079
Conversation
This is part of an effort to document using F# for Azure.
Various updates to make the walkthrough run more smoothly
…e-docs into feature/fsharp-azure
Here's a small landing page
Write a small landing page
Let's prefer to use F# ``printf`` in samples.
Remove uses of Console.WriteLine
Move inline code snippets to F# script files and do line range embeds
|
Hi @sylvanc, I'm your friendly neighborhood .NET Foundation Pull Request Bot (You can call me DNFBOT). Thanks for your contribution! The agreement was validated by .NET Foundation and real humans are currently evaluating your PR. TTYL, DNFBOT; |
|
Open Publishing Build Service: The pull request content has been published and here are some changed files links of this time:
Status: Succeeded. |
|
Open Publishing Build Service: The pull request content has been published and here are some changed files links of this time:
Status: Succeeded. |
|
Open Publishing Build Service: The pull request content has been published and here are some changed files links of this time:
Status: SucceededWithWarning. Message: Warning occurred: Unable to resolve cross-reference "SafeNCryptKeyHandle", "SafeNCryptProviderHandle", "SafeNCryptSecretHandle".. |
|
Open Publishing Build Service: The pull request content has been published and here are some changed files links of this time:
Status: SucceededWithWarning. Message: Warning occurred: Unable to resolve cross-reference "SafeNCryptKeyHandle", "SafeNCryptProviderHandle", "SafeNCryptSecretHandle".. |
|
Open Publishing Build Service: The pull request content has been published and here are some changed files links of this time:
Status: SucceededWithWarning. Message: Warning occurred: Invalid file link:(~/docs/fsharp/using-fsharp-on-azure/Azure Quickstart Templates). Referenced by file: docs/fsharp/using-fsharp-on-azure/index.md at line: 101... |
|
@dsyme @sylvanc I took at a look at it and I think that the titles are a bit long. I propose renaming them to the following:
And for the sake of longevity, I've also been wondering if it's worthwhile to place them under a sub-TOC for Azure Storage. Example: Using F# on AzureAzure StorageBlob StorageFile StorageTable StorageQueue StorageWhen more documentation lands under the "Using F# on Azure" sub-TOC, then the lack of organization could make it difficult to find what you need. However, doing the above also might hurt discoverability. Thoughts? |
|
|
||
| To upload a file to a block blob, get a container reference and use it to get a block blob reference. Once you have a blob reference, you can upload any stream of data to it by calling the `UploadFromStream` method. This operation will create the blob if it didn't previously exist, or overwrite it if it does exist. | ||
|
|
||
| [!code-fsharp[BlobStorage](../../../samples/snippets/fsharp/azure/blob-storage.fsx#L55-L61)] |
There was a problem hiding this comment.
Why not use UploadFromFile instead of UploadFromStream here?
|
|
||
| [!code-fsharp[BlobStorage](../../../samples/snippets/fsharp/azure/blob-storage.fsx#L67-L80)] | ||
|
|
||
| As shown above, you can name blobs with path information in their names. This creates a virtual directory structure that you can organize and traverse as you would a traditional file system. Note that the directory structure is virtual only - the only resources available in Blob storage are containers and blobs. However, the storage client library offers a `CloudBlobDirectory` object to refer to a virtual directory and simplify the process of working with blobs that are organized in this way. |
There was a problem hiding this comment.
As shown above, you can name blobs with path information in their names.
Where was this shown? All I can see is creating a blob with the name myblob.txt, which has no path information.
| 2016/architecture/photo5.jpg | ||
| 2016/architecture/photo6.jpg | ||
| 2016/architecture/description.txt | ||
| 2016/photo7.jpg |
There was a problem hiding this comment.
This code block, and also others below, is syntax highlighted for F# in docfx, but shouldn't. If it's the same with the docs.MS template, this should be changed by using ```none instead of indentation.
There was a problem hiding this comment.
This will also be an issue for Loc later because they'll try to localize this text. All code should be fenced in our docs.
There was a problem hiding this comment.
@mairaw For now I'm adjusting to use
```none
Let me know if that's not enough (or make the adjustment after integration), thanks
|
|
||
| This example shows a flat blob listing, but you can also perform a hierarchical listing, by setting the `useFlatBlobListing` parameter of the `ListBlobsSegmentedAsync` method to `false`. | ||
|
|
||
| Because the sample method calls an asynchronous method, it must be prefaced with the `async` keyword, and it must return a `Task` object. The await keyword specified for the `ListBlobsSegmentedAsync` method suspends execution of the sample method until the listing task completes. |
There was a problem hiding this comment.
This looks like it's copy-pasted from the C# version of this document, but it does not apply to F#, since there is no await keyword and the function does not return a Task (and the return type is not specified anyway).
| // This overload allows control of the page size. You can return | ||
| // all remaining results by passing null for the maxResults | ||
| // parameter, or by calling a different overload. | ||
| let! ct = Async.CancellationToken |
There was a problem hiding this comment.
This line should probably be moved before the comment, so that it's clear what code the comment talks about.
|
|
||
| > mono nuget.exe update | ||
|
|
||
| # Referencing Assemblies |
There was a problem hiding this comment.
I think level 1 headings should be used only for the main heading of an article, not for headings inside articles.
There was a problem hiding this comment.
This needs to be fixed. @svick is right.
|
|
||
| For the tutorial, you'll enter your connection string in your script, like this: | ||
|
|
||
| [!code-fsharp[QueueStorage](../../../samples/snippets/fsharp/azure/queue-storage.fsx#L9-L13)] |
There was a problem hiding this comment.
I think this snippet shouldn't show the commented out CloudConfigurationManager.GetSetting code, it's already shown in the next snippet.
|
|
||
| [!code-fsharp[QueueStorage](../../../samples/snippets/fsharp/azure/queue-storage.fsx#L75-L76)] | ||
|
|
||
| ## Use Async-Await pattern with common Queue storage APIs |
There was a problem hiding this comment.
I don't think it's called "Async-Await pattern" in F#.
|
|
||
| To update an entity, retrieve it from the Table service, modify the entity object, and then save the changes back to the Table service using a `Replace` operation. This causes the entity to be fully replaced on the server, unless the entity on the server has changed since it was retrieved, in which case the operation will fail. This failure is to prevent your application from inadvertently overwriting changes from other sources. | ||
|
|
||
| [!code-fsharp[TableStorage](../../../samples/snippets/fsharp/azure/table-storage.fsx#L120-L127)] |
There was a problem hiding this comment.
This snippet and the one below seem to be one line off: they start with an empty line and end with with e ->.
|
|
||
| A table query can retrieve just a few properties from an entity instead of all of them. This technique, called projection, can improve query performance, especially for large entities. Here, you return only email addresses using `DynamicTableEntity` and `EntityResolver`. Note that projection is not supported on the local storage emulator, so this code runs only when you're using an account on the Table service. | ||
|
|
||
| [!code-fsharp[TableStorage](../../../samples/snippets/fsharp/azure/table-storage.fsx#L145-L156)] |
There was a problem hiding this comment.
This snippet is one line off too, it's missing the resolvedResults line.
|
|
||
| [!code-fsharp[BlobStorage](../../../samples/snippets/fsharp/azure/blob-storage.fsx#L21-L22)] | ||
|
|
||
| This will return a `CloudStorageAccount`. |
There was a problem hiding this comment.
nit: Something to keep in mind when writing articles in the future: present tense is preferred (no pun intended 😄). Like in this line where you could say "This returns..." or in the prerequisites section that says "you'll need an Azure Storage connection" instead of "You need ..."
|
|
||
| ## Upload a blob into a container | ||
|
|
||
| Azure Blob Storage supports block blobs and page blobs. In the majority of cases, a block blob is the recommended type to use. |
There was a problem hiding this comment.
nit: the majority of -> most
| 2016/architecture/photo5.jpg | ||
| 2016/architecture/photo6.jpg | ||
| 2016/architecture/description.txt | ||
| 2016/photo7.jpg |
There was a problem hiding this comment.
This will also be an issue for Loc later because they'll try to localize this text. All code should be fenced in our docs.
|
|
||
| [!code-fsharp[BlobStorage](../../../samples/snippets/fsharp/azure/blob-storage.fsx#L82-L89)] | ||
|
|
||
| and, depending on the current contents of your container, the results look like this: |
There was a problem hiding this comment.
Capital A in and
Should also say "the results look similar to this" since it depends on the contents of the container?
| do! loop null 1 | ||
| } | ||
|
|
||
| // Create some dummy data by upoading the same file over andd over again |
| manager: jbronsk | ||
| ms.date: 09/20/2016 | ||
| ms.topic: article | ||
| ms.prod: .net-core |
There was a problem hiding this comment.
Historically, F# has used the following values for these two fields, so it would be good to be consistent:
ms.prod: visual-studio-dev14
ms.technology: devlang-fsharp
We need to discuss how we want to do the rollup reports of languages in the future and discuss with the BI team to add new keywords.
| // Generate a shared access signature for a file or file share. | ||
| // | ||
|
|
||
| // Create a 24 hour read/write policy. |
|
|
||
| ### Copy files | ||
|
|
||
| You can copy a file to another file, a file to a blob, or a blob to a file. If you are copying a blob to a file, or a file to a blob, you *must* use a shared access signature (SAS) to authenticate the source object, even if you are copying within the same storage account. |
There was a problem hiding this comment.
Suggested rewriting:
You can copy a file to another file, a file to a blob, or a blob to a file ->
You can copy a file to another file or to a blob, or a blob to a file.
|
|
||
| ## Retrieve a single entity | ||
|
|
||
| You can write a query to retrieve a single, specific entity. Here, you use a `TableOperation` to specify the customer "Larry Buster". Instead of a collection, you get back a `Customer`. Specifying both the partition key and the row key in a query is the fastest way to retrieve a single entity from the Table service. |
There was a problem hiding this comment.
Does this name "Larry Buster" come from our approved fictitious names list from CELA?
| member val PhoneNumber = phone with get, set | ||
|
|
||
| let customer = | ||
| Customer("Larry", "Boomer", "larry@example.com", "425-555-0101") |
There was a problem hiding this comment.
Same as previous question re. names, does this name come from our pre-approved list?
There was a problem hiding this comment.
Thanks, I'm adjusting to use the same names as in the samples here https://azure.microsoft.com/en-us/documentation/articles/storage-dotnet-how-to-use-tables/ (not sure why we changed them)
|
Open Publishing Build Service: The pull request content has been published and here are some changed files links of this time:
Status: SucceededWithWarning. Message: Warning occurred: Invalid file link:(~/docs/fsharp/using-fsharp-on-azure/Azure Quickstart Templates). Referenced by file: docs/fsharp/using-fsharp-on-azure/index.md at line: 100... |
…ture/fsharp-azure
|
Hi @sylvanc, I'm your friendly neighborhood .NET Foundation Pull Request Bot (You can call me DNFBOT). Thanks for your contribution! The agreement was validated by .NET Foundation and real humans are currently evaluating your PR. TTYL, DNFBOT; |
|
Closed->reopened because there seemed to be an error with the build (which I don't think is related to your last commit, @dsyme). |
|
It seems all builds are broken somehow. I'll open a LSI. |
|
Open Publishing Build Service: The pull request content has been published and here are some changed files links of this time:
Status: SucceededWithWarning. Message: Warning occurred: Invalid file link:(~/docs/fsharp/using-fsharp-on-azure/Azure Quickstart Templates). Referenced by file: docs/fsharp/using-fsharp-on-azure/index.md at line: 100... |
|
Open Publishing Build Service: The pull request content has been published and here are some changed files links of this time:
Status: Succeeded. |
|
I think this looks good. Any objections to merging? |
|
There's one bad heading that needs to be fixed before merging this one. |
|
Open Publishing Build Service: The pull request content has been published and here are some changed files links of this time:
Status: Succeeded. |
|
Open Publishing Build Service: The pull request content has been published and here are some changed files links of this time:
Status: Succeeded. |
F# Azure storage docs
Summary
Add documentation and examples for using Blob, Queue, Table and File storage with F#.
Details
Existing Azure .NET documentation and examples are C# focused. This provides an F# programmer's view of Azure storage.
Suggested Reviewers
@dsyme @cartermp