Azure Cognitive Services Forms Recognizer Client Library for .NET | Azure SDK for Networking (2023)

Azure Cognitive Services Form Recognizer is a cloud service that uses machine learning to recognize form fields, text, and tables in form documents. It contains the following features:

• Recognize custom forms: Recognize and extract form fields and other content from your custom forms using models you've trained with your own form types.
• Recognize form content: Recognize and extract tables, lines and words in form documents without having to train a model.
• Recognize Receipts – Recognize and extract common US receipt fields using a pre-trained receipt model.

source code|Package (NuGet)|API reference documentation|product documentation|samples

starter

install the package

Installer Azure Form Recognizer Client Library til .NET medNuGetName:

dotnet addon package Azure.AI.FormRecognizer --version 3.0.0

To use:This package version is for the v2.0 API version of the Azure Form Recognizer service.

previous requirements

• Eblue signature.
• An existing feature of Cognitive Services is the Form Recognizer.

Create a cognitive services or form recognition feature

Shape recognizer supports bothmultiservice access and single service. Create a Cognitive Services resource if you plan to access multiple Cognitive Services with a single endpoint/key. Just to access the Form Recognizer, you need to create a Form Recognizer resource.

You can create any resource using:

Option 1: portal azur.

Option 2: CLI to Azure.

Here's an example of how to create a shape-aware resource using the CLI:

# Create a new resource group to contain the shape-aware resource - # skip this step if you are using an existing resource group. group create --name--Location

# Opret en Cognitive Services az form aware account create \ --name\ --resource group\ --kind FormRecognizer \ --sku\ --Location\ --Sim

For more information on how to create the resource or how to get location and sku information, seeher.

authenticate client

To interact with the Form Recognizer service, you must create an instance of theFormRecognizerClientFormRecognizerClientthe classroom. you need onefull stopit is aAPI da keyto instantiate a client object.

Get API Key

You can get the endpoint and API key from the resource details onportal azur.

Alternatively, you can useCLI to Azureextract below to get Form Recognizer API key.

list of az cognitive services account keys --resource-group--name

Create FormRecognizerClient with AzureKeyCredential

Once you have the API key value, you need to create aAzureKeyCredentialAzureKeyCredential. With the terminal and the key credentials you can createFormRecognizerClientFormRecognizerClient:

endpoint of string = "";string apiKey = "";var credencial = new AzureKeyCredential(apiKey);var client = new FormRecognizerClient(new Uri(endpoint), credencial);

Crie FormRecognizerClient com a credencial til Azure Active Directory

AzureKeyCredentialAzureKeyCredentialauthentication is used in the examples in this getting started guide, but you can also authenticate with Azure Active Directory usingAzure Identity Library. Please note that regional endpoints do not support AAD authentication. Create onecustom subdomainfor your resource to use this type of authentication.

Use oAzure default credentialsprovider shown below or other credential providers that come with the Azure SDK installAzure.Identitypackage:

Azure.Identity installationspakke

you must also useregister a new AAD applicationywill allow accessto the Form Recognizer by assigning it"user of cognitive services"role of your service manager.

Set the AAD Application Client ID, Tenant ID, and Client Secret values ​​as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

endpoint of string = "";var cliente = new FormRecognizerClient(new Uri(endpoint), new DefaultAzureCredential());

Key concepts

FormRecognizerClientFormRecognizerClient

FormRecognizerClientFormRecognizerClientprovides operations for:

• Field and form content recognition using custom models trained to recognize your custom forms. These values ​​are returned in a collection ofrecognized formobjects. See an exampleRecognize custom forms.
• Recognize form content, including tables, lines and words, without the need to train a model. The form's contents are returned in a collection ofFormularsideobjects. See an examplerecognize content.
• Recognition of common US receipt fields using a pre-trained receipt model in the Form Recognizer service. These fields and metadata are returned in a collection ofrecognized formobjects. See an examplerecognize receipts.

Customer training form

Customer training formprovides operations for:

• Train custom models to recognize all fields and values ​​found in your custom forms. TOcustom form templateis returned specifying the form types the template recognizes and the fields it will extract for each form type.
• Train custom models to recognize specific fields and values ​​that you specify when you label your custom forms. TOcustom form templateis returned specifying the fields to be extracted by the model and the estimated accuracy for each field.
• Managing the models created on your account.
• Copy a custom template from one Form Recognizer function to another.

See examples oftrain a modelyManage custom templates.

Note that models can also be trained using a graphical user interface such asForm Recognizer Markup Tool.

long-term operations

Since parsing and forming form documents takes time, these operations are implemented aslong-term operations. Long-running operations consist of an initial request sent to the service to start an operation, followed by polling the service at intervals to determine whether the operation completed or failed, and if successful, to get the result.

For long-running operations on the Azure SDK, the client exposes aTo beginmethod that returns aOperation. You can use the extension methodWaitForCompletionAsync()wait for the operation to complete and get the result. An example code snippet is provided to illustrate the use of long-running operationsunder.

examples

The following section contains several code snippets that illustrate common patterns used in the Form Recognizer .NET API. Most of the snippets below use asynchronous service calls, but note that the Azure.AI.FormRecognizer package supports both synchronous and asynchronous APIs.

asynchronous examples

• recognize content
• Recognize custom forms
• recognize receipts
• train a model
• Manage custom templates

Examples of synchronization

• Manage custom templates synchronously

recognize content

Recognize text and table data, along with its bounding box coordinates, from documents.

FormPageCollection formPages = await client.StartRecognizeContentFromUriAsync(invoiceUri).WaitForCompletionAsync(); foreach(page FormPage in formPages){ Console.WriteLine($"Form page {page.PageNumber} has {page.Lines.Count}; lines; ; for (int i = 0; i < page. Lines. Count; i ++) { FormLine line = page. Lines [i]; Console.WriteLine($" Line {i} has {line.Words.Account} words{(line. Words.Account > 1 ? "s" : "")} and the text: '{line.Text}'". ) ; } for ( int i = 0 ; i < page . Tables . Count ; i ++ ) { FormTable table = page .Tables[i]; Console.WriteLine($"Table {i} has {table.RowCount} rows and {table.ColumnCount} columns."); foreach (cell FormTableCell in table.Cells) { Console.WriteLine ($" Cell({cell.RowIndex}, {cell.ColumnIndex}) contains the text: '{cell.Text}'."); } }}

Recognize custom forms

Recognize and extract form fields and other content from your custom forms using models that you train with your own form types.

string modelId = "";RecognizedFormCollection Forms = await client.StartRecognizeCustomFormsFromUriAsync(modelId, formUri).WaitForCompletionAsync();foreach (formulario RecognizedForm en formularios){ Console.WriteLine($"Forma de tipo:}form.FormTypeach); form.Fields.Values) { Console.WriteLine($"Campo '{field.Name}: "); if (field.LabelData != null) { Console.WriteLine($" Rótulo: '{field.LabelData.Text} "); } Console.WriteLine($" Valor: '{field.ValueData.Text}"); Console.WriteLine($" Confiança: '{field.Confidence}"); }}

recognize receipts

Recognize US sales receipt data using a pre-built template.

user (FileStream stream = new FileStream(receiptPath, FileMode.Open)){ RecognizedFormCollection receipts = wait client.StartRecognizeReceiptsAsync(stream).WaitForCompletionAsync(); // To see the list of supported fields returned by the service and their corresponding types, see: // https://aka.ms/formrecognizer/receiptfields foreach (RecognizedForm receipt in receipts) { FormField merchantNameField; if (receipt.Fields.TryGetValue("MerchantName", outmerchantNameField)) { if (MerchantNameField.Value.ValueType == FieldValueType.String) { string merchantName = merchantNameField.Value.AsString(); Console.WriteLine($"Merchant Name: '{merchantName}', with confidence {merchantNameField.Confidence}"); } } FormField transactionDateField; if (receipt.Fields.TryGetValue("TransactionDate", out transactionDateField)) { if (transactionDateField.Value.ValueType == FieldValueType.Date) { FechaHora transacciónFecha = transacciónDateField.Value.AsDate(); Console.WriteLine($"Close transaction: '{transactionDate}', with confidence {transactionDateField.Confidence}"); } } form field field elements; if (receipt.Fields.TryGetValue("Items", out itemsField)) { if (itemsField.Value.ValueType == FieldValueType.List) { foreach (FormField itemField in itemsField.Value.AsList()")) { Console.WriteLine( ") Item:"); if (itemField.Value.ValueType == FieldValueType.Dictionary) { IReadOnlyDictionaryitemFields = itemField.Value.AsDictionary(); campo de formulário campo de nome de elemento; if (itemFields.TryGetValue("Nom", ud itemNameField)) { if (itemNameField.Value.ValueType == FieldValueType.String) { string itemName = itemNameField.Value.AsString(); Console.WriteLine($" Navn: '{itemName}', com confiança {itemNameField.Confidence}"); } } FormField itemTotalPriceField; if (itemFields.TryGetValue("TotalPrice", ud itemTotalPriceField)) { if (itemTotalPriceField.Value.ValueType == FieldValueType.Float) { float itemTotalPrice = itemTotalPriceField.Value.AsFloat(); Console.WriteLine($" Preço total: '{itemTotalPrice}', com confiança {itemTotalPriceField.Confidence}"); } } } } } } campo de formulário campo total; if (recibo.Fields.TryGetValue("Total", out totalField)) { if (totalField.Value.ValueType == FieldValueType.Float) { float total = totalField.Value.AsFloat(); Console.WriteLine($"Total: '{total}', com confiança '{totalField.Confidence}'"); } } }}

train a model

Train a machine learning model on your own form types. The resulting model will be able to recognize values ​​of the shape types it was trained on.

// For this example, you can use the training forms found in the `trainingFiles` folder.// Upload the forms to your storage container and generate a SAS URL from the container.// For instructions on configuring forms For training on the Azure Storage Blob Container, see // https://docs.microsoft.com/azure/cognitive-services/form-recognizer/build-training-data-set#upload-your-training-dataFormTrainingClient client = new FormTrainingClient( new Uri( endpoint ), new AzureKeyCredential (apiKey));Model CustomFormModel = await client.StartTrainingAsync(new Uri(trainingFileUrl), useTrainingLabels: false).WaitForCompletionAsync();Console.WriteLine($"Custom Model Information :"); ( $" Model ID: {model.ModelId}");Console.WriteLine($" Model Status: {model.Status}");Console.WriteLine($" Training model started on: { model.TrainingStartedOn} "); Console .WriteLine($" Training model completed on: {model.TrainingCompletedOn}"); foreach (submodel CustomFormSubmodel in model.Submodels){ Console.WriteLine($"FormType submodel: { submodel.FormType}"); foreach(CustomFormModelField field in submodel.Fields.Values) { Console.Write($" FieldName: {field.Name}"); if (field.Label != null) { Console.Write($", FieldLabel: {field.Label}"); } Console.WriteLine(""); }}

Manage custom templates

Manage custom templates stored in your account.

FormTrainingClient client = new FormTrainingClient(new Uri(endpoint), new AzureKeyCredential(apiKey));// Check the number of templates in the FormRecognizer account and the maximum number of templates that can be stored.AccountProperties accountProperties = await client.GetAccountPropertiesAsync() ; Console.WriteLine($"Account has {accountProperties.CustomModelCount} models.");Console.WriteLine($"Can have a maximum of {accountProperties.CustomModelLimit} models."); // Display the models currently stored in the account . AsyncPageablemodels = client.GetCustomModelsAsync(); await foreach (CustomFormModelInfo modelInfo in models){ Console.WriteLine($"Custom Model Info:"); Console.WriteLine($" Model ID: {modelInfo.ModelId}"); Console.WriteLine($" Model Status: {modelInfo.Status}"); Console.WriteLine($" Training model started on: {modelInfo.TrainingStartedOn}"); Console.WriteLine($" Training model completed on: : {modelInfo.TrainingCompletedOn}");}// Create a new model to store in the model accountCustomFormModel = await client.StartTrainingAsync(new Uri(trainingFileUrl), useTrainingLabels: false) . WaitForCompletionAsync();// Get the model that was just createdCustomFormModel modelCopy = await client.GetCustomModelAsync(model.ModelId);Console.WriteLine($"Custom model {modelCopy.ModelId} recognizes the following form types:"); foreach (CustomFormSubmodelSub submodel in modelCopy.Submodels){ Console.WriteLine($"Submodel form type: {submodel.FormType}"); foreach(CustomFormModelField field in submodel.Fields.Values) { Console.Write($" FieldName: {field.Name}"); if (field.Label != null) { Console.Write($", FieldLabel: {field.Label}"); } Console.WriteLine(""); }}// Delete model from account.wait for customer.DeleteModelAsync(model.ModelId);

Manage custom templates synchronously

Manage custom models stored in your account with a synchronous API. Note that we still make an asynchronous call toWaitForCompletionAsyncfor training, as this method does not have a synchronous counterpart. For more information on long-term operations, seelong-term operations.

Client FormTrainingClient = new FormTrainingClient(new Uri(endpoint), new AzureKeyCredential(apiKey)); // Check the number of templates in the FormRecognizer account and the maximum number of templates that can be stored.AccountProperties accountProperties = client.GetAccountProperties() ; Console.WriteLine($"Account has {accountProperties.CustomModelCount} models."); Console.WriteLine($"You can have a maximum of {accountProperties.CustomModelLimit} models.");// List the first ten or fewer models currently stored in the account.PagableTemplates= client.GetCustomModels(); foreach (CustomFormModelInfo modelInfo in models.Take(10)){ Console.WriteLine($"Custom Model Info:"); Console.WriteLine($" Model ID: {modelInfo.ModelId}"); Console.WriteLine($" Model Status: {modelInfo.Status}"); Console.WriteLine($" Training model started on: {modelInfo.TrainingStartedOn}"); Console.WriteLine($" Training model completed on: {modelInfo.TrainingCompletedOn}");} // Create a new model to store in the model accountCustomFormModel = await client.StartTraining(new Uri(trainingFileUrl), useTrainingLabels: false). WaitForCompletionAsync();// Get the model that was just created. modelCopy.Submodels){ Console.WriteLine($"Submodel form type: {submodel.FormType}"); foreach(CustomFormModelField field in submodel.Fields.Values) { Console.Write($" FieldName: {field.Name}"); if (field.Label != null) { Console.Write($", FieldLabel: {field.Label}"); } Console.WriteLine(""); }}// Delete the model from account.client.DeleteModel(model.ModelId);

Problem solving

In general

When interacting with the Cognitive Services Form Recognizer client library through the .NET SDK, any errors returned by the service will result in aRequestFailedExceptionwith the same HTTP status code returned byAPI RESTorder.

For example, if you upload a receipt image with auri, a400an error indicating "Bad Request" is returned.

prøv{ Recibos de RecognizedFormCollection = esperar cliente.StartRecognizeReceiptsFromUri(nuevo Uri("http://invalid.uri")).WaitForCompletionAsync();}catch (RequestFailedException e){ Console.WriteLine(e.}ToString(e.}ToString)

You will notice that additional information is logged, such as the client request ID of the operation.

Message: Azure.RequestFailedException: Service request failed. Status: 400 (Bad Request) Content: {"error":{"code":"FailedToDownloadImage","innerError":{"requestId":"8ca04feb-86db-4552-857c-fde903251518"},"message":" Could not download image from incoming URL."}}Headers: Transport-Encoding: x-envoy-upstream-service-time fragmented: REMOVED apim-request-id: REMOVED Strict-Transport-Security: REMOVED X-Content-Type -Options: REMOVED Date: Monday 20 Apr 2020 22:48:35 GMT Content-Type: application/json; charset = utf-8

Configure console logging

The easiest way to view logs is to enable console logging. To create an Azure SDK log listener that sends messages to the console, use the AzureEventSourceListener.CreateConsoleLogger method.

// Configure a listener to listen for logged events. Using the listener AzureEventSourceListener = AzureEventSourceListener.CreateConsoleLogger();

For more information about other logging mechanisms, seediagnostic tests.

Next step

Examples showing how to use the Cognitive Services Form Recognizer library are available in this GitHub repository. Examples are given for each main functional area:

• Recognize form content
• Recognize custom forms
• recognize receipts
• train a model
• Manage custom templates
• Copy a custom template between Form Recognizer functions

contributes

This project accepts contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA), which states that you have the right to grant us the right to use your contribution. For more details, visitcla.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether to grant a CLA and decorate the PR accordingly (eg tag, comment). Just follow the instructions from the bot. You only need to do this once for all repositories using our CLA.

This project passedMicrosoft Open Source Code of Conduct. For more information, seeFrequently asked questions about the Code of Conductthe contactopencode@microsoft.comwith additional questions or comments.